阅读 410

WWDC 2021新Formatter API:新老比较及如何自定义

在WWDC 2021的What's in Foundation专题中,苹果隆重介绍了适用于Swift的新Formatter API。网上已经有不少文章对新API的用法进行了说明。本文将通过介绍如何创建符合新API的Formatter,让读者从另一个角度了解新Formatter API的设计机制;并对新旧两款API进行比较。

原文发表在我的博客 www.fatbobman.com

本文的演示代码可以在Github上下载

新旧交替或风格转换

新Formatter API可以做什么

新Formatter提供了一个便捷的接口,让Swift程序员以更熟悉方式在应用程序中呈现本地化的格式字符串。

新API比旧API好吗

好和坏都是相对的,对于以Swift开发为主或者只会Swift的程序员(比如我本人),新Formatter不仅学习和使用起来更容易,同时也更适合日益流行的声明式编程风格。不过从整体功能和效率上讲,新Formatter并不具备优势。

新旧API比较

调用方便度

如果说新API相较旧API的最大优势,便是在调用上更符合直觉、更方便了。

旧API:

      let number = 3.147
      let numberFormat = NumberFormatter()
      numberFormat.numberStyle = .decimal
      numberFormat.maximumFractionDigits = 2
      numberFormat.roundingMode = .halfUp
      let numString = numberFormat.string(from: NSNumber(3.147))!
      // 3.15
复制代码

新API:

      let number = 3.147
      let numString = number.formatted(.number.precision(.fractionLength(2)).rounded(rule: .up))
      // 3.15
复制代码

旧API:

      let numberlist = [3.345,534.3412,4546.4254]
      let numberFormat = NumberFormatter()
              numberFormat.numberStyle = .decimal
              numberFormat.maximumFractionDigits = 2
              numberFormat.roundingMode = .halfUp
      let listFormat = ListFormatter()
      let listString = listFormat
                  .string(from:
                              numberlist
                              .compactMap{numberFormat.string(from:NSNumber(value: $0))}
                  ) ?? ""
      // 3.35, 534.35, and 4,546.43
复制代码

新API:

        let numString1 = numberlist.formatted(
            .list(
                memberStyle: .number.precision(.fractionLength(2)).rounded(rule: .up),
                type: .and
            )
        )
    // 3.35, 534.35, and 4,546.43
复制代码

即使你对新API并不很了解,仅凭代码的自动提示你就可以快速组合出想要的格式化结果。

运行效率

在WWDC视频中,苹果几次提及新API对性能的提升。不过苹果并没有告诉你全部的真相。

从我个人的测试数据来看,新API的效率相较于仅使用一次的Formatter实例来说,提升还是比较明显的(30% —— 300%),不过同可复用的Formatter实例比较,仍有数量级上的差距。

旧API,每次都重新创建实例

    func testDateFormatterLong() throws {
        measure {
            for _ in 0..<count {
                let date = Date()
                let formatter = DateFormatter()
                formatter.dateStyle = .full
                formatter.timeStyle = .full
                _ = formatter.string(from: date)
            }
        }
    }
// 0.121
复制代码

旧API,只创建一次实例

    func testDateFormatterLongCreateOnce() throws {
        let formatter = DateFormatter()
        measure {
            for _ in 0..<count {
                let date = Date()
                formatter.dateStyle = .full
                formatter.timeStyle = .full
                _ = formatter.string(from: date)
            }
        }
    }
// 0.005
复制代码

新API

    func testDateFormatStyleLong() throws {
        measure {
            for _ in 0..<count {
                _ = Date().formatted(.dateTime.year().month(.wide).day().weekday(.wide).hour(.conversationalTwoDigits(amPM: .wide)).minute(.defaultDigits).second(.twoDigits).timeZone(.genericName(.long)))
            }
        }
    }
// 0.085
复制代码

使用新API,配置的内容越多,执行所需时间也会相应增长。不过除非是对性能有非常高要求的场景,否则新API的执行效率还是有可以令人满意的。

本文的Demo中,附带了部分Unit Test代码,大家可以自行测试。

统一性

旧API中,针对不同的格式化类型,我们需要创建不同的Formatter实例。比如使用NumberFormatter格式化数字、DateFormatter格式化日期。

新API针对每个支持的类型都提供了统一的调用接口,尽量减少代码层面的复杂度

Date.now.formatted()
// 9/30/2021, 2:12 PM
345.formatted(.number.precision(.integerLength(5)))
// 00,345
Date.now.addingTimeInterval(100000).formatted(.relative(presentation: .named))
// tomorrow
复制代码

自定义难度

新API的调用便利性是建立在大量繁杂工作的基础之上的。相较于旧API通过属性直接设置,新API采用函数式编程方式,针对每个属性单独编写设置方法。虽然并不复杂,但工作量明显提高。

AttributedString

新API为每个可转换类型都提供AttributedString格式支持。通过AttribtedString中的Field,可以方便的生成想要的显示样式。

比如:

    var dateString: AttributedString {
        var attributedString = Date.now.formatted(.dateTime
            .hour()
            .minute()
            .weekday()
            .attributed
        )
        let weekContainer = AttributeContainer()
            .dateField(.weekday)
        let colorContainer = AttributeContainer()
            .foregroundColor(.red)
        attributedString.replaceAttributes(weekContainer, with: colorContainer)
        return attributedString
    }

Text(dateString)
复制代码

image-20210930142453213

代码出错率

在新API中,一切都是类型安全的,开发者无需反复的查阅文档,你的代码可以享受编译时检查的好处。

比如下面的代码

旧API

let dateFormatter:DateFormatter = {
    let formatter = DateFormatter()
    formatter.dateFormat = "yyyy-MM-dd HH:mm:ss"
    return formatter
}()

let dateString = dateFormatter.string(from: Date.now)
复制代码

新API

let dateString = Date.now.formatted(.iso8601.year().month().day().dateSeparator(.dash).dateTimeSeparator(.space).time(includingFractionalSeconds: false) .timeSeparator(.colon))
复制代码

如果单从代码量上来看,在本例中,新API不占据任何优势。不过你无需在yyyy和YYYY或者MM还是mm中犹豫,也不用反复查看令人头痛的文档,减少了在代码中犯错的可能性。

风格转换?

旧API是Objc的产物,它十分高效且好用,但在Swift中使用难免有不协调感。

新API是完全为Swift开发的,它采用了当前流行的声明式的风格。开发者只需要声明需要显示的字段,系统将以合适的格式进行呈现。

两种风格将在苹果的开发生态中长期共存,开发者可以选择适合自己的方式来实现同一个目标。

因此不存在风格转换的问题,苹果只是补交了Swift开发环境上缺失的一部分而已。

结论

新旧API将长期共存。

新API并非用来替换旧的Formatter API,应该算是旧Formatter的Swift实现版本。新API基本涵盖了旧API绝大多数的功能,着重改善了开发者的使用体验。

类似的情况在最近几年中将不断上演,苹果在Swift语言层面基本完善的情况下,将逐步提供其核心框架的Swift版本。本届WWDC上推出的AttributedString也可以佐证这一点。

如何自定义新的Formatter

新老API在自定义方面的不同

旧API是用类实现的,在创建自定义格式化器时,我们需要创建一个Formatter的子类,并至少实现以下两个方法:

class MyFormatter:Formatter {
   // 将被格式化类型转换成格式类型(字符串)
    override func string(for obj: Any?) -> String?{
        guard let value = obj as? Double else {return nil}
        return String(value)
    }

   // 将格式化类型(字符串)转换回被格式化类型
    override func getObjectValue(_ obj: AutoreleasingUnsafeMutablePointer<AnyObject?>?, for string: String, errorDescription error: AutoreleasingUnsafeMutablePointer<NSString?>?) -> Bool{
        guard let value = Double(string) else {return false}
        obj?.pointee = value as AnyObject
        return true
    }
}
复制代码

需要的情况下,我们也可以提供NSAttributedString的格式化实现

    override func attributedString(for obj: Any, withDefaultAttributes attrs: [NSAttributedString.Key : Any]? = nil) -> NSAttributedString? {
        nil
    }
复制代码

数据的格式转换都是在一个类定义中完成的。

新API充分体现了Swift作为面向协议语言的特点,使用两个协议(FormatStyleParseStrategy),分别定义了格式化数据和从格式化转换两个方向的实现。

新协议

FormatStyle

将被格式化类型转换成格式化类型。

public protocol FormatStyle : Decodable, Encodable, Hashable {

    /// The type of data to format.
    associatedtype FormatInput

    /// The type of the formatted data.
    associatedtype FormatOutput

    /// Creates a `FormatOutput` instance from `value`.
    func format(_ value: Self.FormatInput) -> Self.FormatOutput

    /// If the format allows selecting a locale, returns a copy of this format with the new locale set. Default implementation returns an unmodified self.
    func locale(_ locale: Locale) -> Self
}
复制代码

尽管在导出类型上使用了泛型,不过由于新API着重于格式化(而不是类型转换),因此通常FormatOutpu为String或者AttributedString

func format(_ value: Self.FormatInput) -> Self.FormatOutput是必须实现的方法,locale用来为Formatter设置区域信息,其返回值中的format方法的输出类型同原结构一致。因此,尽管Formatter会针对不同区域提供不同语言的返回结果,但为了兼容性,返回结果仍为String

FormatStyle协议同时约定了必须满足Codable和Hashable。

ParseStrategy

将格式化后的数据转换成被格式化类型

public protocol ParseStrategy : Decodable, Encodable, Hashable {

    /// The type of the representation describing the data.
    associatedtype ParseInput

    /// The type of the data type.
    associatedtype ParseOutput

    /// Creates an instance of the `ParseOutput` type from `value`.
    func parse(_ value: Self.ParseInput) throws -> Self.ParseOutput
}
复制代码

parse的定义可比旧API的getObjectValue容易理解多了。

ParseableFromatStyle

由于FormatStyleParseStrategy是两个独立的协议,因此苹果又提供了ParseableFromatStyle协议,方便我们在一个结构体中实现两个协议的方法。

public protocol ParseableFormatStyle : FormatStyle {

    associatedtype Strategy : ParseStrategy where Self.FormatInput == Self.Strategy.ParseOutput, Self.FormatOutput == Self.Strategy.ParseInput

    /// A `ParseStrategy` that can be used to parse this `FormatStyle`'s output
    var parseStrategy: Self.Strategy { get }
}
复制代码

尽管理论上也可以通过FormatStyle&ParseStrategy在一个结构体中实现双向转换,不过官方框架只支持通过ParseableFromatStyle协议实现的Formatter。

其他

尽管ParseableFromatStyle协议并没有要求一定要输出AttributedString,不过在官方的新Formatter API中还是为每个类型都提供了AttributedString的输出。

为了方便Formatter的调用,所有的官方Formatter都使用了Swift 5.5的新功能——在泛型上下文中扩展静态成员查找

例如

extension FormatStyle where Self == IntegerFormatStyle<Int> {
    public static var number: IntegerFormatStyle<Int> { get }
}
复制代码

我们最好也为自定义的Formatter提供类似的定义

实战

目标

本节中,我们将用新的协议来实现针对UIColor的Formatter,它将实现如下功能:

  • 转换成String
UIColor.red.formatted()
// #FFFFFF
复制代码
  • 转换成AttributedString
UIColor.red.formatted(.uiColor.attributed)
复制代码

image-20210930171252694

  • 从String转换成UIColor
let color = try! UIColor("#FFFFFFCC")
// UIExtendedSRGBColorSpace 1 1 1 0.8
复制代码
  • 支持链式配置(前缀、标记符号、是否显示透明度)
Text(color, format: .uiColor.alpah().mark().prefix)
复制代码

image-20210930171608519

  • localized

image-20210930171654956

实现ParseStrategy

将字符串转换成UIColor。

struct UIColorParseStrategy: ParseStrategy {
    func parse(_ value: String) throws -> UIColor {
        var hexColor = value
        if value.hasPrefix("#") {
            let start = value.index(value.startIndex, offsetBy: 1)
            hexColor = String(value[start...])
        }

        if hexColor.count == 6 {
            hexColor += "FF"
        }

        if hexColor.count == 8 {
            let scanner = Scanner(string: hexColor)
            var hexNumber: UInt64 = 0

            if scanner.scanHexInt64(&hexNumber) {
                return UIColor(red: CGFloat((hexNumber & 0xff000000) >> 24) / 255,
                               green: CGFloat((hexNumber & 0x00ff0000) >> 16) / 255,
                               blue: CGFloat((hexNumber & 0x0000ff00) >> 8) / 255,
                               alpha: CGFloat(hexNumber & 0x000000ff) / 255)
            }
        }

        throw Err.wrongColor
    }

    enum Err: Error {
        case wrongColor
    }
}
复制代码

在Demo中,我们并没有实现一个要求非常严格的ParseStrategy。任何长度为6或8的十六进制字符串都将被转换成UIColor。

实现ParseableFromatStyle

struct UIColorFormatStyle: ParseableFormatStyle {
    var parseStrategy: UIColorParseStrategy {
        UIColorParseStrategy()
    }

    private var alpha: Alpha = .none
    private var prefix: Prefix = .hashtag
    private var mark: Mark = .none
    private var locale: Locale = .current

    enum Prefix: Codable {
        case hashtag
        case none
    }

    enum Alpha: Codable {
        case show
        case none
    }

    enum Mark: Codable {
        case show
        case none
    }

    init(prefix: Prefix = .hashtag, alpha: Alpha = .none, mark: Mark = .none, locale: Locale = .current) {
        self.prefix = prefix
        self.alpha = alpha
        self.mark = mark
        self.locale = locale
    }

    func format(_ value: UIColor) -> String {
        let (prefix, red, green, blue, alpha, redMark, greenMark, blueMark, alphaMark) = Self.getField(value, prefix: prefix, alpha: alpha, mark: mark, locale: locale)
        return prefix + redMark + red + greenMark + green + blueMark + blue + alphaMark + alpha
    }
}

extension UIColorFormatStyle {
    static func getField(_ color: UIColor, prefix: Prefix, alpha: Alpha, mark: Mark, locale: Locale) -> (prefix: String, red: String, green: String, blue: String, alpha: String, redMask: String, greenMark: String, blueMark: String, alphaMark: String) {
        var r: CGFloat = 0
        var g: CGFloat = 0
        var b: CGFloat = 0
        var a: CGFloat = 0
        color.getRed(&r, green: &g, blue: &b, alpha: &a)
        let formatString = "%02X"
        let prefix = prefix == .hashtag ? "#" : ""
        let red = String(format: formatString, Int(r * 0xff))
        let green = String(format: formatString, Int(g * 0xff))
        let blue = String(format: formatString, Int(b * 0xff))
        let alphaString = alpha == .show ? String(format: formatString, Int(a * 0xff)) : ""

        var redMark = ""
        var greenMark = ""
        var blueMark = ""
        var alphaMark = ""

        if mark == .show {
            redMark = "Red: "
            greenMark = "Green: "
            blueMark = "Blue: "
            alphaMark = alpha == .show ? "Alpha: " : ""
        }

        return (prefix, red, green, blue, alphaString, redMark, greenMark, blueMark, alphaMark)
    }
}

复制代码

在ParseableFromatStyle中,除了实现format方法外,我们为不同的配置声明了属性。

getField方法声明为结构方法,便于之后的Attributed调用

在完成了上述代码后,我们已经可以使用代码在UIColor和String之间进行转换:

let colorString = UIColorFormatStyle().format(UIColor.blue)
// #0000FF

let colorString = UIColorFormatStyle(prefix: .none, alpha: .show, mark: .show).format(UIColor.blue)
// Red:00 Green:00 Blue:FF Alpha:FF

let color = try! UIColorFormatStyle().parseStrategy.parse("#FF3322")
// UIExtendedSRGBColorSpace 1 0.2 0.133333 1
复制代码

链式配置

extension UIColorFormatStyle {
    func prefix(_ value: Prefix = .hashtag) -> Self {
        guard prefix != value else { return self }
        var result = self
        result.prefix = value
        return result
    }

    func alpah(_ value: Alpha = .show) -> Self {
        guard alpha != value else { return self }
        var result = self
        result.alpha = value
        return result
    }

    func mark(_ value: Mark = .show) -> Self {
        guard mark != value else { return self }
        var result = self
        result.mark = value
        return result
    }

    func locale(_ locale: Locale) -> UIColorFormatStyle {
        guard self.locale != locale else { return self }
        var result = self
        result.locale = locale
        return result
    }
}
复制代码

现在我们获得了链式配置的能力。

let colorString = UIColorFormatStyle().alpah(.show).prefix(.none).format(UIColor.blue)
// 0000FFFF
复制代码

localized支持

由于format的输出类型为String,因此,我们需要在getField中将Mark转换成对应区域的文字。在getField中做如下修改:

        if mark == .show {
            redMark = getLocalizedString(.red, locale: locale)
            greenMark = getLocalizedString(.green, locale: locale)
            blueMark = getLocalizedString(.blue, locale: locale)
            alphaMark = alpha == .show ? getLocalizedString(.alpha, locale: locale) : ""
        }
复制代码

在UIColorFormatStyle添加如下代码:

enum MarkTag:String{
        case red
        case green
        case blue
        case alpha
    }

    static let localeString:[String:String] = [
        "EN-red":" Red:",
        "EN-green":" Green:",
        "EN-blue" : " Blue:",
        "EN-alpha" : " Alpha:",
        "ZH-red" : " 红:",
        "ZH-green" : " 绿:",
        "ZH-blue" : " 蓝",
        "ZH-alpha" : " 透明度:"
    ]
复制代码

至此,当系统切换到拥有对应语言包的地区时,Mark将显示对应的内容

# Red:00 Green:00 Blue:FF Alpha:FF
# 红:00 绿:00 蓝:FF 透明度:FF
复制代码

截至本文完成时,String(localized:String,locale:Locale)仍有Bug,无法获取到对应的Locale文字。系统的Formatter也有这个问题。正常的情况下,我们可以使用如下代码,在非中文区域获得中文的mark显示

之前对String新的构造方法理解有误,经过官方的邮件解释,String(localized:String, locale:Locale)中的locale是用来设置字符串差值中formatter的locale。因此对原有代码进行了修改。

let colorString = UIColorFormatStyle().mark().locale(Locale(identifier: "zh-cn")).format(UIColor.blue)
复制代码

在SwiftUI中设置

// Text将自动调用Formatter的locale方法
Text(color, format: .uiColor.mark())
    .environment(\.locale, Locale(identifier: "zh-cn"))
复制代码

AttributedString支持

创建自定义Field,便于使用者修改AttributedString不同区域的Style

enum UIColorAttirbute: CodableAttributedStringKey, MarkdownDecodableAttributedStringKey {
    enum Value: String, Codable {
        case red
        case green
        case blue
        case alpha
        case prefix
        case mark
    }

    static var name: String = "colorPart"
}

extension AttributeScopes {
    public struct UIColorAttributes: AttributeScope {
        let colorPart: UIColorAttirbute
    }

    var myApp: UIColorAttributes.Type { UIColorAttributes.self }
}

extension AttributeDynamicLookup {
    subscript<T>(dynamicMember keyPath: KeyPath<AttributeScopes.UIColorAttributes, T>) -> T where T: AttributedStringKey { self[T.self] }
}
复制代码

过些日子我会写篇博文介绍AttributedString的用法,以及如何自定义AttributedKey

由于将UIColor格式化成AttributedString是单向的(无需从AttribuedString转换回UIColor),因此Attributed只需遵循FormatStyle协议

extension UIColorFormatStyle {
    var attributed: Attributed {
        Attributed(prefix: prefix, alpha: alpha,mark: mark,locale: locale)
    }
  
    struct Attributed: Codable, Hashable, FormatStyle {
        private var alpha: Alpha = .none
        private var prefix: Prefix = .hashtag
        private var mark: Mark = .none
        private var locale: Locale = .current

        init(prefix: Prefix = .hashtag, alpha: Alpha = .none, mark: Mark = .none, locale: Locale = .current) {
            self.prefix = prefix
            self.alpha = alpha
            self.mark = mark
            self.locale = locale
        }

        func format(_ value: UIColor) -> AttributedString {
            let (prefix, red, green, blue, alpha, redMark, greenMark, blueMark, alphaMark) = UIColorFormatStyle.getField(value, prefix: prefix, alpha: alpha, mark: mark, locale: locale)
            let prefixString = AttributedString(localized: "^[\(prefix)](colorPart:'prefix')", including: \.myApp)
            let redString = AttributedString(localized: "^[\(red)](colorPart:'red')", including: \.myApp)
            let greenString = AttributedString(localized: "^[\(green)](colorPart:'green')", including: \.myApp)
            let blueString = AttributedString(localized: "^[\(blue)](colorPart:'blue')", including: \.myApp)
            let alphaString = AttributedString(localized: "^[\(alpha)](colorPart:'alpha')", including: \.myApp)

            let redMarkString = AttributedString(localized: "^[\(redMark)](colorPart:'mark')", locale: locale, including: \.myApp)
            let greenMarkString = AttributedString(localized: "^[\(greenMark)](colorPart:'mark')", locale: locale, including: \.myApp)
            let blueMarkString = AttributedString(localized: "^[\(blueMark)](colorPart:'mark')", locale: locale, including: \.myApp)
            let alphaMarkString = AttributedString(localized: "^[\(alphaMark)](colorPart:'mark')", locale: locale, including: \.myApp)

            let result = prefixString + redMarkString + redString + greenMarkString + greenString + blueMarkString + blueString + alphaMarkString + alphaString
            return result
        }

        func prefix(_ value: Prefix = .hashtag) -> Self {
            guard prefix != value else { return self }
            var result = self
            result.prefix = value
            return result
        }

        func alpah(_ value: Alpha = .show) -> Self {
            guard alpha != value else { return self }
            var result = self
            result.alpha = value
            return result
        }

        func mark(_ value: Mark = .show) -> Self {
            guard mark != value else { return self }
            var result = self
            result.mark = value
            return result
        }

        func locale<T:FormatStyle>(_ locale: Locale) -> T {
            guard self.locale != locale else { return self as! T }
            var result = self
            result.locale = locale
            return result as! T
        }
    }
}

复制代码

统一性支持

为UIColorFormatStyle添加FormatStyle扩展,方便在Xcode中使用

extension FormatStyle where Self == UIColorFormatStyle.Attributed {
    static var uiColor: UIColorFormatStyle.Attributed {
        UIColorFormatStyle().attributed
    }
}

extension FormatStyle where Self == UIColorFormatStyle {
    static var uiColor: UIColorFormatStyle {
        UIColorFormatStyle()
    }
}
复制代码

为UIColor添加便捷构造方法和formatted方法,保持同官方Formatter一致的使用体验。

extension UIColor {
    func formatted<F>(_ format: F) -> F.FormatOutput where F: FormatStyle, F.FormatInput == UIColor, F.FormatOutput == String {
        format.format(self)
    }

    func formatted<F>(_ format: F) -> F.FormatOutput where F: FormatStyle, F.FormatInput == UIColor, F.FormatOutput == AttributedString {
        format.format(self)
    }

    func formatted() -> String {
        UIColorFormatStyle().format(self)
    }

    convenience init<T:ParseStrategy>(_ value: String, strategy: T = UIColorParseStrategy() as! T  ) throws where T.ParseOutput == UIColor {
        try self.init(cgColor: strategy.parse(value as! T.ParseInput).cgColor)
    }

    convenience init(_ value: String) throws  {
        try self.init(cgColor: UIColorParseStrategy().parse(value).cgColor)
    }
}

复制代码

完成品

uicolorFormatter

可以在Github上下载全部代码。

总结

鉴于官方已经提供了大量种类齐全、功能丰富的Formatter,大多数的开发者可能都不会碰到需要自定义Formatter的场景。不过通过对自定义Formatter协议的了解,可以加强我们对原生Formatter的认识,在代码中更好地使用它们。

希望本文能对你有所帮助。

原文发表在我的博客 www.fatbobman.com

欢迎订阅我的公共号: 肘子的Swift记事本

AttributedString——不仅仅让文字更漂亮

如何对iOS应用中的文本进行本地化

在Spotlight中展示应用中的Core Data数据

文章分类
iOS
文章标签