ZodiacKit

ZodiacKit 是一个 Swift 包，允许您根据给定的日期获取西方和中国十二生肖的信息。它为处理占星数据的应用程序提供了一个简单、高效且易于集成的解决方案。

描述

ZodiacKit 包含一个 ZodiacService 结构体，可帮助您检索西方和中国十二生肖。然后，它可以根据 Date 查找十二生肖。

如果发现不一致，此包会验证生肖日期范围并抛出相关错误。错误包括日期范围重叠、缺失日期、重复的十二生肖和缺失的十二生肖。

WesternZodiacSign 和 ChineseZodiacSign 枚举是一种易于阅读和访问的方式，可以在 Swift 语言中表示相关的十二生肖。

它们包括各种属性，例如生肖名称、其世俗元素、表情符号表示、阴阳等等。在开发处理十二生肖的应用程序时，这可能是一个有价值的资源。

安装

ZodiacKit 包使用 Swift Package Manager (SPM) 便于添加。按照以下步骤将其添加到您的项目

在 Xcode 中，点击 File -> Swift Packages -> Add Package Dependency。
在搜索栏中，键入 https://github.com/markbattistella/ZodiacKit，然后点击 Next。
指定要使用的版本。您可以选择确切的版本，使用最新的版本，或设置版本范围，然后点击 Next。
最后，选择要在其中使用 ZodiacKit 的目标，然后点击 Finish。

注意

v1.x 到 v2.x 有一些重大更改 - 主要是在命名方面，由于添加了额外的十二生肖，Sign 现在以 Western 或 Chinese 作为前缀。

用法

记住导入 ZodiacKit 模块

import ZodiacKit

基本用法

ZodiacKit 包的默认用法非常简单。这是一个示例

let zodiacService = try ZodiacService()
let dateComponents = DateComponents(year: 1991, month: 5, day: 29)
let birthDate = Calendar.current.date(from: dateComponents)

let westernZodiacSign = try? zodiacService.getWesternZodiac(from: birthDate!)
let chineseZodiacSign = try? zodiacService.getChineseZodiac(from: birthDate!)

// westernZodiacSign.name: Gemini 
// chineseZodiacSign.name: Goat

这将根据提供的日期为您提供相应的信息和属性。

然后，您可以使用 WesternZodiacSign 和 ChineseZodiacSign 的属性来获取有关这些十二生肖的信息。

自定义日期范围（仅限西方）

如果您想使用自定义的十二生肖日期范围而不是默认值（对于 WesternZodiacSign），您可以通过在 ZodiacService 初始化期间传递 WesternZodiac 结构体的自定义数组来实现。

let customZodiacs: [WesternZodiac] = [
  Zodiac(
    sign: .aquarius,
    startDate: .init(day: 22, month: 1),
    endDate: .init(day: 19, month: 2)
  ),
  // ...
]

let zodiacService = try? ZodiacService(zodiacs: customZodiacs)

应用内使用

UIKit

这是一个如何在 UIKit UIViewController 中使用 ZodiacKit 的示例。

import UIKit
import ZodiacKit

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()

        do {
            let zodiacService = try ZodiacService()
            let dateComponents = DateComponents(year: 1991, month: 5, day: 29)
            let birthDate = Calendar.current.date(from: dateComponents)

            let westernZodiacSign = try zodiacService.getWesternZodiac(from: birthDate!)
            let chineseZodiacSign = try zodiacService.getChineseZodiac(from: birthDate!)

            // Use signs...
            print(westernZodiacSign.name) // Gemini
            print(chineseZodiacSign.name) // Goat
        } catch {
            print("Failed to get zodiac sign: \(error)")
        }
    }
}

SwiftUI

以下是在 SwiftUI 视图中使用 ZodiacKit 的示例。

import SwiftUI
import ZodiacKit

struct ContentView: View {
    @State private var westernZodiacSign: WesternZodiacSign?
    @State private var chineseZodiacSign: ChineseZodiacSign?

    var body: some View {
        VStack {
            if let westernSign = westernZodiacSign,
               let chineseSign = chineseZodiacSign {
                Text("Your zodiac sign is \(westernSign.name)")
                Text("Your Chinese Zodiac sign is: \(chineseSign.name)")
            } else {
                Text("Failed to get zodiac sign")
            }
        }.onAppear {
            do {
                let zodiacService = try ZodiacService()
                let dateComponents = DateComponents(year: 1991, month: 5, day: 29)
                let birthDate = Calendar.current.date(from: dateComponents)

                westernZodiacSign = try zodiacService.getWesternZodiac(from: birthDate!)
                chineseZodiacSign = try zodiacService.getChineseZodiac(from: birthDate!)
            } catch {
                print("Failed to get zodiac sign: \(error)")
            }
        }
    }
}

AppKit

这是如何在 AppKit NSViewController 中使用 ZodiacKit 的示例。

import AppKit
import ZodiacKit

class ViewController: NSViewController {
    override func viewDidLoad() {
        super.viewDidLoad()

        do {
            let zodiacService = try ZodiacService()
            let dateComponents = DateComponents(year: 1991, month: 5, day: 29)
            let birthDate = Calendar.current.date(from: dateComponents)

            let westernZodiacSign = try zodiacService.getWesternZodiac(from: birthDate!)
            let chineseZodiacSign = try zodiacService.getChineseZodiac(from: birthDate!)

            // Use signs...
            print(westernZodiacSign.name) // Gemini
            print(chineseZodiacSign.name) // Goat
        } catch {
            print("Failed to get zodiac sign: \(error)")
        }
    }
}

默认日期范围

默认情况下，此包对西方格式的每个十二生肖使用以下日期范围

十二生肖	开始日期范围	结束日期范围
水瓶座	1月20日	2月18日
双鱼座	2月19日	3月20日
白羊座	3月21日	4月19日
金牛座	4月20日	5月20日
双子座	5月21日	6月20日
巨蟹座	6月21日	7月22日
狮子座	7月23日	8月22日
处女座	8月23日	9月22日
天秤座	9月23日	10月22日
天蝎座	10月23日	11月21日
射手座	11月22日	12月21日
摩羯座	12月22日	1月19日

验证

ZodiacKit 包含内置验证，以确保提供的十二生肖数据的一致性和正确性。

在 ZodiacService 初始化期间，包会执行多项检查

日期范围重叠

该包会检查以确保所有十二生肖的日期范围不重叠。重叠的日期范围可能会导致在确定特定日期的十二生肖时产生不明确的结果。

缺失日期

一年中的所有日期必须包含在定义的十二生肖中。如果日期范围有任何空白，ZodiacKit 将抛出错误。

重复的十二生肖

该包确保每个十二生肖都是唯一的并且只定义一次。如果使用不同的日期范围多次定义相同的生肖，则会抛出错误。

缺失的十二生肖

必须表示所有十二个十二生肖。如果缺少任何一个，将抛出错误。

无效日期

该包会检查任何十二生肖的开始或结束日期是否无效（例如，2 月 30 日）。如果找到无效日期，则会抛出错误。

这些验证有助于确保您正在使用的十二生肖数据是准确的，并且该服务将返回正确的结果。如果这些验证中的任何一个失败，ZodiacService 初始化将抛出错误。在您的应用程序中捕获和处理这些错误以确保流畅的用户体验至关重要。

这是一个如何在 ZodiacService 初始化期间处理错误的示例

do {
    let zodiacService = try ZodiacService()
    // Use zodiacService...
} catch {
    print("Failed to initialize ZodiacService: \(error)")
}

抛出的错误将属于 ZodiacService.ZodiacError 类型，您可以使用它在您的应用程序中提供更具体的错误处理或消息传递。

错误处理

ZodiacKit 执行多项验证以确保数据的一致性和正确性。这是一个包含 ZodiacService 可能抛出的每个 ZodiacError 的表格

错误	描述
`dateRangeOverlap`	当十二生肖的日期范围重叠时抛出。
`missingDates`	当存在没有十二生肖涵盖的缺失日期时抛出。
`duplicatedSigns`	当同一个十二生肖被定义多次时抛出。
`missingSigns`	当未表示所有十二生肖时抛出。
`invalidDates`	当使用公历中不存在的日期（例如，2 月 30 日）时抛出。

每个错误都是一个枚举案例，并带有相关数据。例如，dateRangeOverlap 错误带有两个具有重叠日期范围的 Zodiac 结构体。您可以使用此数据来提供详细的错误消息。

这是一个处理 dateRangeOverlap 错误的示例

do {
    let zodiacService = try ZodiacService()
    // Use zodiacService...
} catch ZodiacService.ZodiacError.dateRangeOverlap(let firstZodiac, let secondZodiac) {
    print("\(firstZodiac.sign) and \(secondZodiac.sign) have overlapping date ranges.")
} catch {
    print("An unknown error occurred.")
}

属性

`WesternZodiacSign`

属性	描述	可能的值
`name`	十二生肖的大写名称，直接从枚举案例值派生。	水瓶座、白羊座、巨蟹座、摩羯座、双子座、狮子座、天秤座、双鱼座、射手座、天蝎座、金牛座、处女座
`worldlyElement`	表示与十二生肖相关的四种经典元素之一（空气、火焰、水、土），表明该星座的性质和气质。	风（水瓶座、双子座、天秤座），火（白羊座、狮子座、射手座），水（巨蟹座、天蝎座、双鱼座），土（摩羯座、金牛座、处女座）
`worldlyElementEmoji`	一个象征着与十二生肖相关的世俗元素的表情符号（空气为💨，火焰为🔥，水为💧，地球为🪨）。	💨（空气），🔥（火焰），💧（水），🪨（土）
`emoji`	表示十二生肖的占星符号表情符号（例如，白羊座为♈️）。	♒️, ♈️, ♋️, ♑️, ♊️, ♌️, ♎️, ♓️, ♐️, ♏️, ♉️, ♍️
`color`	传统上与十二生肖相关的颜色，使用系统颜色以与 UI 元素兼容（例如，水瓶座为 `.systemBlue`）。	`.systemBlue`, `.systemRed`, `.systemPurple`, `.black`, `.systemYellow`, `.systemOrange`, `.systemPink`, `.systemGreen`, `.systemBrown`, `.magenta`, `.gray`
`rulingPlanetName`	统治十二生肖的行星或天体的名称，反映了某些性格特征和方面（例如，白羊座的“火星”）。	火星、金星、水星、月亮、太阳、木星、土星、天王星、海王星、冥王星
`rulingPlanet`	与十二生肖相关的统治行星或天体的占星符号（例如，火星为“♂”，白羊座的统治行星）。	♂（火星）、♀（金星）、☿（水星）、☽（月亮）、☉（太阳）、♃（木星）、♄（土星）、♅（天王星）、♆（海王星）、♇（冥王星）

`ChineseZodiacSign`

属性	描述	可能的值
`name`	十二生肖动物的大写名称，直接从枚举案例值派生。	鼠、牛、虎、兔、龙、蛇、马、羊、猴、鸡、狗、猪
`fixedElement`	表示为每个十二生肖固定的元素（木、火、土、金、水），象征着该星座本质的核心方面。	水（鼠、猪），土（牛、龙、羊、狗），木（虎、兔），火（蛇、马），金（猴、鸡）
`fixedElementEmoji`	一个象征着与十二生肖相关的固定元素的表情符号（水为💧，土为🪨，木为🪵，火为🔥，金属为🔗）。	💧（水）、🪨（土）、🪵（木）、🔥（火）、🔗（金属）
`emoji`	中国十二生肖动物的表情符号表示（例如，牛为🐂）。	🐀, 🐂, 🐅, 🐇, 🐉, 🐍, 🐎, 🐐, 🐒, 🐓, 🐕, 🐖
`yinYang`	表示星座的阴或阳性质，反映了中国占星学中星座固有的能量和哲学。	阴（鼠、牛、虎、兔、蛇、猴、鸡、猪），阳（龙、马、羊、狗）

特性和兼容性

一个描述性的特征列表，归因于十二生肖，以及与该星座最兼容的其他十二生肖。

生肖	特性	兼容性
`鼠`	智力、适应性、机智、魅力、艺术性、社交性。	`龙`、`猴`
`牛`	忠诚、可靠、彻底、力量、合理性、稳重、决心。	`鼠`、`鸡`、`蛇`
`虎`	热情、勇气、雄心、领导力、自信、魅力。	`马`、`狗`
`兔`	值得信赖、同情心、谦虚、外交、真诚、社交性。	`羊`、`猪`、`狗`
`龙`	幸运、灵活性、古怪、想象力、艺术性、灵性。	`鸡`、`鼠`、`猴`
`蛇`	哲学、有条理、聪明、直觉、优雅、细心、果断。	`牛`、`鸡`
`马`	适应性、忠诚、勇气、雄心、智力、冒险、强大的自由。	`虎`、`狗`、`羊`
`羊`	想象力、创造力、同情心、慷慨、诚实、坚持、温柔。	`兔`、`马`、`猪`
`猴`	智力、适应性、机智、魅力、运气、灵活性。	`鼠`、`龙`
`鸡`	诚实、精力、智力、炫耀、灵活性、多样性、自信。	`牛`、`龙`、`蛇`
`狗`	忠诚、真诚、可靠、智力、社交性、理解、耐心。	`虎`、`兔`、`马`
`猪`	诚实、真诚、宽容、勤奋、慷慨、乐观、和平。	`羊`, `兔`

重要提示

此包与区域设置无关，并假定使用公历。
处理 ZodiacService 时，错误处理至关重要。请务必捕获并正确处理可能抛出的任何异常。

贡献

非常欢迎贡献。如果您发现错误或有增强功能的想法，请开启一个 issue 或提供 pull request。在做出贡献时，请遵循当前代码库中的代码风格。

许可证

Zodiac Signs 包在 MIT 许可下发布。有关更多信息，请参阅 LICENSE。