Swift Property Wrappers 深度解析
Swift 5.1 引入了 Property Wrappers（属性包装器），这是一个强大的特性，允许开发者以声明式的方式抽象属性行为的通用模式。通过将通用逻辑封装到可复用的包装器中，可以显著减少样板代码，提高代码的可读性和可维护性。本文将深入探讨 Property Wrappers 的各个方面，包括其基本概念、工作原理、常见用例、高级特性以及当前的一些限制。
1. 什么是 Property Wrappers？
Property Wrappers 是一种用于封装属性存储和访问逻辑的机制。它们允许开发者将常见的属性行为（如验证、转换、存储）抽象出来，并通过简单的注解应用到多个属性上。本质上，Property Wrappers 提供了一种可重用的方式来定义属性的 getter 和 setter 行为，而无需在每个属性中重复相同的代码。
1.1 基本语法
要定义一个 Property Wrapper，你需要使用 @propertyWrapper 属性来标记一个结构体、枚举或类。这个类型必须包含一个名为 wrappedValue 的属性，它定义了包装值的存储和访问方式。
@propertyWrapper
struct Capitalized {
private var value: String = ""
var wrappedValue: String {
get { value }
set { value = newValue.capitalized }
}
init(wrappedValue: String) {
self.wrappedValue = wrappedValue
}
}
在这个例子中，Capitalized 是一个 Property Wrapper，它会将字符串值首字母大写。你可以这样使用它：
struct User {
@Capitalized var name: String
}
var user = User()
user.name = "john doe"
print(user.name) // 输出："John Doe"
2. Property Wrappers 的工作原理
当你使用 @Capitalized 修饰一个属性时，编译器会自动将该属性的访问重定向到 Property Wrapper 的 wrappedValue。这意味着对属性的读取和写入操作实际上是通过 wrappedValue 的 getter 和 setter 来完成的。
2.1 编译器的魔法
编译器会为被包装的属性生成一些额外的代码。例如，对于 @Capitalized var name: String，编译器实际上会生成一个名为 _name 的存储属性，其类型为 Capitalized，以及一个名为 name 的计算属性，该属性委托给 _name.wrappedValue。
3. 常见用例
Property Wrappers 可以应用于多种场景，以下是一些常见的用例。
3.1 值验证
确保属性值始终在特定范围内是一个常见需求。例如，限制一个分数在 0 到 100 之间。
@propertyWrapper
struct Clamped<Value: Comparable> {
private var value: Value
let range: ClosedRange<Value>
var wrappedValue: Value {
get { value }
set { value = min(max(range.lowerBound, newValue), range.upperBound) }
}
init(wrappedValue: Value, _ range: ClosedRange<Value>) {
self.value = min(max(range.lowerBound, wrappedValue), range.upperBound)
self.range = range
}
}
struct Player {
@Clamped(0...100) var score: Int = 0
}
var player = Player()
player.score = 150
print(player.score) // 输出：100
3.2 UserDefaults 封装
使用 Property Wrappers 可以简化 UserDefaults 的访问，避免重复的样板代码。
@propertyWrapper
struct UserDefault<T> {
let key: String
let defaultValue: T
var storage: UserDefaults = .standard
var wrappedValue: T {
get {
storage.object(forKey: key) as? T ?? defaultValue
}
set {
if let optional = newValue as? AnyOptional, optional.isNil {
storage.removeObject(forKey: key)
} else {
storage.set(newValue, forKey: key)
}
}
}
init(wrappedValue defaultValue: T, key: String, storage: UserDefaults = .standard) {
self.defaultValue = defaultValue
self.key = key
self.storage = storage
}
}
// 支持可选值的协议
protocol AnyOptional {
var isNil: Bool { get }
}
extension Optional: AnyOptional {
var isNil: Bool { self == nil }
}
使用方式：
extension UserDefaults {
@UserDefault(key: "username", defaultValue: "Guest")
static var username: String
@UserDefault(key: "year_of_birth")
static var yearOfBirth: Int?
}
UserDefaults.username = "Alice"
UserDefaults.yearOfBirth = 1990
UserDefaults.yearOfBirth = nil // 会自动从 UserDefaults 中移除该键
3.3 观察值变化
通过 Property Wrappers，可以轻松实现属性值的观察。
@propertyWrapper
struct Observable<T> {
private var value: T
private var observer: ((T) -> Void)?
var wrappedValue: T {
get { value }
set {
value = newValue
observer?(value)
}
}
var projectedValue: Observable<T> { self }
mutating func bind(observer: @escaping (T) -> Void) {
self.observer = observer
}
init(wrappedValue: T) {
self.value = wrappedValue
}
}
class UserProfile {
@Observable var name: String = "" {
didSet {
print("Name changed to \(name)")
}
}
}
3.4 字符串处理
处理用户输入时，经常需要修剪字符串两端的空白字符。
@propertyWrapper
struct Trimmed {
private(set) var value: String = ""
var wrappedValue: String {
get { value }
set { value = newValue.trimmingCharacters(in: .whitespacesAndNewlines) }
}
init(wrappedValue: String) {
self.wrappedValue = wrappedValue
}
}
struct Post {
@Trimmed var title: String
@Trimmed var body: String
}
let post = Post(title: " Swift Property Wrappers ", body: "...")
print(post.title) // 输出："Swift Property Wrappers"
4. 高级特性
4.1 投影值（Projected Values）
Property Wrappers 可以通过 projectedValue 提供额外的功能。使用 $ 前缀可以访问投影值。
@propertyWrapper
struct Clamped<Value: Comparable> {
private var value: Value
let range: ClosedRange<Value>
var wrappedValue: Value {
get { value }
set { value = min(max(range.lowerBound, newValue), range.upperBound) }
}
var projectedValue: ClosedRange<Value> { range }
init(wrappedValue: Value, _ range: ClosedRange<Value>) {
self.value = min(max(range.lowerBound, wrappedValue), range.upperBound)
self.range = range
}
}
struct Temperature {
@Clamped(0...100) var celsius: Double
}
var temp = Temperature(celsius: 25)
print(temp.celsius) // 输出：25.0
print(temp.$celsius) // 输出：0.0...100.0（范围）
4.2 组合多个 Property Wrappers
可以在单个属性上应用多个 Property Wrappers，以组合它们的行为。注意，它们的应用顺序是从内到外的。
@propertyWrapper
struct Trimmed {
private(set) var value: String = ""
var wrappedValue: String {
get { value }
set { value = newValue.trimmingCharacters(in: .whitespacesAndNewlines) }
}
init(wrappedValue: String) {
self.wrappedValue = wrappedValue
}
}
@propertyWrapper
struct Capitalized {
private var value: String = ""
var wrappedValue: String {
get { value }
set { value = newValue.capitalized }
}
init(wrappedValue: String) {
self.wrappedValue = wrappedValue
}
}
struct User {
@Trimmed @Capitalized var name: String
}
var user = User(name: " john doe ")
print(user.name) // 输出："John Doe"
4.3 在函数参数中使用 Property Wrappers
Property Wrappers 也可以用于函数参数，为参数提供验证或转换逻辑。
@propertyWrapper
struct Positive {
var wrappedValue: Int
init(wrappedValue: Int) {
if wrappedValue < 0 {
self.wrappedValue = 0
} else {
self.wrappedValue = wrappedValue
}
}
}
func doSomething(@Positive value: Int) {
print("Value is \(value)")
}
doSomething(value: 42) // 输出：Value is 42
doSomething(value: -5) // 输出：Value is 0
另一个例子，格式化函数参数：
@propertyWrapper
struct Uppercase {
var wrappedValue: String
init(wrappedValue: String) {
self.wrappedValue = wrappedValue.uppercased()
}
}
func greet(@Uppercase name: String) {
print("Hello, \(name)!")
}
greet(name: "John") // 输出：Hello, JOHN!
4.4 访问包装器实例
使用 _ 前缀可以直接访问 Property Wrapper 的实例，而 $ 前缀用于访问投影值。
extension UserDefaults {
@UserDefault(key: "username", defaultValue: "Guest")
static var username: String
static func debugKeys() {
print(_username.key) // 输出："username"
print($username) // 输出：投影值（如果有）
}
}
5. 实际应用案例
5.1 在 SwiftUI 中管理用户偏好设置
在 macOS 或 iOS 应用中，使用 Property Wrappers 可以非常优雅地管理用户偏好设置。
import SwiftUI
class Settings: ObservableObject {
@UserDefault(key: "username", defaultValue: "Guest")
var username: String
@UserDefault(key: "isDarkMode", defaultValue: false)
var isDarkMode: Bool
}
struct ContentView: View {
@StateObject private var settings = Settings()
var body: some View {
Form {
Section(header: Text("User Settings")) {
TextField("Username", text: $settings.username)
Toggle("Dark Mode", isOn: $settings.isDarkMode)
}
}
.padding()
.frame(width: 300, height: 200)
}
}
@main
struct MyApp: App {
var body: some Scene {
WindowGroup {
ContentView()
.preferredColorScheme(settings.isDarkMode ? .dark : .light)
}
}
}
5.2 与 Combine 框架集成
通过投影值，Property Wrappers 可以很容易地与 Combine 框架集成，提供响应式能力。
import Combine
@propertyWrapper
struct UserDefault<Value> {
private let key: String
private let defaultValue: Value
private let publisher = PassthroughSubject<Value, Never>()
private var storage: UserDefaults = .standard
var wrappedValue: Value {
get {
storage.object(forKey: key) as? Value ?? defaultValue
}
set {
if let optional = newValue as? AnyOptional, optional.isNil {
storage.removeObject(forKey: key)
} else {
storage.set(newValue, forKey: key)
}
publisher.send(newValue)
}
}
var projectedValue: AnyPublisher<Value, Never> {
publisher.eraseToAnyPublisher()
}
init(wrappedValue defaultValue: Value, key: String, storage: UserDefaults = .standard) {
self.defaultValue = defaultValue
self.key = key
self.storage = storage
}
}
// 订阅变化
let cancellable = UserDefaults.$username.sink {
print("用户名变为：\($0)")
}
UserDefaults.username = "新名字"
// 控制台输出：用户名变为：新名字
6. 限制与注意事项
尽管 Property Wrappers 非常强大，但它们也有一些限制和需要注意的地方。
6.1 当前限制
-
不能用于 lazy 属性：Property Wrappers 不能应用于标记为
lazy的属性。 -
不能在协议声明中使用：不能在协议中定义带有 Property Wrappers 的属性。
-
不能抛出错误：Property Wrappers 无法让属性抛出错误，处理无效值的方式有限（如忽略或使用
fatalError()）。 -
多个包装器的顺序问题：当多个 Property Wrappers 应用于单个属性时，顺序很重要，因为它们是从内到外应用的。
-
不能与某些属性修饰符共用：不能与
@NSCopying、@NSManaged、weak或unowned等修饰符一起使用。 -
类型别名限制：带有包装器的属性不能用
typealias标记。
6.2 处理复杂场景的变通方案
由于目前不支持直接组合多个 Property Wrappers，可以通过嵌套的方式来实现类似功能。
@propertyWrapper
struct Dasherized {
private(set) var value: String = ""
var wrappedValue: String {
get { value }
set { value = newValue.replacingOccurrences(of: " ", with: "-") }
}
init(wrappedValue: String) {
self.wrappedValue = wrappedValue
}
}
// 通过嵌套实现多个功能
@propertyWrapper
struct TrimmedAndDasherized {
@Trimmed private var trimmedValue: String
@Dasherized private var dasherizedValue: String
var wrappedValue: String {
get { dasherizedValue }
set {
trimmedValue = newValue
dasherizedValue = trimmedValue
}
}
init(wrappedValue: String) {
self.wrappedValue = wrappedValue
}
}
struct Post {
@TrimmedAndDasherized var slug: String
}
7. 总结
Swift 的 Property Wrappers 是一个极具表现力的功能，它允许开发者将属性的通用访问模式抽象成可重用的组件。通过减少样板代码，它们使代码更加简洁、可读和可维护。从值验证到 UserDefaults 封装，从字符串处理到与 Combine 的响应式集成，Property Wrappers 的应用场景广泛且实用。
虽然目前存在一些限制，如不能用于 lazy 属性或协议中，但通过一些巧妙的变通方案，仍然可以在大多数场景中享受其带来的便利。随着 Swift 语言的不断发展，相信 Property Wrappers 的功能会变得更加强大和灵活。
