FormatterKit 1.9.0

FormatterKit 1.9.0

×

测试已测试✓
语语言 Obj-CObjective C
许可证 MIT
发布上次发布2019年7月

由 Mattt，Victor Ilyukevich 维护。

FormatterKit 1.9.0

FormatterKit

FormatterKit 是一个用于信息单位、距离和相对时间间隔等任务的良好构建的 NSFormatter 子类集合。每个格式化工具都封装了其对应领域的复杂业务逻辑，这样您可以专注于应用程序更重要的一面。

简而言之，如果您手动格式化以下内容（使用字符串插值或其他类似技术），请使用这个库

  • 地址：使用组件创建格式化的地址字符串（例如，221b Baker St / Paddington / Greater London / NW1 6XE / United Kingdom）
  • 数组：以逗号分隔的列表形式显示 NSArray 元素（例如，"Russell, Spinoza & Rawls"）
  • 颜色：以 RGB、CMYK 和 HSL 格式展示 ROY G. BIV。例如 #BADF00D，rgb(255, 100, 42)）
  • 位置、距离和方向：以公制或英制单位显示 CLLocationDistance，CLLocationDirection 和 CLLocationSpeed，例如 "240ft Northwest" / "45 km/h SE"
  • 名称：根据当前区域设置和源语言正确格式化个人姓名，例如 "山田花子"（日本姓"花子"（Hanako）和名"山田"（Yamada））
  • 序数词：将基数 NSNumber 对象转换为大多数主要语言中的序数，例如 "1st, 2nd, 3rd" / "1ère, 2ème, 3ème"
  • 时间间隔：显示两个任意 NSDate 对象之间的相对时间距离，例如 "3 minutes ago" / "yesterday"
  • 信息单位：对比特和字节数量的指数表示，例如 "2.7 MB"
  • URL 请求：为任意 NSURLRequest 打印出 cURL 或 Wget 命令等效，例如 curl -X POST "https://www.example.com/" -H "Accept: text/html"

FormatterKit，以及 TransformerKit 和 InflectorKit，为操作用户界面内容提供了设计良好的 API。

本地化

FormatterKit 已经完全国际化，以下地区提供了 .strings 文件：

  • 加泰罗尼亚语（ca）
  • 中文（简体）（zh_Hans）
  • 中文（繁体）（zh_Hant）
  • 捷克语（cs）
  • 丹麦语（da）
  • 荷兰语（nl）
  • 英语（en）
  • 法语（fr）
  • 德语（de）
  • 希腊语（el）
  • 希伯来语（he）
  • 匈牙利语（hu）
  • 印尼语（id）
  • 意大利语（it）
  • 韩语（ko）
  • 挪威语（帛恩眉尔）（nb）
  • 挪威语（纽诺斯克）（nn）
  • 波兰语（pl）
  • 葡萄牙语（巴西）（pt_BR）
  • 俄语（ru）
  • 西班牙语（es）
  • 瑞典语（sv）
  • 土耳其语（tr）
  • 乌克兰语（uk）
  • 越南语（vi）

如果您想贡献另一个本地化版本，请随意提交一个新的pull request。

示例

在Xcode中构建和运行 FormatterKit Example 项目，查看可用的 FormatterKit 组件。

TTTAddressFormatter

地址格式在不同地区差异很大。使用 TTTAddressFormatter 可以借助 Address Book 框架来帮助用户找到他们的位置。

例如，美国的地址格式如下：

Street Address
City State ZIP
Country

而日本的地址格式遵循不同的约定

Postal Code
Prefecture Municipality
Street Address
Country

需要包含 AddressBook 和 AddressBookUI 框架，并在 Prefix.pch 中使用 #import 指令。仅在iOS上可用。

示例用法

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

TTTArrayFormatter

将其视为NSArray -componentsJoinedByString:的生产级替代方案。TTTArrayFormatter内置国际化支持，并提供简洁的API，允许您配置任何边缘情况。

示例用法

NSArray *list = [NSArray arrayWithObjects:@"Russel", @"Spinoza", @"Rawls", nil];
TTTArrayFormatter *arrayFormatter = [[TTTArrayFormatter alloc] init];
[arrayFormatter setUsesAbbreviatedConjunction:YES]; // Use '&' instead of 'and'
[arrayFormatter setUsesSerialDelimiter:NO]; // Omit Oxford Comma
NSLog(@"%@", [arrayFormatter stringFromArray:list]); // # => "Russell, Spinoza & Rawls"

TTTColorFormatter

以美观的方式处理RGB、CMYK和HSL。 TTTColorFormatter提供颜色的字符串表示形式。

示例用法

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

TTTLocationFormatter

在处理CoreLocation时，您可以使用您喜欢的距离单位，只要您的单位是米。如果您想将距离计算结果展示给用户，您可能希望使用千米，或者在您是英制系统用户的情况下，甚至可以使用英里。

TTTLocationFormatter在显示坐标、距离、方向、速度和速率方面提供了很多灵活性。选择公制或英制、主要方向、缩写或角度，并通过相关的NSNumberFormatter配置所有其他设置（有效数字的数量等）。

示例用法

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"

英制单位中的速度及方位角

[locationFormatter setBearingStyle:TTTBearingNumericStyle];
NSLog(@"%@ at %@", [locationFormatter stringFromSpeed:25],[locationFormatter stringFromBearingFromLocation:pittsburgh toLocation:austin]);
// "25 mph at 310°"

坐标

[locationFormatter.numberFormatter setUsesSignificantDigits:NO];
NSLog(@"%@", [locationFormatter stringFromLocation:austin]);
// (30.2669444, -97.7427778)

TTTNameFormatter

TTTNameFormatter 依据AddressBook框架的国际化标准格式化名称，这些标准确定了名称的显示顺序，以及是否使用空格分隔组件。

TTTNameFormatter 在OS X上不可用。

示例用法

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"

NSString *japaneseName = [nameFormatter stringFromFirstName:@"孝和" lastName:@"関"];
NSLog(@"%@", japaneseName);
// "関孝和"

TTTOrdinalNumberFormatter

NSNumberFormatter 非常适合显示 整数（如 17、42、69 等），但它并没有内置对 序数（例如第 1、第 2、第 3 等）的支持。

一个简单的实现可能只是将个位数放入 switch 语句中，并附加 "-st"、"nd" 等。但是，如果您想支持法语，法语在各种情况下会附加 "-er"、"ère" 和 "-eme"，怎么办？又或者是西班牙语、日语呢？

TTTOrdinalNumberFormatter 支持 英语、西班牙语、法语、德语、爱尔兰语、意大利语、日语、荷兰语、葡萄牙语、简体中文和瑞典语。对于其他语言，您可以使用标准默认设置，或者用它来覆盖。对于序数标志依赖于谓词语法属性的语种，TTTOrdinalNumberFormatter 可以根据指定的性别和/或复数性进行格式化。

示例用法

TTTOrdinalNumberFormatter *ordinalNumberFormatter = [[TTTOrdinalNumberFormatter alloc] init];
[ordinalNumberFormatter setLocale:[NSLocale currentLocale]];
[ordinalNumberFormatter setGrammaticalGender:TTTOrdinalNumberFormatterMaleGender];
NSNumber *number = [NSNumber numberWithInteger:2];
NSLog(@"%@", [NSString stringWithFormat:NSLocalizedString(@"You came in %@ place!", nil), [ordinalNumberFormatter stringFromNumber:number]]);

假设您提供了 "你获得了第 %@ 名！" 的本地化字符串，输出将是

  • 英语： "你获得了第 2 名！"
  • 法语： "Vous êtes arrivé à la 2e place !"}
  • 西班牙语： "Usted llegó en el 2.o lugar!"

TTTTimeIntervalFormatter

几乎每个应用程序都会以某种方式处理时间，并且在大多数情况下，当我们向用户显示时间信息时，这些信息通常是相对于现在的相对时间。因此，“3分钟前”、“10个月前”或“上个月”。

iOS 4 为 NSDateFormatter 引入了 -doesRelativeDateFormatting 属性，但如果找不到惯用语表达式，则会回退到绝对时间表示。相反，TTTTimeIntervalFormatter 默认显示 NSTimeInterval 值的智能相对显示，并提供了将此行为扩展到您特定用例的选项。

示例用法

TTTTimeIntervalFormatter *timeIntervalFormatter = [[TTTTimeIntervalFormatter alloc] init];
[timeIntervalFormatter stringForTimeInterval:0]; // "just now"
[timeIntervalFormatter stringForTimeInterval:-100]; // "1 minute ago"
[timeIntervalFormatter stringForTimeInterval:-8000]; // "2 hours ago"

// Turn idiomatic deictic expressions on / off
[timeIntervalFormatter stringForTimeInterval:-100000]; // "1 day ago"
[timeIntervalFormatter setUsesIdiomaticDeicticExpressions:YES];
[timeIntervalFormatter stringForTimeInterval:-100000]; // "yesterday"

// Customize the present tense deictic expression for
[timeIntervalFormatter setPresentDeicticExpression:@"seconds ago"];
[timeIntervalFormatter stringForTimeInterval:0]; // "seconds ago"

// Expand the time interval for present tense
[timeIntervalFormatter stringForTimeInterval:-3]; // "3 seconds ago"
[timeIntervalFormatter setPresentTimeIntervalMargin:10];
[timeIntervalFormatter stringForTimeInterval:-3]; // "seconds ago"

TTTUnitOfInformationFormatter

无论一个应用与其底层硬件的抽象程度如何，总有一天它需要向用户传达文件的尺寸。

TTTUnitOfInformationFormatter 将若干位或字节数转换为人类可读的表示，使用的是国际单位(SI)的十进制单位或国际电工委员会(IEC)的二进制单位前缀。

下面是一个示例。

TTTUnitOfInformationFormatter *unitOfInformationFormatter = [[TTTUnitOfInformationFormatter alloc] init];
[unitOfInformationFormatter stringFromNumberOfBits:[NSNumber numberWithInteger:416]]; // "56 bytes"

// Display in either bits or bytes
[unitOfInformationFormatter setDisplaysInTermsOfBytes:NO];
[unitOfInformationFormatter stringFromNumberOfBits:[NSNumber numberWithInteger:416]]; // "416 bits"

// Use IEC Binary prefixes (base 2 rather than SI base 10; see http://en.wikipedia.org/wiki/IEC_60027)
[unitOfInformationFormatter setUsesIECBinaryPrefixesForCalculation:NO];
[unitOfInformationFormatter stringFromNumberOfBits:[NSNumber numberWithInteger:8660]]; // "8.66 Kbit"

[unitOfInformationFormatter setUsesIECBinaryPrefixesForCalculation:YES];
[unitOfInformationFormatter setUsesIECBinaryPrefixesForDisplay:YES];
[unitOfInformationFormatter stringFromNumberOfBits:[NSNumber numberWithInteger:416]]; // "8.46 Kibit"

下面是TTTURLRequestFormatter。

NSURLRequest 对象封装了网络请求中使用的所有信息，包括 URL、头、主体等。这并非我们通常想要提供给用户的内容，但有一个方法可以使它在调试中更易于携带。

下面是 TTTURLRequestFormatter 的使用方法。除了简单地将请求格式化为 POST http://www.example.com/，它还会生成包含所有头和数据字段的 cURL 和 Wget 命令，以便在控制台中进行调试。

下面是一个示例。

NSMutableURLRequest *request = [[NSMutableURLRequest alloc] initWithURL:[NSURL URLWithString:@"http://www.example.com/"]];
[request setHTTPMethod:@"POST"];
[request addValue:@"text/html" forHTTPHeaderField:@"Accept"];
[TTTURLRequestFormatter cURLCommandFromURLRequest:request];
curl -X POST "https://www.example.com/" -H "Accept: text/html"

许可证

FormatterKit 在 MIT 许可证下提供。有关更多信息，请参阅 LICENSE 文件。