想法和功能 • 支持的版本 • 安装 • 使用 • 贡献 • 许可 • 问题 • 拉取请求

想法和功能

在 2019 年的 WWDC 上，苹果公司宣布了一套新的图标库，这些图标包含在该年的新操作系统版本中。要浏览它们，有一个名为 SF Symbols 的专门的 Mac 应用。但是，开发者仍然必须复制一个符号的名称并以不安全的方式引用它，导致生成如下代码

UIImage(systemName: "circle.fill")

不久后，就提出了使这些图标以安全方式使用框架

此外，使用 SFSafeSymbols...

• ...您可以确保您的符号代码不会因为拼写错误或符号可用性问题而崩溃。这是因为所有符号都通过 CI 进行了测试（在最新的 iOS & tvOS 版本上，以及一些早期的操作系统版本）。
• ...查找 SF Symbols 应用程序中的信息（例如关于可用的
  
• ...支持多个 SF Symbols 版本（通过使用 @availability 标志）。每个符号仅在苹果声称其可用的平台版本中可用。
• ...可以轻松检测到已重命名的符号（通过建议使用新名称的同时
  

支持的版本

目前支持以下 SF Symbols 版本

安装

SFSafeSymbols 可以通过 Swift 包管理器（推荐）、Carthage 或 CocoaPods 来安装。

支持的平台包括 iOS (11.0+)、macOS (10.13+)、tvOS (11.0+) 和 watchOS (4.0+)，尽管实际上只有从 iOS 13.0、macOS 11.0、tvOS 13.0 和 watchOS 6.0 开始才能访问其实际功能。

Swift 包管理器（Xcode集成式）

要使用Xcode内置的SPM集成SFSafeSymbols，请选择 文件 → Swift 包 → 添加包依赖。输入以下url：https://github.com/SFSafeSymbols/SFSafeSymbols，然后点击 下一步。当询问版本时，保持预览选择并点击 下一步。在下一步中，选择 SFSafeSymbols 作为包产品并点击 完成。

Swift 包管理器（独立式）

要使用Apple的Swift包管理器的独立版本进行集成，请将以下内容添加到你的 Package.swift 中。

.package(url: "https://github.com/SFSafeSymbols/SFSafeSymbols.git", .upToNextMajor(from: "4.1.1"))

指定 "SFSafeSymbols" 作为目标依赖后，运行 swift package update。

Carthage

将以下条目添加到你的 Cartfile 中

github "SFSafeSymbols/SFSafeSymbols" ~> 4.1.1

然后运行 carthage update。

CocoaPods

将以下条目添加到您的Podfile中

pod 'SFSafeSymbols', '~> 4.1.1'

然后运行pod install。

用法

所有系统符号都可通过SFSymbol类型访问。它们的命名类似于Apple的命名方式，但使用小驼峰式，并使用带下划线的数字作为前缀。

c.circle        ~> SFSymbol.cCircle
e.circle.fill   ~> SFSymbol.eCircleFill
11.circle.fill  ~> SFSymbol._11CircleFill

现在可以使用SFSymbol类型来初始化UIImage。此图片已经解包，因此您将获得一个UIImage而不是一个UIImage?。

UIImage(systemSymbol: .cCircle)
UIImage(systemSymbol: SFSymbol.eCircleFill)
UIImage(systemSymbol: ._11CircleFill, withConfiguration: /* Some UIImage.Configuration */)

同样可以使用SFSymbol类型初始化SwiftUI.Image。

Image(systemSymbol: .cCircle)
Image(systemSymbol: SFSymbol.eCircleFill)

也有SwiftUI.Label初始化器。

Label("MyText", systemSymbol: .cCircle)
Label(LocalizedStringKey("my.text"), systemSymbol: SFSymbol.eCircleFill)

... 还有一个用于UIApplicationShortcutItem的初始化器

UIApplicationShortcutIcon(systemSymbol: .cCircle)
UIApplicationShortcutIcon(systemSymbol: SFSymbol.eCircleFill)

... 最后还有一个用于AppKit的NSImage的初始化器

NSImage(systemSymbol: .cCircle)
NSImage(systemSymbol: SFSymbol.eCircleFill, accessibilityDescription: "some.description")

本地化

SF符号可以包含多种不同的本地化版本。SFSafeSymbols以以下方式公开本地化：

• 隐式本地化：当使用一个SFSymbol时，它将自动本地化到用户的当前区域设置——您无需做任何事情。这种行为由Apple对SF符号的系统实现管理。

• 显式本地化：SFSafeSymbols允许您按以下方式访问符号的本地化版本

  // 1. Static localization:
  let a = SFSymbol.character.ar // corresponds to "character.ar"
  let b = SFSymbol.character.zh // corresponds to "character.zh"
  let c = SFSymbol.character.rtl // doesn't compile: "character.rtl" doesn't exist
  // a, b have type SFSymbol
  
  // 2. Dynamic localization:
  SFSymbol.character.availableLocalizations // [.ar, .he, .hi, .ja, .ko, .th, .zh, .zhTraditional]
  let a = SFSymbol.character.localized(to: .ar)
  let b = SFSymbol.character.localized(to: .rtl)
  // a, b have type SFSymbol?

  静态本地化仅公开实际可用的本地化，因此您无法意外本地化一个不可本地化的符号。

  相比之下，动态本地化在处理一个由具有不同可用本地化的多个SFSymbol组成的数组时很有用。

注意：序列化和反序列化SFSymbol目前会使它们丢失其显式的静态本地化信息。动态本地化信息将被保留。

SwiftLint

您可能想利用SwiftLint来确保在适当的情况下使用SFSafeSymbols。在您的.swiftlint.yml文件中，您可以添加一个自定义规则，如下所示

custom_rules:
  sf_safe_symbol:
    name: "Safe SFSymbol"
    message: "Use `SFSafeSymbols` via `systemSymbol` parameters for type safety."
    regex: "(Image\\(systemName:)|(NSImage\\(symbolName:)|(Label.*?systemImage:)|(UIApplicationShortcutIcon\\(systemImageName:)"
    severity: warning

...

欢迎贡献力量！有关更多信息，请参阅 CONTRIBUTING.md。

许可

本库遵循 MIT 许可 发布。详尽信息请参阅 LICENSE。