FormatterKit 技术文档

1. 安装指南

1.1 使用 CocoaPods 安装

要在项目中通过 CocoaPods 安装 FormatterKit，请在 Podfile 中添加以下行：

pod 'FormatterKit', '~> 1.9.0'

然后运行以下命令来下载库并将其集成到 Xcode 项目中：

pod install

1.2 使用 Carthage 安装

要在 Xcode 项目中通过 Carthage 使用 FormatterKit，请在 Cartfile 中指定：

github "FormatterKit/FormatterKit" ~> 1.9.0

然后运行以下命令来构建框架，并将构建的 FormatterKit.framework 拖入 Xcode 项目中：

carthage update

2. 项目使用说明

FormatterKit 是一个包含多个 NSFormatter 子类的集合，用于处理地址、数组、颜色、位置、距离、方向、名称、序数、时间间隔和信息单位等格式化需求。每个格式化器都抽象了复杂的业务逻辑，使开发者能够专注于应用程序的其他重要方面。

2.1 主要功能

• 地址格式化：根据不同地区的格式生成地址字符串。
• 数组格式化：将数组元素格式化为逗号分隔的列表。
• 颜色格式化：支持 RGB、CMYK 和 HSL 格式的颜色表示。
• 位置、距离和方向格式化：显示位置、距离、方向和速度，支持公制和英制单位。
• 名称格式化：根据当前语言环境正确格式化个人姓名。
• 序数格式化：将基数转换为序数，支持多种语言。
• 时间间隔格式化：显示两个 NSDate 对象之间的相对时间。
• 信息单位格式化：以人类可读的方式表示比特和字节。

2.2 示例项目

可以通过在 Xcode 中构建并运行 FormatterKit Example 项目来查看 FormatterKit 组件的示例。

3. 项目 API 使用文档

3.1 TTTAddressFormatter

TTTAddressFormatter 用于根据不同地区的格式生成地址字符串。

示例用法

TTTAddressFormatter *addressFormatter = [[TTTAddressFormatter alloc] init];
NSLog(@"%@", [addressFormatter stringFromAddressWithStreet:street locality:locality region:region postalCode:postalCode country:country]);

3.2 TTTArrayFormatter

TTTArrayFormatter 提供了一个国际化支持的数组格式化器，可以替代 NSArray -componentsJoinedByString:。

示例用法

NSArray *list = [NSArray arrayWithObjects:@"Russel", @"Spinoza", @"Rawls", nil];
TTTArrayFormatter *arrayFormatter = [[TTTArrayFormatter alloc] init];
[arrayFormatter setUsesAbbreviatedConjunction:YES]; // 使用 '&' 代替 'and'
[arrayFormatter setUsesSerialDelimiter:NO]; // 省略 Oxford Comma
NSLog(@"%@", [arrayFormatter stringFromArray:list]); // 输出: "Russell, Spinoza & Rawls"

3.3 TTTColorFormatter

TTTColorFormatter 提供颜色的字符串表示，支持 RGB、CMYK 和 HSL 格式。

示例用法

TTTColorFormatter *colorFormatter = [[TTTColorFormatter alloc] init];
NSString *RGB = [colorFormatter RGBStringFromColor:[UIColor orangeColor]];

3.4 TTTLocationFormatter

TTTLocationFormatter 用于格式化位置、距离、方向、速度和速度，支持公制和英制单位。

示例用法

TTTLocationFormatter *locationFormatter = [[TTTLocationFormatter alloc] init];
CLLocation *austin = [[CLLocation alloc] initWithLatitude:30.2669444 longitude:-97.7427778];
CLLocation *pittsburgh = [[CLLocation alloc] initWithLatitude:40.4405556 longitude:-79.9961111];

// 公制单位下的距离和方向
NSLog(@"%@", [locationFormatter stringFromDistanceAndBearingFromLocation:pittsburgh toLocation:austin]);
// 输出: "2,000 km Southwest"

// 英制单位下的距离和方向
[locationFormatter.numberFormatter setMaximumSignificantDigits:4];
[locationFormatter setBearingStyle:TTTBearingAbbreviationWordStyle];
[locationFormatter setUnitSystem:TTTImperialSystem];
NSLog(@"%@", [locationFormatter stringFromDistanceAndBearingFromLocation:pittsburgh toLocation:austin]);
// 输出: "1,218 miles SW"

3.5 TTTNameFormatter

TTTNameFormatter 根据 AddressBook 框架的国际标准格式化姓名。

示例用法

TTTNameFormatter *nameFormatter = [[TTTNameFormatter alloc] init];
NSString *frenchName = [nameFormatter stringFromPrefix:nil firstName:@"Guillaume" middleName:@"François" lastName:@"Antoine" suffix:@"Marquis de l'Hôpital"];
NSLog(@"%@", frenchName);
// 输出: "Guillaume François Antoine Marquis de l'Hôpital"

3.6 TTTOrdinalNumberFormatter

TTTOrdinalNumberFormatter 将基数转换为序数，支持多种语言。

示例用法

TTTOrdinalNumberFormatter *ordinalFormatter = [[TTTOrdinalNumberFormatter alloc] init];
NSLog(@"%@", [ordinalFormatter stringFromNumber:@1]); // 输出: "1st"

4. 项目安装方式

FormatterKit 可以通过 CocoaPods 或 Carthage 进行安装，具体步骤请参考 安装指南。