--- name: ios-dev-skill description: > iOS/macOS 开发技能（SwiftUI + UIKit）与 Swift 6.3 语言权威参考合集。覆盖 MVVM/Cocoa 架构、网络层（URLSession/async-await）、状态管理（@State/@Published/Combine）、依赖注入、 Navigation、性能优化、单元测试/UI 测试、持久化、App 分发，以及 Swift 完整语法（类型系统/集合/闭包/协议/泛型/并发）。当用户询问 iOS 开发、SwiftUI、Swift 语法、 Swift 语言任何相关内容时触发。 trigger: iOS 开发|SwiftUI|UIKit|Xcode|Swift 编程|MVVM|iOS 架构|iOS 网络|URLSession|Combine|@State|@Published|iOS 测试|XCTest|Swift 布局|SnapKit|Swift 语法|Swift 类型|Swift 闭包|Swift 泛型|Swift async|Swift await|Swift actor|Swift 代码解释|Swift optional|Swift protocol|Swift struct|Swift class|Swift enum|Swift guard|Swift if let|Swift ??|Swift @escaping|Swift 错误处理|Swift throws|Swift do-catch|Swift 访问控制|Swift extension|Swift 类型转换|Swift Sendable|Swift @propertyWrapper|Swift Property Wrapper|Swift tuple|Swift Optional 解包 tags: - ios - swiftui - uikit - xcode - swift - mvvm - ios-architecture - ios-network hermes: tags: [ios, swiftui, uikit, xcode, swift, mvvm, ios-architecture, ios-network] related_skills: [apple-design, harmonyos-dev] version: "1.0.0" last_updated: "2026-04-23" source: | https://developer.apple.com/documentation/swiftui https://developer.apple.com/documentation/uikit https://developer.apple.com/documentation/xcode https://developer.apple.com/documentation/combine license: MIT --- # iOS 开发技能 iOS/macOS 应用开发技能，基于 SwiftUI + UIKit。 # 核心架构 ## MVVM 架构（SwiftUI） ``` ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │ View │ ←── │ ViewModel │ ←── │ Model │ │ (SwiftUI) │ │ (ObservableObject) │ │ (Struct) │ └─────────────┘ └──────────────┘ └─────────────┘ @StateObject @Published @State @ObservedObject @State let ``` **数据流向**： 1. View 订阅 ViewModel 的 @Published 属性 2. ViewModel 处理业务逻辑，调用 Model 3. Model 定义数据结构 4. 状态变化自动触发 View 重新渲染 ## UIKit 架构对比 | 模式 | 适用场景 | 复杂度 | |------|---------|--------| | MVC | 简单页面 | 低 | | MVVM | 中等复杂度 | 中 | | MVP | 需要解耦 View | 中 | | VIPER | 大型模块化 | 高 | | Coordinator | 导航复杂 | 高 | --- ## iOS 生命周期与状态管理 ### App 生命周期 | 状态 | 触发时机 | 典型用途 | |------|---------|---------| | `didFinishLaunching` | App 启动完成 | 初始化配置 | | `sceneWillEnterForeground` | 从后台恢复 | 刷新数据 | | `sceneDidBecomeActive` | 获得焦点 | 恢复动画 | | `sceneWillResignActive` | 失去焦点 | 暂停任务 | | `sceneDidEnterBackground` | 进入后台 | 保存状态 | ### SwiftUI 状态修饰符 ```swift @State // 值类型，值语义 @StateObject // 引用类型，ObservableObject @ObservedObject // 外部提供的 ObservableObject @EnvironmentObject // 环境注入的共享状态 @Published // 属性观察器，自动触发更新 ``` ### 状态管理对比 | 方式 | 适用场景 | 生命周期 | |------|---------|---------| | `@State` | 视图私有 | 随视图 | | `@StateObject` | 模型对象 | 随视图 | | `@EnvironmentObject` | 跨视图共享 | 随 App | | `@AppStorage` | UserDefaults | 持久 | --- ## 数据持久化 ### 方案对比 | 方案 | 适用数据量 | 类型 | 线程安全 | |------|-----------|------|---------| | `UserDefaults` | < 1MB | Key-Value | ✅ | | FileManager | 任意 | 文件 | ❌ | | `PropertyListEncoder` | 中等 | 结构化 | ❌ | | `SQLite.swift` | 大型 | 关系型 | ✅ | | Core Data | 超大型 | 对象图 | ✅ | | Realm | 超大型 | 对象 | ✅ | ### UserDefaults ```swift @AppStorage("username") var username = "" @AppStorage("theme") var theme = "light" ``` ### SQLite.swift ```swift import SQLite let db = try Connection("db.sqlite3") let users = Table("users") let id = Expression("id") let name = Expression("name") try db.run(users.insert(name <- "Alice")) for user in try db.prepare(users) { print(user[name]) } ``` --- ## 网络与 API ### URLSession 封装 ```swift enum APIError: Error { case invalidURL, noData, decodingError, networkError(Error) } func fetch(_ type: T.Type, from url: String) async throws -> T { guard let url = URL(string: url) else { throw APIError.invalidURL } let (data, _) = try await URLSession.shared.data(from: url) do { return try JSONDecoder().decode(T.self, from: data) } catch { throw APIError.decodingError } } ``` ### SwiftUI 网络图片 ```swift AsyncImage(url: URL(string: "https://...")) { phase in switch phase { case .empty: ProgressView() case .success(let image): image.resizable() case .failure: Image(systemName: "photo") @unknown default: EmptyView() } } ``` --- ## App 分发与发布 ### 构建配置 | 配置 | 用途 | 代码签名 | |------|------|---------| | Debug | 开发调试 | Development | | Release | App Store | Distribution | | Ad Hoc | 测试分发 | Distribution | ### 发布检查清单 - [ ] App Icon 1024×1024 - [ ] 启动屏（Splash Screen） - [ ] Info.plist 权限说明 - [ ] 隐私政策 URL - [ ] TestFlight / App Store Connect 上传 - [ ] App Store 截图（6.7 / 6.5 / 5.5 英寸） ### 常用权限声明 | 权限 | Info.plist Key | |------|---------------| | 相机 | `NSCameraUsageDescription` | | 照片 | `NSPhotoLibraryUsageDescription` | | 位置 | `NSLocationWhenInUseUsageDescription` | | 通知 | 推送证书配置 | --- # SwiftUI 基础 ### 页面结构 ```swift @main struct MyApp: App { var body: some Scene { WindowGroup { ContentView() } } } struct ContentView: View { @State private var count = 0 var body: some View { VStack(spacing: 20) { Text("Count: \(count)") .font(.largeTitle) Button("Increment") { count += 1 } .buttonStyle(.borderedProminent) } } } ``` ### 组件层级 ``` Window → ViewController → View → Subviews NavigationController → ViewController → TableView → Cell TabBarController → ViewController × N → NavigationController ``` --- # 状态管理 | 状态类型 | SwiftUI | UIKit | 生命周期 | |---------|---------|-------|---------| | 本地临时 | @State | local var | 视图存在期间 | | 页面级 | @State | view property | 页面存在期间 | | 应用级 | @AppStorage | UserDefaults | 跨页面持久化 | | 全局共享 | @StateObject | Singleton | 应用生命周期 | ### SwiftUI 状态装饰器 ```swift // @State — 值类型，组件私有 @State private var text = "Hello" // @Binding — 双向绑定 @Binding var isPresented: Bool // @StateObject — 引用类型，视图拥有 @StateObject private var viewModel = ViewModel() // @ObservedObject — 引用类型，外部传入 @ObservedObject var viewModel: ViewModel // @EnvironmentObject — 环境注入的全局状态 @EnvironmentObject var authService: AuthService // @AppStorage — 持久化 @AppStorage("username") var username = "" ``` ### UIKit 状态 ```swift // 局部变量 class ViewController: UIViewController { private var data: [String] = [] override func viewDidLoad() { super.viewDidLoad() data = loadData() } } // 视图属性 class ViewController: UIViewController { var initialData: [String] = [] } // UserDefaults UserDefaults.standard.string(forKey: "username") // Singleton let shared = NetworkManager.shared ``` --- # Navigation 导航模式 ### SwiftUI NavigationStack（推荐） ```swift NavigationStack { List(users) { user in NavigationLink(destination: UserDetailView(user: user)) { Text(user.name) } } } ``` ### UIKit 导航 ```swift // 导航控制器 let nav = UINavigationController(rootViewController: HomeVC()) nav.pushViewController(detailVC, animated: true) nav.popViewController(animated: true) // TabBar 切换 UITabBarController() ├─ UINavigationController(首页) ├─ UINavigationController(发现) └─ UINavigationController(我的) ``` --- # 网络层 ### SwiftUI + async/await ```swift actor NetworkService { static let shared = NetworkService() func fetch(_ type: T.Type, from url: URL) async throws -> T { let (data, _) = try await URLSession.shared.data(from: url) return try JSONDecoder().decode(T.self, from: data) } } // 使用 Task { let users = try await NetworkService.shared.fetch([User].self, from: url) } ``` ### UIKit + async/await ```swift class NetworkManager { static let shared = NetworkManager() func request(_ type: T.Type, endpoint: String) async throws -> T { guard let url = URL(string: endpoint) else { throw NetworkError.invalidURL } let (data, _) = try await URLSession.shared.data(from: url) return try JSONDecoder().decode(T.self, from: data) } } ``` ### URLSession 完整示例 ```swift import Foundation struct User: Codable, Identifiable { let id: String let name: String let email: String } enum NetworkError: Error { case invalidURL case requestFailed case decodingFailed case noData } class APIClient { private let baseURL = "https://api.example.com" private let session: URLSession init() { let config = URLSessionConfiguration.default config.timeoutIntervalForRequest = 30 self.session = URLSession(configuration: config) } func get(_ type: T.Type, path: String) async throws -> T { guard let url = URL(string: baseURL + path) else { throw NetworkError.invalidURL } var request = URLRequest(url: url) request.httpMethod = "GET" request.setValue("application/json", forHTTPHeaderField: "Content-Type") let (data, response) = try await session.data(for: request) guard let httpResponse = response as? HTTPURLResponse, (200...299).contains(httpResponse.statusCode) else { throw NetworkError.requestFailed } let decoder = JSONDecoder() decoder.keyDecodingStrategy = .convertFromSnakeCase do { return try decoder.decode(T.self, from: data) } catch { throw NetworkError.decodingFailed } } func post(_ type: T.Type, path: String, body: B) async throws -> T { guard let url = URL(string: baseURL + path) else { throw NetworkError.invalidURL } var request = URLRequest(url: url) request.httpMethod = "POST" request.setValue("application/json", forHTTPHeaderField: "Content-Type") let encoder = JSONEncoder() encoder.keyEncodingStrategy = .convertToSnakeCase request.httpBody = try encoder.encode(body) let (data, response) = try await session.data(for: request) guard let httpResponse = response as? HTTPURLResponse, (200...299).contains(httpResponse.statusCode) else { throw NetworkError.requestFailed } return try JSONDecoder().decode(T.self, from: data) } } ``` --- # 依赖注入 ### SwiftUI Environment 注入 ```swift struct ContentView: View { @EnvironmentObject var authService: AuthService var body: some View { ... } } // App 层级注入 ContentView() .environmentObject(AuthService()) ``` ### UIKit Protocol 注入 ```swift protocol NetworkServiceProtocol { func fetchUsers() async throws -> [User] } class ViewModel { let networkService: NetworkServiceProtocol init(networkService: NetworkServiceProtocol = NetworkService.shared) { self.networkService = networkService } } ``` --- # Combine 响应式编程 ### Publisher 与 Subscriber ```swift import Combine // Publisher let publisher = PassthroughSubject() // Subscriber let cancellable = publisher .filter { $0.count > 3 } .map { $0.uppercased() } .sink { print($0) } // Future + Promise func fetchUser(id: Int) -> Future { Future { promise in // 异步操作 promise(.success(user)) } } ``` ### SwiftUI + Combine ```swift @Published var searchText: String = "" var searchResults: AnyPublisher<[User], Never> { $searchText .debounce(for: .milliseconds(300), scheduler: RunLoop.main) .removeDuplicates() .flatMap { query in query.isEmpty ? Just([]).eraseToAnyPublisher() : api.search(query: query) } .receive(on: DispatchQueue.main) .eraseToAnyPublisher() } ### AnyCancellable 内存管理 ```swift import Combine class ViewModel { private var cancellables = Set() func bind() { $searchText .debounce(for: .milliseconds(300), scheduler: RunLoop.main) .sink { [weak self] text in self?.performSearch(text) } .store(in: &cancellables) } } // Store in property class AnotherViewModel { @Published var data: [Item] = [] private var cancellables = Set() func subscribe(to api: APIService) { api.itemsPublisher .receive(on: DispatchQueue.main) .sink { [weak self] items in self?.data = items } .store(in: &cancellables) } } // 取消订阅 cancellables.removeAll() // 手动取消所有 ``` ### 常用 Operators | Operator | 用途 | |----------|------| | `map` | 转换值 | | `filter` | 过滤值 | | `flatMap` | 展平嵌套 Publisher | | `debounce` | 防抖（搜索场景） | | `throttle` | 节流（滚动场景） | | `removeDuplicates` | 去重 | | `combineLatest` | 合并多个 Publisher | | `merge` | 合并同类型 Publisher | | `catch` | 错误处理 | | `retry` | 重试 | | `zip` | 配对组合 | --- # 性能优化 | 场景 | SwiftUI | UIKit | |------|---------|-------| | 列表滚动 | LazyVStack | UITableView/UICollectionView | | 图片缓存 | AsyncImage + 第三方库 | SDWebImage/Kingfisher | | 预取数据 | .task modifier | UITableViewDataSourcePrefetching | | 后台任务 | Task.detached | async/await | ### SwiftUI 列表优化 ```swift // ✅ 推荐：LazyVStack List { ForEach(items) { item in ItemView(item: item) } } // ❌ 避免：大列表不用 Lazy VStack { ForEach(items) { item in // 全部渲染 ItemView(item: item) } } ``` ### UIKit 列表优化 ```swift // UICollectionView 预加载 func collectionView(_ collectionView: UICollectionView, prefetchItemsAt indexPaths: [IndexPath]) { for indexPath in indexPaths { let item = items[indexPath.item] imageLoader.prefetch(url: item.imageURL) } } ``` --- # 测试策略 ``` 单元测试 → ViewModel / Service 逻辑 ↓ UI 测试 → View 渲染 + 交互（XCUITest） ↓ 集成测试 → 模块间交互 ↓ 快照测试 → UI 视觉回归（swift-snapshot-testing） ``` ### Swift 单元测试示例 ```swift import XCTest final class UserViewModelTests: XCTestCase { var viewModel: UserListViewModel! var mockService: MockNetworkService! override func setUp() { super.setUp() mockService = MockNetworkService() viewModel = UserListViewModel(networkService: mockService) } func testLoadUsersSuccess() async { // Given mockService.users = [User(id: "1", name: "John")] // When await viewModel.loadUsers() // Then XCTAssertEqual(viewModel.users.count, 1) XCTAssertFalse(viewModel.isLoading) } } ``` --- # 完整页面示例 ### SwiftUI + MVVM ```swift // Model struct User: Identifiable, Codable { let id: String let name: String let email: String } // ViewModel @MainActor class UserListViewModel: ObservableObject { @Published var users: [User] = [] @Published var isLoading = false @Published var error: String? func loadUsers() async { isLoading = true defer { isLoading = false } do { users = try await api.fetch(User.self, path: "/users") } catch { self.error = error.localizedDescription } } } // View struct UserListView: View { @StateObject private var vm = UserListViewModel() var body: some View { NavigationStack { Group { if vm.isLoading { ProgressView() } else if let error = vm.error { Text("Error: \(error)") .foregroundColor(.red) } else { List(vm.users) { user in NavigationLink(destination: UserDetailView(user: user)) { HStack { Text(user.name) Spacer() Text(user.email) .foregroundColor(.secondary) } } } } } .navigationTitle("用户") .task { await vm.loadUsers() } } } } ``` ### UIKit + MVC ```swift import UIKit import SnapKit class UserListViewController: UIViewController { private let tableView = UITableView(frame: .zero, style: .insetGrouped) private var users: [User] = [] override func viewDidLoad() { super.viewDidLoad() setupUI() loadData() } private func setupUI() { title = "用户" view.backgroundColor = .systemGroupedBackground tableView.delegate = self tableView.dataSource = self tableView.register(UITableViewCell.self, forCellReuseIdentifier: "Cell") view.addSubview(tableView) tableView.snp.makeConstraints { make in make.edges.equalToSuperview() } } private func loadData() { Task { do { users = try await APIClient.shared.get([User].self, path: "/users") tableView.reloadData() } catch { showError(error) } } } } extension UserListViewController: UITableViewDataSource, UITableViewDelegate { func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int { return users.count } func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell { let cell = tableView.dequeueReusableCell(withIdentifier: "Cell", for: indexPath) let user = users[indexPath.row] var config = cell.defaultContentConfiguration() config.text = user.name config.secondaryText = user.email cell.contentConfiguration = config return cell } func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) { tableView.deselectRow(at: indexPath, animated: true) let user = users[indexPath.row] let detailVC = UserDetailViewController(user: user) navigationController?.pushViewController(detailVC, animated: true) } } ``` --- # Swift 语言权威参考 > 来源：The Swift Programming Language (6.3) > https://docs.swift.org/swift-book/documentation/the-swift-programming-language/ > CC BY 4.0 License ## 类型系统 ### 基本类型 | 类型 | 说明 | 示例 | |------|------|------| | Int | 整数 | `42`, `-7` | | Double | 64位浮点 | `3.14159` | | Float | 32位浮点 | `3.14` | | Bool | 布尔 | `true` / `false` | | String | 字符串 | `"Hello"` | | Character | 单字符 | `"A"` | ### 类型推断与注解 ```swift let inferred = 42 // Int let annotated: Int = 42 // 显式 Int let pi: Double = 3.14 // Double ``` ### 类型别名 ```swift typealias AudioSample = UInt16 typealias Callback = (Int, String) -> Void ``` ## Optional 可选类型 ### 定义与解包 ```swift // 定义 var serverResponse: String? = nil var response: String! = nil // 隐式解包 // 解包方式 if let value = optional { print(value) } // guard 解包 func process(_ value: String?) { guard let value = value else { return } print(value) } // ?? 操作符 let name = optional ?? "default" // 链式调用 let upper = optional?.uppercased() ``` ### Optional 模式 ```swift // switch 模式匹配 switch optional { case .some(let value): print(value) case .none: print("nil") } // 问号链式调用 person?.address?.city ``` ## Tuple 元组 ```swift // 定义 let httpError = (404, "Not Found") let (code, message) = httpError let onlyCode = httpError.0 // 命名 let success = (code: 200, message: "OK") success.code success.message // 返回多值 func getUser() -> (name: String, age: Int) { return ("Alice", 30) } ``` ## 集合类型 ### Array ```swift // 创建 var arr = [Int]() // 空 var arr2 = Array(repeating: 0, count: 5) // [0,0,0,0,0] let literals = [1, 2, 3] // 字面量 // 操作 arr.append(4) arr.insert(0, at: 0) arr.remove(at: 0) arr.removeLast() arr.first arr.last // 遍历 for item in arr { } for (i, v) in arr.enumerated() { } ``` ### Set ```swift // 创建 var set = Set() let genres: Set = ["Rock", "Jazz"] // 操作 set.insert("Pop") set.remove("Rock") set.contains("Jazz") // 集合运算 a.union(b) // 并集 a.intersection(b) // 交集 a.subtracting(b) // 差集 a.symmetricDifference(b) // 对称差集 // 关系 a.isSubset(of: b) a.isSuperset(of: b) a.isDisjoint(with: b) ``` ### Dictionary ```swift // 创建 var dict = [String: Int]() let capitals = ["CN": "Beijing", "JP": "Tokyo"] // 操作 dict["key"] = "value" dict["key"] = nil // 删除 dict.updateValue("v", forKey: "k") // 返回旧值 // 安全访问 if let value = dict["key"] { } // 遍历 for (k, v) in dict { } for key in dict.keys { } for value in dict.values { } ``` ## 函数 ### 定义与调用 ```swift func greet(name: String) -> String { return "Hello, \(name)" } greet(name: "World") // 参数标签 func greet(to name: String) -> String { return "Hello, \(name)" } greet(to: "World") // 默认参数 func greet(_ name: String = "World") -> String { return "Hello, \(name)" } // 可变参数 func sum(_ numbers: Int...) -> Int { return numbers.reduce(0, +) } sum(1, 2, 3, 4, 5) // inout 参数 func swap(_ a: inout Int, _ b: inout Int) { let temp = a a = b b = temp } ``` ### 函数类型 ```swift var mathFunc: (Int, Int) -> Int = { $0 + $1 } // 作为参数 func apply(_ op: (Int, Int) -> Int, _ a: Int, _ b: Int) -> Int { return op(a, b) } apply(mathFunc, 3, 4) // 作为返回值 func choose(_ op: Bool) -> (Int, Int) -> Int { return op ? { $0 + $1 } : { $0 - $1 } } ``` ### 嵌套函数 ```swift func outer() -> () -> Int { var count = 0 func inner() -> Int { count += 1 return count } return inner } ``` ## 闭包 ### 基本语法 ```swift // 完整语法 { (params) -> ReturnType in statements } // 类型推断 { a, b in a + b } // 无参数 { () -> Int in 42 } // 返回类型推断 { $0 + $1 } ``` ### 尾随闭包 ```swift // 不用尾随 arr.map({ (x: Int) -> Int in x * 2 }) // 尾随闭包 arr.map { $0 * 2 } // 最后一个参数是闭包 arr.map { x in x * 2 } ``` ### @escaping ```swift var handlers: [() -> Void] = [] func withEscaping(_ handler: @escaping () -> Void) { handlers.append(handler) } func withoutEscaping(_ handler: () -> Void) { handler() } // 逃逸闭包需要显式 self class MyClass { var x = 10 func test() { withEscaping { self.x = 20 } // 必须显式 withoutEscaping { x = 30 } // 可省略 } } ``` ### 捕获 ```swift func makeCounter() -> () -> Int { var count = 0 return { count += 1 return count } } let counter = makeCounter() counter() // 1 counter() // 2 ``` ## 枚举 ```swift enum Direction { case north, south, east, west } let dir: Direction = .north // 关联值 enum Result { case success(Data) case failure(Error) } // 方法 enum Device { case phone, tablet func description() -> String { switch self { case .phone: return "iPhone" case .tablet: return "iPad" } } } // 原始值 enum ASCIIControl: Character { case tab = "\t" case newline = "\n" } ``` ## 结构体与类 ### 对比 | 特性 | struct | class | |------|--------|-------| | 类型 | 值类型 | 引用类型 | | 继承 | ❌ | ✅ | | 初始化 | 自动生成 | 手动 | | 析构 | — | ✅ | | 引用计数 | — | ✅ | ```swift struct Point { var x: Double var y: Double // 自动生成 memberwise init } class Person { var name: String var age: Int init(name: String, age: Int) { self.name = name self.age = age } } ``` ## 属性 ### 存储属性 ```swift struct FixedRange { var start: Int let end: Int // 常量 } ``` ### 计算属性 ```swift struct Rect { var origin: Point var size: Size var center: Point { get { Point(x: origin.x + size.width/2, y: origin.y + size.height/2) } set { origin.x = newValue.x - size.width/2 origin.y = newValue.y - size.height/2 } } } ``` ### 属性包装器 ```swift @propertyWrapper struct SmallNumber { private var number: Int var value: Int { get { min(number, 12) } set { number = newValue } } init() { number = 0 } init(wrappedValue: Int) { number = min(wrappedValue, 12) } } @SmallNumber var value: Int // 使用 ``` ### 属性观察者 ```swift class StepCounter { var totalSteps: Int = 0 { willSet { print("will set to \(newValue)") } didSet { print("did set from \(oldValue)") } } } ``` ### 懒加载 ```swift class DataManager { lazy var importer = DataImporter() // 首次访问时才创建 } ``` ## 方法 ### 实例方法 ```swift class Counter { var count = 0 func increment() { count += 1 } func increment(by amount: Int) { count += amount } func reset() { count = 0 } } ``` ### 静态/类方法 ```swift struct MathUtils { static func sqrt(_ n: Double) -> Double { ... } } MathUtils.sqrt(16) // 类方法（可被重写） class Animal { class func info() { print("Animal") } } ``` ## 下标 ```swift struct TimesTable { subscript(index: Int) -> Int { return index * multiplier } } let table = TimesTable(multiplier: 3) table[6] // 18 // 多维下标 struct Matrix { subscript(row: Int, col: Int) -> Double { get { return grid[row * 3 + col] } set { grid[row * 3 + col] = newValue } } } ``` ## 继承 ```swift class Vehicle { var speed = 0 func describe() -> String { "speed: \(speed)" } } class Bicycle: Vehicle { var hasBasket = false override func describe() -> String { // 调用父类 return super.describe() + ", basket: \(hasBasket)" } } // final 类不可被继承 final class FinalClass { } ``` ## 初始化与析构 ### 初始化 ```swift class ShoppingListItem { var name: String var quantity: Int = 1 var completed: Bool = false init(name: String, quantity: Int = 1) { self.name = name self.quantity = quantity } } // 可失败初始化 struct Animal { let species: String init?(species: String) { if species.isEmpty { return nil } self.species = species } } ``` ### 析构 ```swift class FileHandler { var file: FileHandle init() { file = open(...) } deinit { file.close() } } ``` # 错误处理 ## 错误处理 ```swift // 定义错误 enum NetworkError: Error { case badURL case noData case decodingFailed } // 抛出 func fetch() throws -> Data { guard let url = URL(string: "...") else { throw NetworkError.badURL } return try Data(contentsOf: url) } // 处理 do { let data = try fetch() } catch NetworkError.badURL { print("Bad URL") } catch { print("Error: \(error)") } // try? 转换 Optional let data = try? fetch() // try! 强制解包（危险） let data = try! fetch() ``` # 协议与泛型 ## 协议 ### 定义与遵循 ```swift protocol ExampleProtocol { var simpleDescription: String { get } mutating func adjust() } // 遵循 struct SimpleStructure: ExampleProtocol { var simpleDescription: String = "A simple structure" mutating func adjust() { } } // 类遵循 class SimpleClass: ExampleProtocol { var simpleDescription: String = "A simple class" func adjust() { } } ``` ### 协议扩展 ```swift extension Collection { func allEven() -> [Element] where Element: Numeric { return self.filter { ($0 as? Int ?? 0) % 2 == 0 } } } ``` ## 泛型 ### 函数泛型 ```swift func swapTwoValues(_ a: inout T, _ b: inout T) { let temp = a a = b b = temp } swapTwoValues(&x, &y) ``` ### 类型约束 ```swift func findIndex(of valueToFind: T, in array: [T]) -> Int? { for (index, value) in array.enumerated() { if value == valueToFind { return index } } return nil } ``` ### 泛型类型 ```swift struct Stack { var items: [Element] = [] mutating func push(_ item: Element) { items.append(item) } mutating func pop() -> Element { items.removeLast() } } ``` ### where 子句 ```swift func allItemsMatch (_ someContainer: C1, _ anotherContainer: C2) -> Bool where C1.Element == C2.Element, C1.Element: Equatable { // ... } ``` ## 访问控制 | 修饰符 | 范围 | |--------|------| | open | 任意模块，可被继承 | | public | 任意模块 | | internal | 模块内（默认） | | fileprivate | 当前文件 | | private | 当前作用域 | ```swift public class PublicClass { private var privateVar = 0 fileprivate var fileVar = 0 } ``` ## 扩展 ```swift extension Int { var isEven: Bool { return self % 2 == 0 } func repetitions(_ task: () -> Void) { for _ in 0.. Data { ... } Task { do { let data = try await fetchData() } catch { print(error) } } // async let 并行 async let first = fetchData() async let second = anotherFetch() let results = await [first, second] ``` ### Task ```swift // 创建 let task = Task { await doWork() } let result = await task.value task.cancel() // TaskGroup await withTaskGroup(of: Data.self) { group in for url in urls { group.addTask { await fetch(url) } } var results: [Data] = [] for await data in group { results.append(data) } } ``` ### Actor ```swift actor SafeCounter { private var count = 0 func increment() { count += 1 } func getCount() -> Int { count } } // MainActor @MainActor func updateUI() { // UI 更新 } ``` ### Sendable ```swift struct User: Sendable { let id: String } actor SafeLogger: Sendable { // actor 自动 Sendable } ``` --- ## 避坑指南 ### 常见错误 | 错误做法 | 正确做法 | |---------|---------| | ❌ 在主线程执行网络请求 | ✅ async/await 自动后台执行 | | ❌ 不处理网络错误 | ✅ always try-catch + user feedback | | ❌ @State 用于引用类型 | ✅ @StateObject 用于 class | | ❌ 不用 LazyVStack 处理大列表 | ✅ 懒加载避免性能问题 | | ❌ 硬编码 URL | ✅ Configuration/Environment | ### SwiftUI 陷阱 - ⚠️ **@State 复制语义** — @State 修饰的 struct 是值语义，修改会触发重渲染 - ⚠️ **@StateObject 只初始化一次** — 不能在 body 中创建 - ⚠️ **onAppear vs task** — task 可取消，onAppear 不行 ### UIKit 陷阱 - ⚠️ **循环引用** — delegate/closure 记得用 [weak self] - ⚠️ **主线程 UI** — UI 更新必须在主线程 - ⚠️ **Memory Leak** — 及时清理 NotificationCenter 观察者 --- ## 来源 > 来源：Apple Developer Documentation（2026-04-23 访问） > - SwiftUI: https://developer.apple.com/documentation/swiftui > - UIKit: https://developer.apple.com/documentation/uikit > - Xcode: https://developer.apple.com/documentation/xcode > - Combine: https://developer.apple.com/documentation/combine > > 更新频率：随 Xcode/iOS 版本迭代 --- # 持久化 ### UserDefaults 适用于：小量配置、用户偏好、简单状态 ```swift // SwiftUI @AppStorage("username") var username = "" @AppStorage("isDarkMode") var isDarkMode = false // 代码直接访问 UserDefaults.standard.string(forKey: "username") UserDefaults.standard.set("value", forKey: "key") ``` ### SQLite（生产推荐）适用于：结构化数据、离线存储、查询性能 ```swift import SQLite class DatabaseManager { static let shared = DatabaseManager() private var db: Connection? // 表定义 private let users = Table("users") private let id = SQLite.Expression("id") private let name = SQLite.Expression("name") private let email = SQLite.Expression("email") init() { do { let path = NSSearchPathForDirectoriesInDomains( .documentDirectory, .userDomainMask, true ).first! db = try Connection("\(path)/sqlite.db") try createTables() } catch { print("Database error: \(error)") } } private func createTables() throws { try db?.run(users.create(ifNotExists: true) { t in t.column(id, primaryKey: .autoincrement) t.column(name) t.column(email) }) } // CRUD func insertUser(_ user: User) throws { let insert = users.insert( name <- user.name, email <- user.email ) try db?.run(insert) } func fetchUsers() throws -> [User] { guard let db = db else { return [] } return try db.prepare(users).map { row in User( id: row[id], name: row[name], email: row[email] ) } } func deleteUser(_ userId: Int64) throws { let user = users.filter(id == userId) try db?.run(user.delete()) } } ``` ### Core Data（苹果官方）适用于：复杂对象图、大量关系数据、Apple 生态深度集成 ```swift // Core Data Stack class CoreDataManager { static let shared = CoreDataManager() lazy var persistentContainer: NSPersistentContainer = { let container = NSPersistentContainer(name: "Model") container.loadPersistentStores { _, error in if let error = error { fatalError("Core Data failed: \(error)") } } container.viewContext.automaticallyMergesChangesFromParent = true return container }() var viewContext: NSManagedObjectContext { persistentContainer.viewContext } func save() { let context = viewContext if context.hasChanges { do { try context.save() } catch { print("Save error: \(error)") } } } } // SwiftUI 集成 struct ContentView: View { @Environment(\.managedObjectContext) var viewContext @FetchRequest( sortDescriptors: [NSSortDescriptor(keyPath: \User.name, ascending: true)], animation: .default ) var users: FetchedResults var body: some View { List(users, id: \.self) { user in Text(user.name ?? "Unknown") } } } ``` --- # Swift Concurrency 深度 ### Sendable 协议确保数据可以安全跨并发域传递。 ```swift // ✅ 可Sendable的类型 struct User: Sendable { let id: String let name: String // 值类型默认 Sendable } // ⚠️ Class 需要手动实现 final class SafeClass: @unchecked Sendable { // 不做线程安全假设，仅用于已知安全的场景 } // ❌ 不可Sendable class UnsafeClass { var cache = [String: Any]() // 包含可变状态 } ``` ### MainActor 确保代码在主线程执行，用于 UI 更新。 ```swift // 方法级别 @MainActor func updateUI() { // 自动在主线程执行 self.username = "New Name" } // 类级别（所有方法默认主线程） @MainActor class ViewModel: ObservableObject { @Published var items: [Item] = [] // 隐式 @MainActor func loadItems() async { let fetched = await network.fetchItems() self.items = fetched // 安全 } } // 非隔离函数访问主线程数据 nonisolated func describe(_ vm: ViewModel) { // ❌ 不能访问 @Published // ✅ 可以访问 Sendable 属性 print("Description") } ``` ### TaskGroup 并发执行多个任务。 ```swift // 并发下载 func fetchAllImages(urls: [URL]) async throws -> [Data] { try await withThrowingTaskGroup(of: Data.self) { group in for url in urls { group.addTask { let (data, _) = try await URLSession.shared.data(from: url) return data } } var results: [Data] = [] for try await data in group { results.append(data) } return results } } // 带取消 func fetchWithCancel(urls: [URL]) async { await withTaskGroup(of: Data?.self) { group in for url in urls { group.addTask { try? await Task.sleep(nanoseconds: 1_000_000_000) guard !Task.isCancelled else { return nil } let (data, _) = try await URLSession.shared.data(from: url) return data } } } } ``` ### Task 取消 ```swift // 检查取消 func performWork() async throws { for item in items { try Task.checkCancellation() // 抛出 CancellationError // 处理 item } } // withTaskCancellationHandler try await withTaskCancellationHandler { try await longRunningWork() } onCancel: { cleanup() } // 传递取消 struct DetailView: View { @State private var data: Data? @Environment(\.dismiss) var dismiss var body: some View { Button("加载") { Task { data = await fetchData() } } .onDisappear { // 视图消失时自动取消 } } } ``` --- # UIKit 进阶 ### UICollectionView 生产级列表/网格首选。 ```swift class CollectionViewController: UIViewController { private var collectionView: UICollectionView! private var dataSource: UICollectionViewDiffableDataSource! enum Section: Hashable { case main case featured } override func viewDidLoad() { super.viewDidLoad() setupCollectionView() configureDataSource() applySnapshot() } private func setupCollectionView() { // Compositional Layout let config = UICollectionLayoutConfiguration( -interSectionSpacing: 16 ) let layout = UICollectionViewCompositionalLayout( sectionProvider: { sectionIndex, environment in let itemSize = NSCollectionLayoutSize( widthDimension: .fractionalWidth(0.5), heightDimension: .fractionalHeight(1.0) ) let item = NSCollectionLayoutItem(layoutSize: itemSize) item.contentInsets = NSDirectionalEdgeInsets( top: 8, leading: 8, bottom: 8, trailing: 8 ) let groupSize = NSCollectionLayoutSize( widthDimension: .fractionalWidth(1.0), heightDimension: .absolute(180) ) let group = NSCollectionLayoutGroup.horizontal( layoutSize: groupSize, subitems: [item] ) let section = NSCollectionLayoutSection(group: group) section.contentInsets = NSDirectionalEdgeInsets( top: 0, leading: 16, bottom: 16, trailing: 16 ) return NSCollectionLayoutSection(section: section) }, configuration: config ) collectionView = UICollectionView( frame: view.bounds, collectionViewLayout: layout ) collectionView.autoresizingMask = [.flexibleWidth, .flexibleHeight] collectionView.delegate = self view.addSubview(collectionView) } private func configureDataSource() { let cellRegistration = UICollectionView.CellRegistration< UICollectionViewCell, Item > { cell, indexPath, item in var config = UIListContentConfiguration.cell() config.text = item.title config.secondaryText = item.subtitle config.image = UIImage(systemName: item.icon) cell.contentConfiguration = config } dataSource = UICollectionViewDiffableDataSource( collectionView: collectionView ) { collectionView, indexPath, item in collectionView.dequeueConfiguredReusableCell( using: cellRegistration, for: indexPath, item: item ) } } private func applySnapshot() { var snapshot = NSDiffableDataSourceSnapshot() snapshot.appendSections([.main]) snapshot.appendItems(items) dataSource.apply(snapshot, animatingDifferences: true) } } extension CollectionViewController: UICollectionViewDelegate { func collectionView( _ collectionView: UICollectionView, didSelectItemAt indexPath: IndexPath ) { guard let item = dataSource.itemIdentifier(for: indexPath) else { return } // 处理选择 } } ``` ### Auto Layout 完整约束 ```swift // NSLayoutConstraint 语法 label.translatesAutoresizingMaskIntoConstraints = false NSLayoutConstraint.activate([ label.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 16), label.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -16), label.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor, constant: 16), label.heightAnchor.constraint(greaterThanOrEqualToConstant: 44) ]) // 优先级 let highPriority = label.widthAnchor.constraint(equalToConstant: 100) highPriority.priority = .defaultHigh // 750 let lowPriority = label.widthAnchor.constraint(equalToConstant: 50) lowPriority.priority = .defaultLow // 250 // 比例约束 label.widthAnchor.constraint(equalTo: view.widthAnchor, multiplier: 0.5) // 尺寸约束 label.heightAnchor.constraint(equalTo: label.widthAnchor, multiplier: 1.5) ``` ### 键盘处理 ```swift class KeyboardViewController: UIViewController { @IBOutlet weak var scrollView: UIScrollView! @IBOutlet weak var textField: UITextField! override func viewDidLoad() { super.viewDidLoad() setupKeyboardObservers() } private func setupKeyboardObservers() { NotificationCenter.default.addObserver( self, selector: #selector(keyboardWillShow), name: UIResponder.keyboardWillShowNotification, object: nil ) NotificationCenter.default.addObserver( self, selector: #selector(keyboardWillHide), name: UIResponder.keyboardWillHideNotification, object: nil ) } @objc func keyboardWillShow(_ notification: Notification) { guard let keyboardFrame = notification.userInfo?[ UIResponder.keyboardFrameEndUserInfoKey ] as? CGRect else { return } let contentInsets = UIEdgeInsets( top: 0, left: 0, bottom: keyboardFrame.height, right: 0 ) scrollView.contentInset = contentInsets scrollView.scrollIndicatorInsets = contentInsets } @objc func keyboardWillHide(_ notification: Notification) { scrollView.contentInset = .zero scrollView.scrollIndicatorInsets = .zero } @objc func dismissKeyboard() { view.endEditing(true) } } // SwiftUI 版本 struct KeyboardAvoidingView: View { @State private var text = "" @FocusState private var isFocused: Bool var body: some View { ScrollView { TextField("输入", text: $text) .focused($isFocused) .padding() .background(Color.gray.opacity(0.2)) } .onTapGesture { isFocused = false } } } ``` --- ## Swift Concurrency 避坑 ### 常见错误 | 错误做法 | 正确做法 | |---------|---------| | ❌ nonisolated 函数访问 @Published | ✅ 用 @MainActor 包装 | | ❌ 跨线程传递 UIView | ✅ 始终在主线程操作 | | ❌ Task 不保存引用 | ✅ 存储 Task 以支持取消 | | ❌ 忘记 CancellationError | ✅ 调用 Task.checkCancellation() | | ❌ actor 内部用锁 | ✅ actor 天然线程安全 | | ❌ 传递非 Sendable 闭包 | ✅ 确保闭包捕获值是 Sendable | ### @MainActor 传递规则 ```swift @MainActor class ViewModel { func update() { /* 主线程 */ } } // ✅ 正确：await 后自动回到主线程 let vm = ViewModel() Task { @MainActor in await someAsyncMethod() vm.update() // 安全 } // ❌ 错误：非隔离上下文访问 Task { await someAsyncMethod() // vm.update() // ❌ 编译错误 } ``` --- # Widget 开发 - [widget.md](references/widget.md) — TimelineProvider / App Group / Interactive Widget / Lock Screen Widget # 国际化与本地化 - [localization.md](references/localization.md) — NSLocalizedString / String Catalog / 格式化 / RTL / App Store 本地化 # Swift Concurrency 权威参考 - [swift-concurrency.md](references/swift-concurrency.md) — async/await / TaskGroup / MainActor / Actor / Sendable / Swift 6 ## 快速参考 ### SwiftUI 状态装饰器速查 | 装饰器 | 作用域 | 父传子 | 创建者 | |--------|--------|--------|--------| | @State | 局部 | ❌ | 视图 | | @Binding | 局部 | ✅ | 视图 | | @StateObject | 局部 | ❌ | 视图 | | @ObservedObject | 局部 | ✅ | 父视图 | | @EnvironmentObject | 全局 | ✅ | 任意 | | @AppStorage | 全局 | ✅ | UserDefaults | | @SceneStorage | 全局 | ✅ | Scene | | @FocusState | 局部 | ✅ | 视图 | | @ScaledMetric | 局部 | ✅ | 视图 | ### UIKit vs SwiftUI 生命周期 | 阶段 | UIKit | SwiftUI | |------|-------|---------| | 创建 | `init` | `@State init` | | 加载视图 | `loadView` | body | | 视图加载 | `viewDidLoad` | `.task` | | 即将显示 | `viewWillAppear` | `.onAppear` | | 已显示 | `viewDidAppear` | — | | 即将消失 | `viewWillDisappear` | `.onDisappear` | | 已消失 | `viewDidDisappear` | — | | 内存警告 | `didReceiveMemoryWarning` | `.onChange` | ### iOS 版本支持速查 | API | 最低版本 | |-----|---------| | NavigationStack | iOS 16+ | | @MainActor | iOS 16+ / Swift 5.5+ | | SwiftUI Charts | iOS 16+ | | AnyCancellable store | iOS 13+ | | AsyncSequence | Swift 5.5+ | | WidgetKit | iOS 14+ | | Live Activities | iOS 16.1+ | | Interactive Widget | iOS 17+ | ### Auto Layout 速查 ```swift // 核心约束 label.translatesAutoresizingMaskIntoConstraints = false NSLayoutConstraint.activate([ label.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 16), label.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -16), label.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor), label.heightAnchor.constraint(greaterThanOrEqualToConstant: 44) ]) // SnapKit view.snp.makeConstraints { make in make.edges.equalToSuperview().inset(16) make.height.greaterThanOrEqualTo(100) make.width.equalToSuperview().multipliedBy(0.5) } // 优先级 .widthAnchor.constraint(equalToConstant: 100).priority = .defaultHigh // 750 .widthAnchor.constraint(equalToConstant: 50).priority = .defaultLow // 250 .widthAnchor.constraint(equalToConstant: 0).priority = .required // 1000 ``` ### 网络状态速查 | 状态 | SwiftUI | UIKit | |------|---------|-------| | 空闲 | `isLoading = false` | `state = .idle` | | 加载中 | `isLoading = true` | `state = .loading` | | 成功 | `@Published var items` | `delegate?.didFinish` | | 错误 | `@Published var error` | `delegate?.didFail` | ### Combine 操作符速查 | 操作符 | 用途 | 示例 | |--------|------|------| | `map` | 转换值 | `.map { $0 * 2 }` | | `filter` | 过滤 | `.filter { $0 > 0 }` | | `flatMap` | 展平 | `.flatMap { $0.publisher }` | | `debounce` | 防抖 | `.debounce(for: .milliseconds(300), scheduler: RunLoop.main)` | | `throttle` | 节流 | `.throttle(for: .seconds(1), scheduler: RunLoop.main, latest: true)` | | `combineLatest` | 合并 | `Publishers.CombineLatest(a, b)` | | `merge` | 合并同类型 | `a.merge(with: b)` | | `catch` | 错误处理 | `.catch { Just(default) }` | | `retry` | 重试 | `.retry(3)` | | `zip` | 配对 | `a.zip(b)` | ### Auto Layout 速查 ```swift // 核心约束 label.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 16) label.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -16) label.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor) label.heightAnchor.constraint(greaterThanOrEqualToConstant: 44) // SnapKit view.snp.makeConstraints { make in make.edges.equalToSuperview().inset(16) make.height.greaterThanOrEqualTo(100) } // 优先级 .widthAnchor.constraint(equalToConstant: 100).priority = .defaultHigh .widthAnchor.constraint(equalToConstant: 50).priority = .defaultLow ``` ### Widget 尺寸速查 | 尺寸 | 宽度 | 高度 | 用途 | |------|------|------|------| | systemSmall | 155pt | 155pt | 单指标 | | systemMedium | 329pt | 155pt | 双指标 | | systemLarge | 329pt | 345pt | 列表卡片 | | accessoryCircular | — | — | 锁屏圆形 | | accessoryRectangular | — | — | 锁屏矩形 | ### 常用尺寸速查 | 场景 | 尺寸 | |------|------| | 最小点击区域 | 44pt | | 标准间距 | 16pt | | 大间距 | 24pt | | 安全区留边 | 16pt | | TabBar 高度 | 49pt | | NavigationBar 高度 | 44pt | | Widget 圆角 | 20pt | | 按钮圆角 | 8pt | | 图片圆角 | 12pt | ### Swift Concurrency 速查 ```swift // async/await func fetch() async throws -> Data // Task Task { await fetch() } Task.detached { await fetch() } // TaskGroup await withTaskGroup(of: Data.self) { group in group.addTask { await fetch() } } // MainActor @MainActor func update() { } Task { @MainActor in update() } // Sendable struct User: Sendable { let id: String } actor SafeCounter { } // 取消 Task.checkCancellation() Task.isCancelled task.cancel() ``` ### 生命周期速查 | 事件 | SwiftUI | UIKit | |------|---------|-------| | 视图出现 | `.onAppear` | `viewDidAppear` | | 视图消失 | `.onDisappear` | `viewDidDisappear` | | 应用激活 | `.onReceive` | `applicationDidBecomeActive` | | 应用休眠 | — | `applicationWillResignActive` | ## 输出格式规范当使用本技能回答用户问题时，遵循以下格式： ### 回复结构 1. **直接回答** — 一段简洁的话给出核心答案 2. **代码示例** — 提供完整的 SwiftUI/UIKit 代码（如需） 3. **实现要点** — 关键步骤和注意事项 4. **避坑提醒** — 常见错误+正确做法 ### 示例回复（网络请求） > SwiftUI 推荐使用 async/await 处理网络请求。定义一个 `NetworkService` actor 封装 `URLSession`，在 ViewModel 中用 `@Published` 管理状态。示例：定义 `fetch` 泛型方法，用 `Task` 调用并更新 `@Published` 属性。错误处理用 `do-catch`，始终给用户反馈。 ### 禁用格式 - ❌ 不要显式分层（避免"第一层/第二层/框架分析"等字眼） - ❌ 不要长篇解释概念，要直接给出实现 - ❌ 不要只给代码片段，要给完整可运行的示例 - ✅ 输出应是一段干净的话 + 完整代码 FILE:README.md # iOS 开发技能 iOS/macOS 应用开发与 Swift 6.3 语言权威参考合集，基于 SwiftUI + UIKit。 ## 概述本 skill 覆盖 iOS/macOS 完整开发知识体系，包括： - **SwiftUI** — 声明式 UI、状态管理、Navigation、数据绑定 - **UIKit** — 视图控制器、Auto Layout、SnapKit、生命周期 - **Swift 语言** — 类型系统、集合、闭包、协议、泛型、并发（async/await/actor） - **架构模式** — MVVM、依赖注入、Combine 响应式编程 - **网络层** — URLSession、async-await、REST API - **性能优化** — LazyVStack、图片缓存、预取 - **测试** — XCTest 单元测试、XCUITest UI 测试 - **Widget** — WidgetKit、Live Activities - **持久化** — UserDefaults、SQLite、FileManager - **App 分发** — TestFlight、App Store、签名 ## 核心章节 ### 架构与基础 | 章节 | 内容 | |------|------| | [核心架构](SKILL.md#核心架构) | MVVM 架构（SwiftUI）、UIKit 架构对比、iOS 生命周期 | | [SwiftUI 基础](SKILL.md#SwiftUI-基础) | 页面结构、组件层级、状态装饰器 | | [状态管理](SKILL.md#状态管理) | @State/@Binding/@StateObject/@ObservedObject/@EnvironmentObject | | [Navigation 导航模式](SKILL.md#Navigation-导航模式) | NavigationStack、TabBar、Sheet、路由 | | [网络层](SKILL.md#网络层) | URLSession、async-await、APIClient、错误处理 | | [依赖注入](SKILL.md#依赖注入) | SwiftUI Environment、UIKit Protocol 注入 | ### Swift 语言权威参考 | 章节 | 内容 | |------|------| | [类型系统](SKILL.md#类型系统) | 基本类型、类型推断、类型别名 | | [Optional 可选类型](SKILL.md#Optional-可选类型) | 解包方式、?? 操作符、guard let | | [Tuple 元组](SKILL.md#Tuple-元组) | 多元组、命名、解构 | | [集合类型](SKILL.md#集合类型) | Array、Set、Dictionary | | [函数](SKILL.md#函数) | 参数标签、默认参数、可变参数、inout | | [闭包](SKILL.md#闭包) | @escaping、尾随闭包、捕获列表 | | [枚举](SKILL.md#枚举) | 关联值、原始值、Switch 匹配 | | [结构体与类](SKILL.md#结构体与类) | 值类型 vs 引用类型、方法、构造器 | | [属性](SKILL.md#属性) | 存储属性、计算属性、属性包装器 | | [协议与泛型](SKILL.md#协议与泛型) | 协议扩展、泛型约束、关联类型 | | [访问控制](SKILL.md#访问控制) | public/private/internal/fileprivate/open | | [错误处理](SKILL.md#错误处理) | throws/do-catch/try/Result | ### Swift 6 并发 | 章节 | 内容 | |------|------| | [Swift 6 Concurrency](SKILL.md#Swift-6-Concurrency) | async/await、actor、Task、Sendable | | [Swift Concurrency 深度](SKILL.md#Swift-Concurrency-深度) | Structured Concurrency、TaskGroup、MainActor | | [Swift Concurrency 避坑](SKILL.md#Swift-Concurrency-避坑) | 常见错误与正确做法 | ### UIKit 进阶 | 章节 | 内容 | |------|------| | [UIKit 进阶](SKILL.md#UIKit-进阶) | Auto Layout（NSLayoutConstraint + SnapKit）、手势识别、动画 | | [Widget 开发](SKILL.md#Widget-开发) | WidgetKit、Timeline Provider、Intent | | [国际化与本地化](SKILL.md#国际化与本地化) | String Catalog、多语言支持 | ### 工程与质量 | 章节 | 内容 | |------|------| | [性能优化](SKILL.md#性能优化) | LazyVStack、图片缓存、预取、后台任务 | | [测试策略](SKILL.md#测试策略) | XCTest 单元测试、XCUITest UI 测试、快照测试 | | [数据持久化](SKILL.md#数据持久化) | UserDefaults、SQLite、FileManager、AppStorage | | [App 分发与发布](SKILL.md#App-分发与发布) | TestFlight、App Store Connect、签名配置 | | [避坑指南](SKILL.md#避坑指南) | 常见错误、SwiftUI/UIKit 陷阱 | ## 快速参考 ### SwiftUI 状态装饰器 | 装饰器 | 作用域 | 父传子 | 创建者 | |--------|--------|--------|--------| | @State | 局部 | ❌ | 视图 | | @Binding | 局部 | ✅ | 视图 | | @StateObject | 局部 | ❌ | 视图 | | @ObservedObject | 局部 | ✅ | 父视图 | | @EnvironmentObject | 全局 | ✅ | 任意 | | @AppStorage | 全局 | ✅ | UserDefaults | | @SceneStorage | 全局 | ✅ | Scene | ### iOS 版本支持 | API | 最低版本 | |-----|---------| | NavigationStack | iOS 16+ | | @MainActor | iOS 16+ / Swift 5.5+ | | SwiftUI Charts | iOS 16+ | | AsyncSequence | Swift 5.5+ | | WidgetKit | iOS 14+ | | Live Activities | iOS 16.1+ | | Interactive Widget | iOS 17+ | ### 最小触摸目标 **44 × 44 pt**（Apple HIG 规定） ## 完整示例 ### SwiftUI + MVVM ```swift // Model struct User: Identifiable, Codable { let id: String let name: String let email: String } // ViewModel @MainActor class UserListViewModel: ObservableObject { @Published var users: [User] = [] @Published var isLoading = false @Published var error: String? func loadUsers() async { isLoading = true defer { isLoading = false } do { users = try await api.fetchUsers() } catch { self.error = error.localizedDescription } } } // View struct UserListView: View { @StateObject private var vm = UserListViewModel() var body: some View { NavigationStack { Group { if vm.isLoading { ProgressView() } else if let error = vm.error { Text("Error: \(error)") .foregroundColor(.red) } else { List(vm.users) { user in NavigationLink(destination: UserDetailView(user: user)) { HStack { Text(user.name) Spacer() Text(user.email) .foregroundColor(.secondary) } } } } } .navigationTitle("用户") .task { await vm.loadUsers() } } } } ``` ### UIKit + Auto Layout（SnapKit） ```swift import UIKit import SnapKit class UserListViewController: UIViewController { private let tableView = UITableView(frame: .zero, style: .insetGrouped) private var users: [User] = [] override func viewDidLoad() { super.viewDidLoad() setupUI() loadData() } private func setupUI() { title = "用户" view.backgroundColor = .systemGroupedBackground tableView.delegate = self tableView.dataSource = self tableView.register(UITableViewCell.self, forCellReuseIdentifier: "Cell") view.addSubview(tableView) tableView.snp.makeConstraints { make in make.edges.equalToSuperview() } } private func loadData() { Task { do { users = try await APIClient.shared.get([User].self, path: "/users") tableView.reloadData() } catch { showError(error) } } } } extension UserListViewController: UITableViewDataSource, UITableViewDelegate { func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int { return users.count } func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell { let cell = tableView.dequeueReusableCell(withIdentifier: "Cell", for: indexPath) let user = users[indexPath.row] var config = cell.defaultContentConfiguration() config.text = user.name config.secondaryText = user.email cell.contentConfiguration = config return cell } func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) { tableView.deselectRow(at: indexPath, animated: true) let user = users[indexPath.row] let detailVC = UserDetailViewController(user: user) navigationController?.pushViewController(detailVC, animated: true) } } ``` ### Swift async/await 网络请求 ```swift actor NetworkService { static let shared = NetworkService() func fetch(_ type: T.Type, from url: URL) async throws -> T { let (data, _) = try await URLSession.shared.data(from: url) return try JSONDecoder().decode(T.self, from: data) } } struct User: Codable, Identifiable { let id: String let name: String let email: String } // 使用 Task { let users = try await NetworkService.shared.fetch([User].self, from: url) } ``` ### Swift Concurrency（async/await/actor） ```swift // actor 线程安全类 actor UserStore { private var users: [User] = [] func add(_ user: User) { users.append(user) } func all() -> [User] { return users } } // Task 和 async/await func fetchUser(id: String) async throws -> User { let (data, _) = try await URLSession.shared.data(from: url) return try JSONDecoder().decode(User.self, from: data) } // MainActor 确保 UI 更新在主线程 @MainActor class ViewModel: ObservableObject { @Published var user: User? func load() async { user = try? await fetchUser(id: "1") } } ``` ## 参考文档 | 文件 | 行数 | 内容 | |------|------|------| | swift-concurrency.md | 408 | async/await/actor/Task/Sendable/TaskGroup | | uikit-advanced.md | 504 | Auto Layout/SnapKit/手势/动画/TableView/CollectionView | | swiftui-advanced.md | 400 | 高级组件、GeometryReader、偏好设置 | | widget.md | 339 | WidgetKit/Timeline/Live Activities | | uikit-basics.md | 212 | UIViewController/UIView/生命周期 | | swiftui-basics.md | 234 | 基础组件、@State、@Binding、Navigation | | localization.md | 279 | String Catalog/多语言/日期格式化 | | app-store-distribution.md | 197 | TestFlight/App Store/签名 | | standard-library.md | 411 | Swift 标准库 API | | protocols.md | 206 | 协议进阶、Equatable/Hashable/Codable | | generics.md | 203 | 泛型约束、关联类型、泛型上下文 | | closures.md | 130 | 闭包逃逸、尾随闭包、捕获语义 | | collection-types.md | 191 | Array/Set/Dictionary 深度用法 | | advanced-features.md | 253 | 高级特性、内存管理、反射 | ## 避坑指南 | 错误做法 | 正确做法 | |---------|---------| | ❌ 在主线程执行网络请求 | ✅ async/await 自动后台执行 | | ❌ 不处理网络错误 | ✅ always try-catch + user feedback | | ❌ @State 用于引用类型 | ✅ @StateObject 用于 class | | ❌ 不用 LazyVStack 处理大列表 | ✅ 懒加载避免性能问题 | | ❌ 硬编码 URL | ✅ Configuration/Environment | | ❌ @StateObject 在 body 中创建 | ✅ @StateObject 在视图外初始化 | | ❌ 循环引用（delegate/closure） | ✅ 记得用 `[weak self]` | ## 来源 > Apple Developer Documentation > - SwiftUI: https://developer.apple.com/documentation/swiftui > - UIKit: https://developer.apple.com/documentation/uikit > - Xcode: https://developer.apple.com/documentation/xcode > - Combine: https://developer.apple.com/documentation/combine > > 版本：Swift 6.3 / iOS 18+ > 更新日期：2026-04-23 FILE:references/advanced-features.md # Swift 高级特性 > 来源：The Swift Programming Language (6.3) - Advanced Features > https://docs.swift.org/swift-book/documentation/the-swift-programming-language/ > 抓取时间：2026-04-23 ## 内存安全 Swift 确保只使用有效内存： | 特性 | 说明 | |------|------| | 栈安全 | 线程局部存储，先进后出 | | 引用计数 | 类实例自动管理 | | 无垂悬指针 | 编译器确保 | | 无未初始化内存 | 必须初始化 | ## 自动引用计数 ARC ```swift class Person { let name: String init(name: String) { self.name = name } } var ref1: Person? var ref2: Person? var ref3: Person? ref1 = Person(name: "Alice") // ref1 strong ref2 = ref1 // ref2 strong ref3 = ref1 // ref3 strong // 现在有 3 个强引用 ref1 = nil // 还有 ref2, ref3 ref2 = nil // 还有 ref3 ref3 = nil // 引用计数 = 0，deinit 调用 ``` ### 强引用循环 ```swift class Person { let name: String var apartment: Apartment? // strong init(name: String) { self.name = name } } class Apartment { let unit: String var tenant: Person? // strong — 循环引用！ init(unit: String) { self.unit = unit } } var alice: Person? var unit4A: Apartment? alice = Person(name: "Alice") unit4A = Apartment(unit: "4A") alice!.apartment = unit4A unit4A!.tenant = alice // 循环引用！ alice = nil unit4A = nil // 内存泄漏！deinit 不会调用 ``` ### weak 和 unowned ```swift class Person { let name: String var apartment: Apartment? // weak init(name: String) { self.name = name } } class Apartment { let unit: String var tenant: Person? // strong init(unit: String) { self.unit = unit } } // weak 不增加引用计数，可选 // unowned 不增加引用计数，非可选（假设永不为 nil） ``` ### unowned 的使用场景 ```swift class Customer { let name: String var card: CreditCard? init(name: String) { self.name = name } } class CreditCard { let number: Int unowned let customer: Customer // 非可选 init(number: Int, customer: Customer) { self.number = number self.customer = customer } } // Customer 拥有 CreditCard，CreditCard 引用 Customer // 假设卡永远属于某个客户 ``` ### unowned vs weak | 修饰符 | 可选？ | 使用场景 | |--------|--------|---------| | weak | ✅ | 可能为 nil | | unowned | ❌ | 永不为 nil | ## 类型擦除 ### Any 和 AnyObject ```swift var things: [Any] = [] things.append(42) things.append("string") things.append({ $0 > 0 }) // AnyObject（类实例） var objects: [AnyObject] = [] objects.append(NSObject()) ``` ### 泛型类型擦除 ```swift // 类型擦除包装 struct AnySequence: Sequence { private var _makeIterator: () -> AnyIterator init(_ sequence: S) where S.Element == Element { _makeIterator = { AnyIterator(sequence.makeIterator()) } } func makeIterator() -> AnyIterator { return _makeIterator() } } ``` ## Opaque Types some ```swift // some 修饰返回类型 protocol Shape { func area() -> Double } func makeShape() -> some Shape { return Circle() } // some 保证： // 1. 返回具体类型一致 // 2. 编译器可优化 // 3. 隐藏实现细节 ``` ## 关键字速查 | 关键字 | 用途 | |--------|------| | `let` | 常量 | | `var` | 变量 | | `func` | 函数 | | `class` | 类 | | `struct` | 结构体 | | `enum` | 枚举 | | `protocol` | 协议 | | `extension` | 扩展 | | `init` | 构造器 | | `deinit` | 析构器 | | `guard` | 提前退出 | | `defer` | 延迟执行 | | `fallthrough` | switch 贯穿 | | `break` | 跳出循环/switch | | `continue` | 下一轮循环 | | `return` | 返回值 | | `throw` | 抛出错误 | | `try` | 尝试可能出错 | | `catch` | 捕获错误 | | `async` | 异步函数 | | `await` | 等待异步 | | `actor` | 隔离类型 | | `@escaping` | 逃逸闭包 | | `@autoclosure` | 自动闭包 | | `@available` | 版本检查 | | `@main` | 程序入口 | | `@discardableResult` | 可丢弃返回值 | | `@inlinable` | 可内联 | | `@testable` | 测试可见 | ## 声明属性速查 | 修饰符 | 适用 | 说明 | |--------|------|------| | `static` | 方法/属性 | 类型成员 | | `class` | 方法 | 可被重写 | | `final` | 类/方法 | 不可被继承/重写 | | `override` | 方法/属性 | 重写父类 | | `mutating` | 方法 | 修改 self | | `nonisolated` | 函数/属性 | 跨 actor 访问 | | `nonisolated(unsafe)` | 属性 | 显式跨域 | ## 访问控制速查 | 修饰符 | 模块内 | 模块外 | 继承 | |--------|--------|--------|------| | open | ✅ | ✅ 可继承/重写 | ✅ | | public | ✅ | ✅ | ❌ | | internal | ✅ | ❌ | ❌ | | fileprivate | 当前文件 | ❌ | ❌ | | private | 当前作用域 | ❌ | ❌ | ## 字符串插值 ```swift // 自定义插值 extension String.StringInterpolation { mutating func appendInterpolation(repeat count: Int, _ char: Character) { for _ in 0.. The Swift Programming Language (Swift 6.3) > https://docs.swift.org/swift-book/documentation/the-swift-programming-language/ FILE:references/app-store-distribution.md # iOS App Store 分发与发布 > 来源：Apple Developer Documentation — App Store Connect > URL: https://developer.apple.com/app-store-connect/ > 整理时间：2026-04-23 > 版本：iOS 17+ ## App Store Connect概览 ### App Store Connect 是核心平台所有 iOS App 的提交、审核、发布、统计分析都在 App Store Connect 完成。主要功能模块： - App 管理（版本管理、元数据、定价） - TestFlight（测试分发） - 销售与趋势（收入、下载） - 用户评论管理 - App Analytics（分析） ### TestFlight vs App Store | 维度 | TestFlight | App Store | |------|-----------|-----------| | 受众 | 内部测试 / 外部 Beta | 正式用户 | | 设备数 | 10000 台 | 无限制 | | 审核 | 24 小时（快速审核）| 1-7 天 | | 分发方式 | 邮箱 / 公测链接 | App Store 搜索 | | 生命周期 | 90 天 | 永久 | ## TestFlight 分发 ### 内部测试（自动） App Store Connect 自动分发给所有内部团队成员（100 人以内）。无需审核，提交后数分钟内可用。 ### 外部测试（需审核） 1. 创建测试组 2. 添加测试员（邮箱或公测链接） 3. 提交构建版本 4. Apple 审核（约 24-48 小时） 5. 审核通过后自动分发给测试员 ### 构建版本要求 | 要求 | 说明 | |------|------| | Xcode 版本 | 推荐最新稳定版 | | 最低 iOS | 设置合适的最低版本 | | 第三方 SDK | 确保无过期证书 | | 隐私清单 | 填写隐私采集说明 | | 构建号递增 | 每次递增 +1 | ### TestFlight 崩溃报告 ``` TestFlight 会自动收集崩溃日志 Xcode → Organizer → Crashes 可查看 ``` ## App Store 发布 ### 发布前检查清单 #### App 元数据 | 项目 | 要求 | |------|------| | App 名称 | ≤ 30 字符 | | 副标题 | ≤ 30 字符 | | 描述 | 描述 App 功能和特色 | | 关键词 | 100 字符以内，用逗号分隔 | | 类别 | 主类别 + 次类别各 1 个 | | 评分 | 根据内容选择适当年龄分级 | #### 视觉资产 | 资产 | 尺寸 | 说明 | |------|------|------| | App Icon | 1024×1024 | 无透明，无圆角 | | 截图 6.7" | 1290×2796 | 必填 | | 截图 6.5" | 1284×2778 | 必填 | | 截图 5.5" | 1242×2208 | 选填 | | iPad 截图 | 2048×2732 | 如有 iPad 版本 | | 宣传图 | 诱人的 Banner | 选填 | | App 预览视频 | 15-30 秒 | 选填 | #### 隐私与合规 | 项目 | 说明 | |------|------| | 隐私政策 URL | 必填（可使用 Firebase Hosting 托管） | | 年龄分级 | 根据内容选择 | | 版权 | 可选 | | 追踪透明度 | 如有广告，需申请追踪授权 | ### 定价与分发 | 定价层级 | 价格区间 | |----------|----------| | Free | 免费 | | Tier 1-87 | $0.99 - $999.99 | 分发选项： - 全球或指定国家/地区 - 自动或手动发布 - 预购功能（发布前接受订单） ### 提交审核 #### 审核时间 | App 类型 | 典型时间 | |----------|----------| | 新 App | 1-3 天 | | 更新 | 1-2 天 | | 热修补丁 | 加急请求 | #### 审核被拒原因（Top 5） | 原因 | 解决方案 | |------|---------| | 崩溃 / 无响应 | 充分测试后再提交 | | 功能不完整 | 明确说明 App 边界 | | 元数据误导 | 描述与实际功能一致 | | 重复 App | 差异化定位 | | 登录要求强制 | 至少支持游客浏览 | #### 申诉流程被拒后可在 App Store Connect 申诉： 1. 查看被拒详情 2. 修复问题或提交申诉 3. 申诉由另一个审核团队重审 ### 发布后操作 #### 推广资源 - Apple 开发者网站推广 - 社交媒体 announcement - Product Hunt 发布 - App Store 优化（ASO） #### 持续运营 | 任务 | 频率 | |------|------| | 查看用户评论 | 每天 | | 分析崩溃报告 | 每周 | | 查看销售报告 | 每月 | | 发布功能更新 | 按版本节奏 | | 监控竞品动态 | 持续 | ## 企业分发（In-House / Custom App） ### Apple Developer Enterprise Program 适合企业内部 App 分发，不经过 App Store。限制： - 成员需手动信任企业证书 - 仅限企业内部员工 - 每年 $299 ### MDM（移动设备管理）通过 Mobile Device Management 方案： - 托管式 App 分发 - 配置profiles安装 - 设备管理策略 ## 常用工具 | 工具 | 用途 | |------|------| | Transporter | 上传构建版本 | | App Store Connect API | 自动化管理 | | Fastlane | CI/CD 流水线 | | Xcode Cloud | Apple 原生 CI | ## 注意事项 1. **不要频繁提交**：每次审核有记录，频繁被拒影响账号信誉 2. **测试设备覆盖**：涵盖所有目标 iOS 版本 3. **隐私清单**：iOS 17+ 强制要求 PrivacyInfo.xcprivacy 4. **App Icon 规范**：PNG 无 Alpha 通道，RGB 色彩 5. **截图不含设备边框**：只提交纯截图 ## App Store 搜索优化（ASO） ### 关键词优化 | 策略 | 说明 | |------|------| | 标题权重最高 | 关键词放前面 | | 逗号分隔 | 搜索匹配更精确 | | 竞品词 | 调研竞品关键词 | | 地域词 | 覆盖目标市场 | ### 评分与评论 | 指标 | 影响 | |------|------| | 评分 ≥ 4.0 | 搜索排名权重 | | 近期评论 | 算法实时权重 | | 评论回复 | 用户信任度 | ### 常见 ASO 错误 | 错误 | 影响 | |------|------| | 关键词堆砌 | 审核被拒 | | 截图文字过多 | 用户流失 | | 描述复制竞品 | 降权 | ## 来源 > Apple Developer Documentation — App Store Connect > https://developer.apple.com/app-store-connect/ > Apple App Store Review Guidelines > https://developer.apple.com/app-store/review/guidelines/ FILE:references/closures.md # Swift 闭包 > 来源：The Swift Programming Language (Swift 6.3) — Closures > URL: https://docs.swift.org/swift-book/documentation/the-swift-programming-language/closures/ > 整理时间：2026-04-23 ## 三种闭包形式 | 类型 | 有名字 | 捕获值 | |------|--------|--------| | 全局函数 | ✅ | ❌ | | 嵌套函数 | ✅ | ✅ | | 闭包表达式 | ❌ | ✅ | ## 闭包表达式语法 ```swift { (params) -> ReturnType in statements } ``` ### 类型推断 ```swift // 完整形式 reversedNames = names.sorted(by: { (s1: String, s2: String) -> Bool in return s1 > s2 }) // 推断后 reversedNames = names.sorted(by: { s1, s2 in return s1 > s2 }) // 单表达式隐式返回 reversedNames = names.sorted(by: { s1, s2 in s1 > s2 }) // 缩写参数名 reversedNames = names.sorted(by: { $0 > $1 }) // 操作符方法 reversedNames = names.sorted(by: >) ``` ## 尾随闭包 ```swift // 普通写法 arr.map({ (x: Int) -> Int in x * 2 }) // 尾随闭包 arr.map { $0 * 2 } // 最后一个参数是闭包 loadPicture(from: server) { picture in someView.currentPicture = picture } onFailure: { print("Error") } ``` ## 逃逸闭包 @escaping ```swift var completionHandlers: [() -> Void] = [] func someFunctionWithEscapingClosure(completionHandler: @escaping () -> Void) { completionHandlers.append(completionHandler) } // 逃逸闭包需要显式 self class SomeClass { var x = 10 func doSomething() { someFunctionWithEscapingClosure { self.x = 100 } } } // capture list 打破循环引用 someFunctionWithEscapingClosure { [weak self] in self?.x = 100 } ``` ## 捕获值 ```swift func makeIncrementer(forIncrement amount: Int) -> () -> Int { var runningTotal = 0 func incrementer() -> Int { runningTotal += amount return runningTotal } return incrementer } let incrementByTen = makeIncrementer(forIncrement: 10) incrementByTen() // 10 incrementByTen() // 20 ``` ## @autoclosure ```swift var customersInLine = ["Chris", "Alex", "Ewa"] // 普通闭包 func serve(customer provider: () -> String) { print("Now serving \(provider())!") } serve(customer: { customersInLine.remove(at: 0) }) // @autoclosure（自动包装表达式） func serve(customer provider: @autoclosure () -> String) { print("Now serving \(provider())!") } serve(customer: customersInLine.remove(at: 0)) // 无需 {} ``` ### @autoclosure 注意事项 | 注意事项 | 说明 | |---------|------| | 仅适合无参数闭包 | 参数为 `() -> T` | | 慎用 | 隐藏闭包执行时机 | | 调试困难 | 调用栈不直观 | | 仅用于 API 设计 | Swift 标准库内部使用 | ## 闭包是引用类型 ```swift let alsoIncrementByTen = incrementByTen alsoIncrementByTen() // 30 incrementByTen() // 40 // 两个引用指向同一个闭包实例 ``` ## 使用场景 | 场景 | 示例 | |------|------| | 数组排序 | `arr.sorted { $0 > $1 }` | | 异步回调 | `fetch { data in ... }` | | 事件处理 | `button.onTap { ... }` | | 延迟执行 | `DispatchQueue.main.asyncAfter { ... }` | | 条件判断 | `arr.filter { $0 > 0 }` | ### 常见高阶函数 ```swift // map：转换每个元素 [1, 2, 3].map { $0 * 2 } // [2, 4, 6] // filter：过滤元素 [1, 2, 3].filter { $0 > 1 } // [2, 3] // reduce：聚合 [1, 2, 3].reduce(0) { $0 + $1 } // 6 // flatMap：扁平化 [[1, 2], [3]].flatMap { $0 } // [1, 2, 3] // compactMap：去除 nil [1, nil, 3].compactMap { $0 } // [1, 3] ``` ## 闭包与函数 ### 闭包作为返回值 ```swift func makeAdder(n: Int) -> (Int) -> Int { return { $0 + n } } let addFive = makeAdder(n: 5) addFive(3) // 8 ``` ### 闭包作为参数 ```swift func transform(_ array: [Int], using fn: (Int) -> Int) -> [Int] { return array.map(fn) } transform([1, 2, 3]) { $0 * 2 } // [2, 4, 6] ``` ## 性能注意事项 1. **避免循环引用**：始终使用 `[weak self]` 或 `[unowned self]` 2. **避免过长的闭包**：超过 20 行考虑提取为独立函数 3. **尾随闭包优先**：可读性更好 4. **@escaping 谨慎使用**：仅在必要时标记 ## 内存管理 ### 内存管理原则 1. **闭包默认捕获变量引用**（强引用） 2. **逃逸闭包必须显式处理 self 引用** 3. **使用 `[weak self]` 打破强引用环** 4. **避免在闭包内直接使用 `self`** ### weak vs unowned | 场景 | 选择 | 原因 | |------|------|------| | ViewController → Closure | `weak self` | ViewController 可能被释放 | | Self 生命周期确定 | `unowned self` | 避免 Optional 解包 | | 值类型 | 无需捕获列表 | 不存在引用语义 | | 闭包内多次使用 | `weak self` + guard | 避免多次判断 | ### 循环引用检测 ```swift // ❌ 循环引用 class MyClass { var handler: (() -> Void)! func setup() { handler = { self.doSomething() } // self → 闭包 → self } } // ✅ 正确 class MyClass { var handler: (() -> Void)! func setup() { handler = { [weak self] in self?.doSomething() } } } // ✅ unowned（确定不会 nil 时） class MyClass { var handler: (() -> Void)! func setup() { handler = { [unowned self] in self.doSomething() } } } ``` ### 内存泄漏场景 | 场景 | 原因 | 解决方案 | |------|------|---------| | 网络请求回调 | ViewController 持有闭包，闭包持有 VC | `[weak self]` | | Timer 回调 | Timer 持有闭包 | `invalidate()` | | 动画完成回调 | View 持有闭包 | 使用 `nil` 检查 | | Notification 回调 | 持有闭包 | `removeObserver` | ### 闭包常见错误 | 错误 | 后果 | 正确做法 | |------|------|---------| | 忘记 `[weak self]` | 内存泄漏 | `[weak self]` | | `[weak self]` 后不判断 | 运行时崩溃 | `guard let self else { return }` | | `@escaping` 漏标 | 编译错误 | 添加 `@escaping` | | 闭包内递归调用 | 栈溢出 | 确保终止条件 | ## 来源 > The Swift Programming Language (Swift 6.3) — Closures > https://docs.swift.org/swift-book/documentation/the-swift-programming-language/closures/ ## 附录速查 ### 语法速查 | 语法 | 示例 | |------|------| | 标准闭包 | `{ x, y in x + y }` | | 省略参数 | `{ $0 + $1 }` | | 省略返回 | `arr.sorted { $0 > $1 }` | | 尾随闭包 | `arr.map { $0 * 2 }` | | @escaping | 闭包存储后执行 | | @autoclosure | 表达式自动包装 | | 捕获列表 | `[weak self], [unowned self]` | ### Swift 标准库常用闭包参数 | 方法 | 闭包签名 | 说明 | |------|---------|------| | `map` | `(Element) -> T` | 转换 | | `filter` | `(Element) -> Bool` | 过滤 | | `reduce` | `(Result, Element) -> Result` | 聚合 | | `forEach` | `(Element) -> Void` | 遍历 | | `compactMap` | `(Element) -> T?` | 去除 nil | | `flatMap` | `(Element) -> [T]` | 扁平化 | | `first(where:)` | `(Element) -> Bool` | 查找首个 | | `contains` | `(Element) -> Bool` | 是否包含 | | `allSatisfy` | `(Element) -> Bool` | 全部满足 | | `firstIndex` | `(Element) -> Int?` | 查找下标 | | `lastIndex` | `(Element) -> Int?` | 查找末尾下标 | | `last(where:)` | `(Element) -> Element?` | 查找末尾元素 | | `partition` | `(Element) -> Bool` | 分区重排 | | `split` | `(Element) -> Bool` | 按条件分割 | | `min()` | `() -> Element?` | 最小值 | | `max()` | `() -> Element?` | 最大值 | | `sorted()` | `() -> [Element]` | 排序副本 | | `shuffled()` | `() -> [Element]` | 随机打乱 | | `reversed()` | `() -> [Element]` | 反向副本 | | `prefix` | `(Int) -> [Element]` | 前缀切片 | | `suffix` | `(Int) -> [Element]` | 后缀切片 | | `dropFirst` | `(Int) -> [Element]` | 去除前缀 | | `dropLast` | `(Int) -> [Element]` | 去除后缀 | | `chunked` | `(Int) -> [[Element]]` | 分块 | | `chunked(into:)` | `([Element]) -> [[Element]]` | 按大小分块 | | `unique` | `() -> [Element]` | 去重（需自定义）| | `count` | `() -> Int` | 元素个数 | | `isEmpty` | `() -> Bool` | 是否为空 | | `randomElement` | `() -> Element?` | 随机元素 | | `reduce(into:)` | `((inout Result, Element) -> ()) -> Result` | 聚合 | | `enumerated()` | `() -> [(offset: Int, element: Element)]` | 带索引 | | `zip` | `(Sequence) -> [(A, B)]` | 合并序列 | | `product` | `() -> Int` | 元素乘积 | FILE:references/collection-types.md # Swift 集合类型 > 来源：The Swift Programming Language (6.3) - Collection Types > https://docs.swift.org/swift-book/documentation/the-swift-programming-language/collectiontypes/ > 抓取时间：2026-04-23 ## 三大集合类型 | 类型 | 有序 | 可重复 | 用途 | |------|------|--------|------| | Array | ✅ | ✅ | 顺序列表 | | Set | ❌ | ❌ | 无序唯一值 | | Dictionary | ❌ | — | 键值对 | ## Array ### 创建 ```swift // 空数组 var empty: [Int] = [] var anotherEmpty = [Int]() // 默认值 var threeDoubles = Array(repeating: 0.0, count: 3) // [0.0, 0.0, 0.0] // 字面量 var shoppingList = ["Eggs", "Milk"] // 类型推断 [String] // 合并 var combined = array1 + array2 ``` ### 操作 ```swift // 增 shoppingList.append("Flour") shoppingList += ["Baking Powder"] // 插入 shoppingList.insert("Maple Syrup", at: 0) // 删除 let first = shoppingList.removeFirst() let last = shoppingList.removeLast() shoppingList.remove(at: 0) shoppingList.removeAll() // 访问 let first = shoppingList[0] let range = shoppingList[1...3] // 修改 shoppingList[0] = "Six eggs" shoppingList[1...3] = ["A", "B"] // 可变长 // 属性 shoppingList.count shoppingList.isEmpty // 遍历 for item in shoppingList { } for (index, value) in shoppingList.enumerated() { } ``` ## Set ### 创建 ```swift var letters = Set() var favoriteGenres: Set = ["Rock", "Classical", "Hip hop"] ``` ### 操作 ```swift // 增删 favoriteGenres.insert("Jazz") if let removed = favoriteGenres.remove("Rock") { } // 查询 favoriteGenres.contains("Rock") favoriteGenres.count favoriteGenres.isEmpty // 遍历 for genre in favoriteGenres { } for genre in favoriteGenres.sorted() { } // 排序遍历 ``` ### 集合运算 ```swift let oddDigits: Set = [1, 3, 5, 7, 9] let evenDigits: Set = [0, 2, 4, 6, 8] oddDigits.union(evenDigits) // 并集 oddDigits.intersection(evenDigits) // 交集 oddDigits.subtracting(singleDigitPrimeNumbers) // 差集 oddDigits.symmetricDifference(evenDigits) // 对称差集 ``` ### 集合关系 ```swift houseAnimals.isSubset(of: farmAnimals) // 子集 farmAnimals.isSuperset(of: houseAnimals) // 超集 farmAnimals.isDisjoint(with: cityAnimals) // 不相交 houseAnimals.isStrictSubset(of: farmAnimals) // 真子集 ``` ## Dictionary ### 创建 ```swift var emptyDict: [String: Int] = [:] var airports = ["YYZ": "Toronto", "DUB": "Dublin"] ``` ### 操作 ```swift // 增改 airports["LHR"] = "London" airports["LHR"] = "London Heathrow" // 修改 // 安全更新 if let old = airports.updateValue("Dublin Airport", forKey: "DUB") { print("旧值: \(old)") } // 访问（返回 Optional） if let name = airports["DUB"] { print(name) } // 删除 airports["APL"] = nil if let removed = airports.removeValue(forKey: "DUB") { } // 遍历 for (code, name) in airports { } for code in airports.keys { } for name in airports.values { } // 转换 let codes = [String](airports.keys) let names = [String](airports.values) ``` ## 性能特性 | 操作 | Array | Set | Dictionary | |------|-------|-----|------------| | 读取 | O(1) | O(1) | O(1) | | 插入(尾) | O(1) amortized | — | — | | 插入(随机) | O(n) | O(n) | O(n) | | 删除(随机) | O(n) | O(n) | O(n) | ## 常用扩展 ```swift // 过滤 let filtered = array.filter { $0 > 0 } // 映射 let doubled = array.map { $0 * 2 } // 展平 let flat = nestedArray.flatMap { $0 } // 排序 let sorted = array.sorted() let sortedDesc = array.sorted(by: >) // 查找 if let first = array.first(where: { $0 > 5 }) { } // reduce let sum = array.reduce(0) { $0 + $1 } let sum2 = array.reduce(0, +) // contains array.contains(where: { $0 > 5 }) // allSatisfy array.allSatisfy { $0 > 0 } ``` ## 性能注意事项 | 操作 | 时间复杂度 | 说明 | |------|-----------|------| | `append` | O(1) 均摊 | Array 末尾追加 | | `insert` | O(n) | 中间插入 | | `remove(at:)` | O(n) | 删除元素 | | `contains` | O(n) | 线性搜索 | | `Dictionary` 查找 | O(1) | 哈希表 | ## 来源 > The Swift Programming Language (Swift 6.3) — Collection Types > https://docs.swift.org/swift-book/documentation/the-swift-programming-language/collectiontypes/ FILE:references/generics.md # Swift 泛型参考 > 来源：The Swift Programming Language (6.3) - Generics > https://docs.swift.org/swift-book/documentation/the-swift-programming-language/generics/ > 抓取时间：2026-04-23 ## 泛型函数 ```swift func swapTwoValues(_ a: inout T, _ b: inout T) { let temp = a a = b b = temp } var i = 3, j = 5 swapTwoValues(&i, &j) // T = Int swapTwoValues(&i, &j) // T = Double ``` ## 类型约束 ```swift // Equatable 约束 func findIndex(of valueToFind: T, in array: [T]) -> Int? { for (index, value) in array.enumerated() { if value == valueToFind { return index } } return nil } // Comparable 约束 func maximum(_ array: [T]) -> T? { return array.max() } ``` ## 协议约束 ```swift // 继承约束 func send(_ request: Request) { } // 类约束 class SomeClass { } protocol SomeProtocol { } func someFunction(some: T, item: U) { } ``` ## 泛型类型 ```swift struct Stack { var items: [Element] = [] mutating func push(_ item: Element) { items.append(item) } mutating func pop() -> Element { items.removeLast() } var top: Element? { items.last } } var stack = Stack() stack.push(10) stack.push(20) print(stack.pop()) // 20 ``` ## 泛型扩展 ```swift extension Stack { var topItem: Element? { return items.isEmpty ? nil : items[items.count - 1] } } if let top = stack.topItem { print(top) } ``` ## 关联类型 ```swift protocol Container { associatedtype Item mutating func append(_ item: Item) var count: Int { get } subscript(i: Int) -> Item { get } } struct IntStack: Container { var items = [Int]() mutating func push(_ item: Int) { items.append(item) } mutating func pop() -> Int { items.removeLast() } // 关联类型实现 typealias Item = Int mutating func append(_ item: Int) { push(item) } var count: Int { items.count } subscript(i: Int) -> Int { items[i] } } // 泛型版本 struct GenericStack: Container { var items = [Element]() mutating func push(_ item: Element) { items.append(item) } mutating func pop() -> Element { items.removeLast() } mutating func append(_ item: Element) { items.append(item) } var count: Int { items.count } subscript(i: Int) -> Element { items[i] } } ``` ## where 子句 ```swift // 函数约束 func allItemsMatch (_ someContainer: C1, _ anotherContainer: C2) -> Bool where C1.Item == C2.Item, C1.Item: Equatable { if someContainer.count != anotherContainer.count { return false } for i in 0.. [Item] { return items.sorted() } } // 关联类型约束 protocol ComparableContainer: Container where Item: Comparable { // ... } ``` ## 泛型下标 ```swift extension Container { subscript(indices: Indices) -> [Item] where Indices.Iterator.Element == Int { var result: [Item] = [] for index in indices { result.append(self[index]) } return result } } ``` ## 泛型 Builder ```swift // Result Builder @resultBuilder struct StringBuilder { static func buildBlock(_ parts: String...) -> String { parts.joined() } static func buildIf(_ part: String?) -> String { part ?? "" } } func build(@StringBuilder _ strings: () -> String) -> String { strings() } let result = build { "Hello" " " "World" } ``` ## 不透明类型 some ```swift // some 修饰符 func makeProtocol() -> some Equatable { return 42 // 返回类型隐藏为 some Equatable } // 不透明类型保证具体类型一致 func makeIntStack() -> some Stack { var stack = IntStack() stack.push(1) return stack } ``` ## 泛型约束 | 约束类型 | 语法 | 说明 | |---------|------|------| | 类型约束 | `T: Comparable` | T 必须实现 Comparable | | 协议约束 | `T: SomeProtocol` | T 必须遵循协议 | | 类约束 | `T: UIView` | T 必须是 UIView 子类 | | 关联类型 | `T.Iterator` | 使用关联类型 | ## 泛型与 OOP | 模式 | 泛型实现 | 协议实现 | |------|---------|---------| | 通用容器 | `Stack` | `Container` 协议 | | 通用算法 | `sort` | `Comparable` | | 类型擦除 | `AnyCollection` | `Collection` | ## 来源 > The Swift Programming Language (Swift 6.3) > Generics Chapter > https://docs.swift.org/swift-book/documentation/the-swift-programming-language/generics/ FILE:references/localization.md # 国际化与本地化参考 > 来源：Apple Localization Documentation（2026-04-23） > https://developer.apple.com/documentation/localization ## 本地化基础 ### 支持语言 | 平台 | 语言代码 | 示例 | |------|---------|------| | iOS/macOS | zh-Hans | 简体中文 | | iOS/macOS | zh-Hant | 繁体中文 | | iOS/macOS | en | 英语 | | iOS/macOS | ja | 日语 | | iOS/macOS | ko | 韩语 | ### 本地化目录结构 ``` 项目/ ├── en.lproj/ # 英语 │ └── Localizable.strings ├── zh-Hans.lproj/ # 简体中文 │ └── Localizable.strings ├── ja.lproj/ # 日语 │ └── Localizable.strings └── Base.lproj/ # 默认语言 └── Localizable.strings ``` ## NSLocalizedString ### 基本用法 ```swift // 代码中 let title = NSLocalizedString("welcome_title", comment: "欢迎标题") let message = NSLocalizedString("welcome_message", comment: "欢迎消息") // 带参数 let greeting = String(format: NSLocalizedString("greeting_format", comment: ""), name, count) ``` ### String Catalog（Xcode 15+ 推荐） ```swift // 新方式：String Catalog (.xcstrings) struct Strings { static func welcome(name: String) -> String { String(localized: "Welcome, \(name)") } static func itemCount(_ count: Int) -> String { String(localized: "\(count) items", defaultValue: "\(count) 个项目") } } ``` ### .xcstrings 文件格式 ```json { "sourceLanguage": "en", "strings": { "welcome_title": { "localizations": { "zh-Hans": { "stringUnit": { "state": "translated", "value": "欢迎" } } } }, "greeting_format": { "localizations": { "zh-Hans": { "stringUnit": { "state": "translated", "value": "你好，%@！" } } } } } } ``` ## 格式化 ### 数字格式化 ```swift let formatter = NumberFormatter() formatter.numberStyle = .decimal formatter.maximumFractionDigits = 2 let price = formatter.string(from: 1234.567) // "1,234.57" ``` ### 货币格式化 ```swift let formatter = NumberFormatter() formatter.numberStyle = .currency formatter.currencyCode = "CNY" formatter.locale = Locale(identifier: "zh-Hans") let price = formatter.string(from: 99.9) // "¥99.90" ``` ### 日期格式化 ```swift let formatter = DateFormatter() formatter.dateStyle = .medium formatter.timeStyle = .short formatter.locale = Locale(identifier: "zh-Hans") let dateString = formatter.string(from: Date()) // "2024年4月23日 14:30" ``` ### 相对日期 ```swift let formatter = RelativeDateTimeFormatter() formatter.unitsStyle = .full formatter.locale = Locale(identifier: "zh-Hans") let relative = formatter.localizedString(for: Date().addingTimeInterval(-3600), relativeTo: Date()) // "1小时前" ``` ### 复数格式化 ```swift // Localizable.stringsdict /* %d items = { one = "%d 个项目"; other = "%d 个项目"; }; */ // 代码 let format = NSLocalizedString("%d items", comment: "") let result = String(format: format, count) ``` ## SwiftUI 本地化 ### Text 本地化 ```swift Text("Hello, World!") Text("items_count", comment: "项目数量") Text("\(count) items", comment: "") // 动态值 Text("greeting", value: name, format: .name(style: .firstName)) ``` ### 复数 ```swift Text( "\(count) items", table: "Plurals", comment: "" ) // Plurals.xcstrings { "items_count": { "localizations": { "zh-Hans": { "stringUnit": { "value": "\(count) 个项目" } } } } } ``` ## App Store 本地化 ### 可本地化内容 | 内容 | 说明 | |------|------| | App 名称 | App Store Connect | | 副标题 | App Store Connect | | 描述 | 每个语言版本 | | 关键词 | 每个语言版本 | | 更新日志 | 每个语言版本 | | 截图 | 按设备/语言 | ### 本地化截图尺寸 | 设备 | 尺寸 (pt) | 比例 | |------|----------|------| | iPhone 6.5" | 1284×2778 | 2.165 | | iPhone 6.7" | 1290×2796 | 2.165 | | iPad 12.9" | 2048×2732 | 1.333 | ## RTL 语言支持 ### 布局方向 ```swift // SwiftUI Text("Hello") .environment(\.layoutDirection, .rightToLeft) // UIKit label.semanticContentAttribute = .forceRightToLeft view.transform = CGAffineTransform(scaleX: -1, y: 1) ``` ### 检测 RTL ```swift func isRTL() -> Bool { let direction = UIApplication.shared.userInterfaceLayoutDirection return direction == .rightToLeft } ``` ## 测量单位 | 类型 | 中国 | 美国 | |------|------|------| | 距离 | 公里/米 | 英里/英尺 | | 温度 | 摄氏度 | 华氏度 | | 重量 | 公斤 | 磅 | | 体积 | 升 | 加仑 | ```swift let formatter = MeasurementFormatter() formatter.unitStyle = .medium formatter.unitOptions = .providedUnit let distance = Measurement(value: 10, unit: UnitLength.kilometers) formatter.string(from: distance) // "10 km" 或 "6.2 mi" ``` ## 字符长度注意 | 语言 | vs 英语 | 示例 | |------|--------|------| | 德语 | +20~30% | "Einstellungen" vs "Settings" | | 俄语 | +10~15% | "Настройки" vs "Settings" | | 中文 | -50% | "设置" vs "Settings" | | 日语 | -40% | "設定" vs "Settings" | ## App Icon 本地化 ### 本地化 Icon ``` AppIcon/ ├── AppIcon.appiconset/ │ ├── Contents.json │ ├── Icon-60@2x.png # 英文 │ ├── Icon-60@3x.png # 英文 │ ├── zh-Hans/ │ │ ├── Icon-60@2x.png # 中文 │ │ └── Icon-60@3x.png # 中文 │ └── ja/ │ ├── Icon-60@2x.png # 日语 │ └── Icon-60@3x.png # 日语 ``` ## 来源 > Apple Localization Documentation > https://developer.apple.com/documentation/localization FILE:references/protocols.md # Swift 协议参考 > 来源：The Swift Programming Language (6.3) - Protocols > https://docs.swift.org/swift-book/documentation/the-swift-programming-language/protocols/ > 抓取时间：2026-04-23 ## 协议基础 ```swift protocol ExampleProtocol { var simpleDescription: String { get } mutating func adjust() } ``` ### 遵循协议 ```swift // 结构体 struct SimpleStructure: ExampleProtocol { var simpleDescription: String = "A simple structure" mutating func adjust() { simpleDescription += " (adjusted)" } } // 类 class SimpleClass: ExampleProtocol { var simpleDescription: String = "A simple class" func adjust() { simpleDescription += " (adjusted)" } } ``` ## 属性要求 ```swift protocol FullyNamed { var fullName: String { get } // 必须可读 var displayName: String { get set } // 可读可写 } struct Person: FullyNamed { var fullName: String var displayName: String } ``` ## 方法要求 ```swift protocol RandomNumberGenerator { func random() -> Double } class LinearCongruentialGenerator: RandomNumberGenerator { var lastRandom = 42.0 func random() -> Double { lastRandom = (lastRandom * 3039177861 + 1) % 6075 return lastRandom / 6075 } } ``` ## 突变方法要求 ```swift protocol Togglable { mutating func toggle() } enum OnOffSwitch: Togglable { case off, on mutating func toggle() { switch self { case .off: self = .on case .on: self = .off } } } ``` ## 构造器要求 ```swift protocol SomeProtocol { init() init(name: String) } class SomeClass: SomeProtocol { var name: String required init() { self.name = "default" } required init(name: String) { self.name = name } } ``` ## 协议作为类型 ```swift protocol DiceGame { var dice: Dice { get } func play() } // 当作类型使用 var game: DiceGame = SnakesAndLadders() game.play() ``` ## 委托模式 ```swift protocol DiceGameDelegate { func gameDidStart(_ game: DiceGame) func game(_ game: DiceGame, didStartNewTurnWithDiceRoll diceRoll: Int) func gameDidEnd(_ game: DiceGame) } class Tracker: DiceGameDelegate { func gameDidStart(_ game: DiceGame) { } func game(_ game: DiceGame, didStartNewTurnWithDiceRoll: Int) { } func gameDidEnd(_ game: DiceGame) { } } ``` ## 协议扩展 ```swift extension Collection { func allEven() -> [Element] where Element: Numeric { return self.filter { ($0 as? Int ?? 0) % 2 == 0 } } } extension RandomNumberGenerator { func randomBool() -> Bool { return random() > 0.5 } } ``` ## 协议约束 ```swift func someFunction(thing: T) { } // where 子句 func allItemsMatch (_ someContainer: C1, _ anotherContainer: C2) -> Bool where C1.Element == C2.Element, C1.Element: Equatable { // ... } ``` ## 合成协议 ```swift protocol InEqual: Equatable, Comparable { } // 自动 Equatable + Comparable struct Point: InEqual { var x: Int, y: Int } ``` ## Class-Only 协议 ```swift protocol ClassOnlyProtocol: AnyObject { // 只有类可以遵循 } // 错误：结构体无法遵循 // struct S: ClassOnlyProtocol { } // ❌ ``` ## 协议继承 ```swift protocol PrettyTextRepresentable: TextRepresentable { var prettyDescription: String { get } } ``` ## Optional 协议要求（Objective-C） ```swift @objc protocol CounterDataSource { @objc optional func increment(for counter: Counter) -> Int @objc optional var fixedIncrement: Int { get } } ``` ## 来源 > The Swift Programming Language (Swift 6.3) > Protocols Chapter > https://docs.swift.org/swift-book/documentation/the-swift-programming-language/protocols/ FILE:references/standard-library.md # Swift 标准库参考 > 来源：The Swift Programming Language (6.3) - Language Guide 补充 > https://docs.swift.org/swift-book/documentation/the-swift-programming-language/ > 抓取时间：2026-04-23 ## 字符串 String ### 创建与访问 ```swift let greeting = "Hello, World!" greeting[greeting.startIndex] // "H" greeting[greeting.index(before: greeting.endIndex)] // "!" greeting[greeting.index(greeting.startIndex, offsetBy: 7)] // "W" // 安全访问 if let idx = greeting.firstIndex(of: ",") { let sub = greeting[.. yesterday // true now == now // true // 组件 let components = Calendar.current.dateComponents([.year, .month, .day], from: now) components.year // 2024 components.month // 4 components.day // 23 ``` ## URL ```swift var url = URL(string: "https://example.com/path?query=value")! url.scheme // "https" url.host // "example.com" url.path // "/path" url.query // "query=value" url.fragment // nil // 追加 var base = URL(string: "https://example.com/")! base.appendPathComponent("api") base.appendPathComponent("users") base.appendPathComponent("123") // "https://example.com/api/users/123" // 查询参数 var components = URLComponents(url: url, resolvingAgainstBaseURL: true)! components.queryItems // [URLQueryItem(name: "query", value: "value")] components.path // "/path" // 构建查询 var build = URLComponents() build.scheme = "https" build.host = "api.example.com" build.path = "/search" build.queryItems = [ URLQueryItem(name: "q", value: "swift"), URLQueryItem(name: "page", value: "1") ] build.url?.absoluteString // "https://api.example.com/search?q=swift&page=1" ``` ## FileManager ```swift import Foundation let fm = FileManager.default let docs = fm.urls(for: .documentDirectory, in: .userDomainMask)[0] // 路径操作 fm.currentDirectoryPath docs.path // 文件存在 fm.fileExists(atPath: "test.txt") fm.fileExists(atPath: docs.path) // 目录操作 fm.createDirectory(at: docs.appendingPathComponent("cache"), withIntermediateDirectories: true) fm.removeItem(at: docs.appendingPathComponent("cache")) // 文件操作 fm.copyItem(at: source, to: dest) fm.moveItem(at: source, to: dest) // 属性 let attrs = try fm.attributesOfItem(atPath: "test.txt") attrs[.size] // 文件大小 attrs[.creationDate] attrs[.modificationDate] // 遍历目录 let contents = try fm.contentsOfDirectory(at: docs, includingPropertiesForKeys: nil) for file in contents where file.pathExtension == "txt" { } ``` ## UserDefaults ```swift let defaults = UserDefaults.standard // 存储 defaults.set("Alice", forKey: "username") defaults.set(42, forKey: "age") defaults.set([1, 2, 3], forKey: "scores") defaults.set(true, forKey: "isOnboarded") // 读取 defaults.string(forKey: "username") // "Alice" defaults.integer(forKey: "age") // 42 defaults.array(forKey: "scores") // [1, 2, 3] defaults.bool(forKey: "isOnboarded") // true // 监听变化 NotificationCenter.default.addObserver( forName: UserDefaults.didChangeNotification, object: nil, queue: .main ) { _ in // 重新读取 } ``` ## JSON 编码解码 ```swift import Foundation struct User: Codable { let id: Int let name: String let email: String? } let user = User(id: 1, name: "Alice", email: "alice@example.com") // 编码 let encoder = JSONEncoder() encoder.outputFormatting = [.prettyPrinted, .sortedKeys] let data = try encoder.encode(user) let json = String(data: data, encoding: .utf8)! // 解码 let decoder = JSONDecoder() decoder.keyDecodingStrategy = .convertFromSnakeCase // snake_case let decoded = try decoder.decode(User.self, from: data) // 通用 Any 解码 let anyDecoder = JSONDecoder() let anyData = try anyDecoder.decode([String: Any].self, from: data) // 需 Codable 扩展 ``` ## 常用宏 | 宏 | 用途 | |----|------| | `@main` | 程序入口 | | `@State` | SwiftUI 状态 | | `@Binding` | 绑定 | | `@Published` | Observable 属性 | | `@ObservedObject` | 观察对象 | | `@EnvironmentObject` | 环境注入 | | `@propertyWrapper` | 自定义包装器 | | `@resultBuilder` | 结果构建器 | | `@dynamicMemberLookup` | 动态成员查找 | | `@dynamicCallable` | 动态调用 | ## Result ```swift enum NetworkError: Error { case badURL case noData case decodingFailed(Error) } func fetch() -> Result { guard let url = URL(string: "...") else { return .failure(.badURL) } guard let data = try? Data(contentsOf: url) else { return .failure(.noData) } return .success(data) } // 使用 let result = fetch() switch result { case .success(let data): print(data.count) case .failure(let error): print(error) } // map / flatMap let stringResult = result.map { String(data: $0, encoding: .utf8) } ``` ## 常用协议 | 协议 | 用途 | |------|------| | Codable | JSON 编解码 | | Equatable | 相等比较 | | Hashable | 可哈希/Set/Dict key | | Comparable | 排序 | | CustomStringConvertible | print 描述 | | Identifiable | ID 标识 | | Sequence | 迭代 | | Collection | 下标访问 | | LazySequenceProtocol | 惰性序列 | ### CustomStringConvertible ```swift struct Point: CustomStringConvertible { let x: Int, y: Int var description: String { "(\(x), \(y))" } } print(Point(x: 1, y: 2)) // "(1, 2)" ``` ### Identifiable ```swift struct User: Identifiable { let id: Int let name: String } // ForEach 无需 id 参数 ForEach(users) { user in Text(user.name) } ``` ## 常用扩展 ```swift // String 扩展 extension String { var isBlank: Bool { trimmingCharacters(in: .whitespaces).isEmpty } func toInt() -> Int? { Int(self) } } // Array 扩展 extension Array { func chunked(into size: Int) -> [[Element]] { stride(from: 0, to: count, by: size).map { Array(self[$0.. The Swift Programming Language (Swift 6.3) > https://docs.swift.org/swift-book/documentation/the-swift-programming-language/ FILE:references/swift-concurrency.md # Swift 6 Concurrency 权威参考 > 来源：The Swift Programming Language (6.3) - Concurrency Chapter > https://docs.swift.org/swift-book/documentation/the-swift-programming-language/concurrency/ > 抓取时间：2026-04-23 ## 核心概念 Swift 并发 = 异步代码 + 并行代码。 | 概念 | 说明 | |------|------| | 异步代码 | 可暂停/恢复，同时只执行一段 | | 并行代码 | 多段代码同时执行（如4核CPU同时运行4段） | | 数据竞争 (data race) | 多段代码同时访问同一可变状态 | Swift 在编译期检测并阻止大多数数据竞争。 ## 异步函数 async/await ### 定义异步函数 ```swift // 基本异步函数 func listPhotos(inGallery name: String) async -> [String] { let result = await fetchPhotos(name: name) return result } // 异步 + throwing func fetchPhoto(named name: String) async throws -> Photo { guard let photo = try await download(name: name) else { throw PhotoError.notFound } return photo } ``` ### 调用异步函数 ```swift // 普通调用 let photos = await listPhotos(inGallery: "Vacation") // 异步 + throwing let photo = try await fetchPhoto(named: "sunset") // async-let 并行调用 async let first = fetchPhoto(named: photos[0]) async let second = fetchPhoto(named: photos[1]) async let third = fetchPhoto(named: photos[2]) let all = await [first, second, third] ``` ### async-let vs await | 方式 | 适用场景 | |------|---------| | `await` | 后续代码依赖结果 | | `async let` | 结果只需在后面某处使用，可并行 | ## Task 和 TaskGroup ### Task 基础 ```swift // 创建任务 let handle = Task { return await fetchData() } // 等待结果 let data = await handle.value // 取消 handle.cancel() ``` ### TaskGroup（动态数量任务） ```swift // 下载任意数量照片 let photos = await withTaskGroup(of: Data.self) { group in let names = await listPhotos() for name in names { group.addTask { return await downloadPhoto(named: name) } } var results: [Data] = [] for await photo in group { results.append(photo) } return results } // Throwing 版本 let photos = await withThrowingTaskGroup(of: Data.self) { group in // 同上，但 addTask 可 throw } ``` ### Task 取消 ```swift // 方式1：checkCancellation（自动抛出） func process() async throws { try Task.checkCancellation() // 继续处理 } // 方式2：isCancelled（自定义清理） func process() async { for item in items { guard !Task.isCancelled else { cleanup() return } await processItem(item) } } // 方式3：withTaskCancellationHandler let task = await Task.withTaskCancellationHandler { await longRunningWork() } onCancel: { cleanupResources() } task.cancel() // addTaskUnlessCancelled let added = group.addTaskUnlessCancelled { await download(name: name) } guard added else { break } ``` ## 结构化并发 vs 非结构化并发 | 类型 | 说明 | |------|------| | 结构化 | TaskGroup/async-let，父子关系，自动取消/传播 | | 非结构化 | `Task {}`，无父任务，需手动管理 | ```swift // 结构化（TaskGroup） await withTaskGroup { group in group.addTask { await work() } } // 非结构化 let handle = Task { await work() } await handle.value // Detached（完全独立） let detached = Task.detached { await work() } await detached.value ``` ## MainActor ### 概念 MainActor = 保护 UI 数据的 actor，确保所有 UI 更新串行执行。 | 类比 | MainActor | Main Thread | |------|-----------|-------------| | 关系 | Swift 层面抽象 | 底层实现 | | 保证 | 串行访问 UI 数据 | 实际执行代码 | ### @MainActor 用法 ```swift // 函数级别 @MainActor func updateUI(with data: Data) { label.text = "\(data.count) bytes" } // 类型级别（struct/class/enum） @MainActor class ViewModel: ObservableObject { @Published var items: [Item] = [] func load() async { let fetched = await api.fetch() self.items = fetched // 安全，在 MainActor } } // 属性级别 struct Gallery { @MainActor var photoNames: [String] @MainActor func drawUI() { /* UI代码 */ } func cache() { /* 后台代码 */ } } // 闭包 Task { @MainActor in show(photo) } ``` ### 调用 @MainActor 函数 ```swift // 从 MainActor 调用：同步 @MainActor func show(_ photo: Photo) { } struct MyView: View { @StateObject var vm = ViewModel() var body: some View { Button("Show") { show(photo) // 同步调用 } } } // 从非 MainActor 调用：需要 await func downloadAndShow(name: String) async { let photo = await download(name: name) await show(photo) // 需要 await } ``` ## 自定义 Actor ### 定义和用法 ```swift actor TemperatureLogger { let label: String var measurements: [Int] private(set) var max: Int init(label: String, measurement: Int) { self.label = label self.measurements = [measurement] self.max = measurement } func update(with measurement: Int) { measurements.append(measurement) if measurement > max { max = measurement } } } // 访问 actor let logger = TemperatureLogger(label: "Indoor", measurement: 22) print(await logger.max) // 需要 await // actor 内部访问：不需要 await extension TemperatureLogger { func convertFahrenheitToCelsius() { for i in measurements.indices { measurements[i] = (measurements[i] - 32) * 5 / 9 } } } ``` ### GlobalActor ```swift @globalActor struct DatabaseActor { static let shared = DatabaseActor() } @DatabaseActor func saveToDatabase(_ data: Data) async { // 在 DatabaseActor 上执行 } ``` ## Sendable 协议 ### Sendable 条件 | 类型 | Sendable? | 说明 | |------|-----------|------| | 值类型（只含 Sendable 属性） | ✅ 自动 | struct/enum | | 无可变状态的不可变类型 | ✅ 自动 | let 属性 | | @MainActor 类 | ✅ | UI 框架类 | | 序列化访问的类 | ✅ | 自行保证线程安全 | | 普通类 | ❌ | 含可变状态 | ### 显式标记 ```swift // 显式实现 struct Reading: Sendable { var value: Int } // 显式不可 Sendable struct UnsafeWrapper { let rawPointer: UnsafePointer } @available(*, unavailable) extension UnsafeWrapper: Sendable {} ``` ### 闭包的 Sendable ```swift // @Sendable 闭包 let task = Task { @Sendable in await work() // 自动 Sendable } // actor init 中的 sendable 要求 actor MyActor { init(sendable closure: @Sendable @escaping () async -> Void) { Task { await closure() } } } ``` ## 异步序列 AsyncSequence ```swift // 基本用法 let handle = FileHandle.standardInput for try await line in handle.bytes.lines { print(line) } // 自定义 AsyncSequence struct Counter: AsyncSequence { typealias Element = Int struct AsyncIterator: AsyncIteratorProtocol { var count = 0 mutating func next() async -> Int? { guard count < 5 else { return nil } count += 1 return count } } func makeAsyncIterator() -> AsyncIterator { AsyncIterator() } } for await i in Counter() { print(i) // 1, 2, 3, 4, 5 } ``` ## Swift 6 数据竞争安全 ### 编译期检测 Swift 6 默认开启 Complete Concurrency Checking： ```swift // Swift 6 模式下，以下代码编译错误： class UnsafeCounter { var count = 0 func increment() { count += 1 } } // 正确方式：使用 actor actor SafeCounter { private var count = 0 func increment() { count += 1 } var value: Int { count } } ``` ### 迁移策略（Top-Down） ``` 1. 入口点（@main、AppDelegate）标记为 async 2. 逐层向下转换调用方 3. 不能从下往上迁移 ``` ## 性能考虑 | 操作 | 成本 | |------|------| | Task 创建 | 低 | | await 暂停 | 极低 | | actor 切换 | 极低 | | Thread 创建 | 高 | ## 来源 > The Swift Programming Language (Swift 6.3) > Concurrency Chapter > https://docs.swift.org/swift-book/documentation/the-swift-programming-language/concurrency/ FILE:references/swiftui-advanced.md # SwiftUI 进阶参考 > 来源：Apple SwiftUI Documentation（2026-04-23） > https://developer.apple.com/documentation/swiftui ## 环境值 @Environment 访问系统级上下文。 ```swift struct DetailView: View { @Environment(\.dismiss) var dismiss // 关闭视图 @Environment(\.horizontalSizeClass) var hSize // 水平尺寸类 @Environment(\.colorScheme) var colorScheme // 深色/浅色模式 @Environment(\.managedObjectContext) var context // Core Data @Environment(\.scenePhase) var scenePhase // App 状态 var body: some View { Button("关闭") { dismiss() } } } ``` ### 常用 Environment Key | Key | 类型 | 说明 | |-----|------|------| | `.dismiss` | DismissAction | 关闭 Sheet/Navigation | | `.colorScheme` | ColorScheme | light/dark | | `.horizontalSizeClass` | UserInterfaceSizeClass? | regular/compact | | `.managedObjectContext` | NSManagedObjectContext | Core Data | | `.scenePhase` | ScenePhase | active/inactive/background | --- ## @AppStorage 和 @SceneStorage ```swift struct SettingsView: View { @AppStorage("username") var username = "" @AppStorage("notificationsEnabled") var notificationsEnabled = true @AppStorage("selectedColor") var selectedColor = "blue" var body: some View { Form { TextField("用户名", text: $username) Toggle("启用通知", isOn: $notificationsEnabled) } } } struct FormView: View { @SceneStorage("draftText") private var draftText = "" @SceneStorage("selectedTab") private var selectedTab = 0 var body: some View { // 数据在同一个 Scene 内持久化 // 切换 App 会恢复状态 } } ``` ### 区别 | 修饰器 | 持久化 | 作用域 | |--------|--------|--------| | @AppStorage | UserDefaults | 全局 | | @SceneStorage | UserDefaults | 同一 Scene | | @State | 内存 | 视图生命周期 | --- ## @FocusState 焦点管理 ```swift struct LoginView: View { @State private var email = "" @State private var password = "" @FocusState private var focusedField: Field? enum Field { case email, password } var body: some View { VStack { TextField("Email", text: $email) .focused($focusedField, equals: .email) .textContentType(.emailAddress) .submitLabel(.next) .onSubmit { focusedField = .password } SecureField("Password", text: $password) .focused($focusedField, equals: .password) .textContentType(.password) .submitLabel(.go) .onSubmit { login() } Button("登录") { login() } .focused($focusedField, equals: nil) // 失去焦点 } .toolbar { ToolbarItemGroup(placement: .keyboard) { Button("完成") { focusedField = nil } } } } } ``` --- ## 高级动画 ### animation(_:value:) 绑定动画 ```swift struct AnimatedCard: View { @State private var isExpanded = false var body: some View { VStack { Image(systemName: isExpanded ? "star.fill" : "star") Text(isExpanded ? "已收藏" : "收藏") } .padding() .background(isExpanded ? Color.yellow : Color.gray.opacity(0.2)) .cornerRadius(12) .animation(.easeInOut(duration: 0.3), value: isExpanded) // isExpanded 变化时自动触发动画 } } ``` ### 过渡 Transitions ```swift struct TransitionView: View { @State private var showDetail = false var body: some View { ZStack { if showDetail { DetailView() .transition(.asymmetric( insertion: .scale(scale: 0.8).combined(with: .opacity), removal: .move(edge: .bottom).combined(with: .opacity) )) } } .animation(.spring(response: 0.4, dampingFraction: 0.7), value: showDetail) } } ``` ### 手势动画 ```swift struct DraggableView: View { @State private var offset = CGSize.zero @State private var scale: CGFloat = 1.0 var body: some View { Circle() .fill(Color.blue) .frame(width: 100, height: 100) .offset(offset) .scaleEffect(scale) .gesture( DragGesture() .onChanged { value in offset = value.translation scale = 1.1 // 拖动时放大 } .onEnded { _ in offset = .zero scale = 1.0 } ) } } ``` --- ## Sheet 和 FullScreenCover ```swift struct SheetExamples: View { @State private var showSheet = false @State private var selectedItem: Item? @State private var itemToEdit: Item? var body: some View { // 基本用法 Button("显示 Sheet") { showSheet = true } .sheet(isPresented: $showSheet) { BasicSheet() } // 基于 item 的 Sheet Button("编辑项目") { selectedItem = items.first } .sheet(item: $selectedItem) { item in EditView(item: item) } // 全屏覆盖 Button("全屏") { showSheet = true } .fullScreenCover(isPresented: $showSheet) { FullScreenView() } } } // Dismisser struct DismissibleSheet: View { @Environment(\.dismiss) var dismiss var body: some View { VStack { Text("可滑出关闭") Button("手动关闭") { dismiss() } } .interactiveDismissDisabled() // 禁用滑出关闭 .presentationDetents([.medium, .large]) .presentationDragIndicator(.visible) } } ``` ### Presentation 修饰器 ```swift .sheet(isPresented: $show) { } // Sheet 弹出 .fullScreenCover(isPresented: $show) { } // 全屏覆盖 .confirmationDialog("标题", isPresented: $show) { } // 确认对话框 .confirmationDialog("选择", isPresented: $show, titleVisibility: .visible) { Button("选项1") { } Button("选项2", role: .destructive) { } Button("取消", role: .cancel) { } } message: { Text("选择一项操作") } ``` --- ## Navigation 进阶 ### NavigationStack 深度导航 ```swift struct AppNavigation: View { var body: some View { NavigationStack { List(items) { item in NavigationLink(value: item) { ItemRow(item: item) } } .navigationDestination(for: Item.self) { item in DetailView(item: item) } .navigationDestination(for: String.self) { path in // 字符串路径 RouteView(path: path) } .navigationDestination(for: Route.self) { route in // 枚举路由 RouteView(route: route) } } .navigationDestination(for: Item.self, destination: { item in DetailView(item: item) }) } } // Programmatic Navigation struct ProgrammaticNav: View { @State private var path = NavigationPath() var body: some View { NavigationStack(path: $path) { List { ForEach(items) { item in Button(item.name) { path.append(item) } } } .navigationDestination(for: Item.self) { item in DetailView(item: item) } .toolbar { ToolbarItem(placement: .navigationBarTrailing) { Button("返回") { path.removeLast() } Button("回首页") { path.removeLast(path.count) // 回到根 } } } } } } ``` ### 深度链接 Deep Linking ```swift struct DeepLinkView: View { @Environment(\.navigationDestinationKind) var navKind var body: some View { if navKind == .push { Text("通过导航链进入") } else if navKind == .sheet { Text("通过 Sheet 进入") } } } ``` --- ## 列表进阶 ### 展开/折叠 ```swift struct ExpandableList: View { @State private var expandedSections: Set = [] var body: some View { List { ForEach(sections) { section in Section { if expandedSections.contains(section.id) { ForEach(section.items) { item in ItemRow(item: item) } } } header: { Button { withAnimation { expandedSections.toggle(section.id) } } label: { HStack { Text(section.title) Spacer() Image(systemName: expandedSections.contains(section.id) ? "chevron.up" : "chevron.down") } } } } } } } ``` ### Swipe Actions ```swift struct SwipeList: View { @State private var items = ["A", "B", "C"] var body: some View { List { ForEach(items, id: \.self) { item in Text(item) .swipeActions(edge: .trailing) { Button(role: .destructive) { items.removeAll { $0 == item } } label: { Label("删除", systemImage: "trash") } Button { // 收藏 } label: { Label("收藏", systemImage: "heart") } .tint(.orange) } .swipeActions(edge: .leading) { Button { // 分享 } label: { Label("分享", systemImage: "square.and.arrow.up") } .tint(.blue) } } } } } ``` FILE:references/swiftui-animation.md # SwiftUI 动画与过渡 > 来源：Apple Developer Documentation — SwiftUI > URL: https://developer.apple.com/documentation/swiftui/view-transitions > 整理时间：2026-04-23 > 版本：iOS 17+ ## 动画基础 ### 动画修饰符 SwiftUI 提供三种主要动画方式： ```swift // 隐式动画：任何状态变化都自动应用 withAnimation(.easeInOut(duration: 0.3)) { isExpanded.toggle() } // 显式动画：指定具体属性变化 withAnimation(.spring(response: 0.3, dampingFraction: 0.7)) { scale += 0.1 } // 绑定动画：直接绑定到 Animation @State private var amount: Double = 0 Slider(value: $amount.animation(.easeInOut)) ``` ### 常用动画曲线 | 曲线 | 特点 | 适用场景 | |------|------|---------| | `.default` | easeInOut | 通用 | | `.easeIn` | 缓入 | 进入动画 | | `.easeOut` | 缓出 | 退出动画 | | `.easeInOut` | 缓入缓出 | 标准过渡 | | `.linear` | 匀速 | 进度条 | | `.spring()` | 弹性 | 弹跳效果 | | `.interactiveSpring()` | 交互弹性 | 拖拽跟随 | | `.snappy()` | 快速响应 | 轻快切换 | ### 动画参数 | 参数 | 说明 | 典型值 | |------|------|-------| | `duration` | 动画时长（秒） | 0.25 - 0.5 | | `response` | 弹簧响应 | 0.3 - 0.5 | | `dampingFraction` | 阻尼系数 | 0.5 - 0.8 | | `blendDuration` | 混合时长 | 0.0 - 0.3 | --- ## 视图过渡（Transitions） ### transition 修饰符 ```swift // 单边滑入 Rectangle() .transition(.move(edge: .trailing)) // 组合过渡 Rectangle() .transition(.asymmetric( insertion: .scale.combined(with: .opacity), removal: .slide )) // 渐变过渡 Rectangle() .transition(.opacity) ``` ### 常用过渡效果 | 过渡 | 效果 | |------|------| | `.opacity` | 透明度 0→1 | | `.scale` | 缩放 0→1 | | `.slide` | 滑入滑出 | | `.move(edge:)` | 指定边滑入 | | `.combined(with:)` | 组合多个 | | `.asymmetric(insertion:removal:)` | 不同进出 | | `.push(from:)` | 推入方向 | | `.offset(x:y:)` | 平移 | --- ## 显式动画 withAnimation ### 状态驱动动画 ```swift struct ContentView: View { @State private var isExpanded = false var body: some View { VStack { Button("Toggle") { withAnimation(.spring(response: 0.3, dampingFraction: 0.7)) { isExpanded.toggle() } } if isExpanded { DetailView() .transition(.scale.combined(with: .opacity)) } } } } ``` ### 动画优先级 | 优先级 | 说明 | |--------|------| | Transaction | 最高，覆盖 withAnimation | | Implicit | 隐式动画（animation 修饰符）| | Environment | 环境默认动画 | --- ## 动画Modifiers（动画专用修饰符） ### animation 修饰符 ```swift // 应用到所有子视图 Text("Hello") .animation(.easeInOut, value: isActive) // 旋转动画 Image(systemName: "arrow.right") .rotationEffect(.degrees(isRotated ? 90 : 0)) .animation(.easeInOut, value: isRotated) // 位置动画 circle .position(x: x, y: y) .animation(.spring(response: 0.3), value: x) ``` ### 关键帧动画（Keyframes） ```swift Text("Bounce") .keyframes( in: 0...1, data: \.scale, tracking: 0.1 ) { value in switch value { case 0: return 1.0 case 0.25: return 1.2 case 0.5: return 0.9 case 0.75: return 1.05 case 1: return 1.0 } } ``` --- ## 匹配几何过渡（Matched Geometry） ### 跨视图的连续过渡 ```swift @Namespace private var namespace var body: some View { if showDetail { DetailView() .matchedGeometryEffect(in: namespace, properties: .frame) .transition(.opacity) } else { GridItemView() .matchedGeometryEffect(in: namespace, properties: .frame) .transition(.opacity) } } ``` ### matchedGeometryEffect 属性 | 属性 | 说明 | |------|------| | `.frame` | 位置和大小 | | `.position` | 仅位置 | | `.size` | 仅大小 | | `.opacity` | 透明度 | --- ## 手势与动画结合 ### 拖拽动画 ```swift struct DraggableView: View { @State private var offset = CGSize.zero var body: some View { Circle() .fill(.blue) .frame(width: 100, height: 100) .offset(offset) .gesture( DragGesture() .onChanged { value in offset = value.translation } .onEnded { _ in withAnimation(.spring()) { offset = .zero } } ) } } ``` ### 弹性效果 ```swift // 弹簧动画参数 struct SpringPreset { static let snappy = Animation.spring(response: 0.3, dampingFraction: 0.7) static let bouncy = Animation.spring(response: 0.5, dampingFraction: 0.5) static let smooth = Animation.spring(response: 0.5, dampingFraction: 0.8) } ``` --- ## 动画控制 ### 暂停 / 恢复 ```swift @State private var isAnimating = false // 通过绑定控制 ProgressView() .animation(isAnimating ? .easeInOut : nil, value: isAnimating) ``` ### 动画状态机 | 状态 | 动画 | |------|------| | `loading` | `.easeInOut` 循环 | | `success` | `.spring` 弹跳 | | `error` | `.shake` 左右抖动 | --- ## 性能注意事项 1. **避免过度动画**：每个动画都消耗 GPU，复杂场景限制在 3 个以内 2. **使用 `drawingGroup()`**：将视图合成位图再渲染，提升性能 3. **优先使用 `opacity`**：比 `scale` / `offset` 性能更好 4. **避免在动画中计算**：提前计算，不要在每帧中计算 --- ## 来源 > Apple Developer Documentation — SwiftUI View Transitions > https://developer.apple.com/documentation/swiftui/view-transitions > Apple Developer Documentation — Animation > https://developer.apple.com/documentation/swiftui/animation FILE:references/swiftui-basics.md # SwiftUI 基础参考 > 来源：Apple SwiftUI Documentation（2026-04-23） > https://developer.apple.com/documentation/swiftui ## 视图基础 ### 最简单的 App ```swift @main struct MyApp: App { var body: some Scene { WindowGroup { ContentView() } } } ``` ### View Protocol ```swift struct MyView: View { var body: some View { // 返回单个 View Text("Hello") } } ``` ### 常用视图 | 视图 | 用途 | |------|------| | Text | 文本 | | Image | 图片 | | VStack | 垂直布局 | | HStack | 水平布局 | | ZStack | 层叠布局 | | Spacer | 空白填充 | ### 修饰器 ```swift Text("Hello") .font(.largeTitle) .foregroundColor(.blue) .padding() .background(Color.yellow) .cornerRadius(10) ``` ## 状态管理 ### @State ```swift struct Counter: View { @State private var count = 0 var body: some View { Button("Count: \(count)") { count += 1 } } } ``` ### @Binding ```swift struct ParentView: View { @State private var value = true var body: some View { ChildView(isOn: $value) } } struct ChildView: View { @Binding var isOn: Bool var body: some View { Toggle("", isOn: $isOn) } } ``` ### @StateObject ```swift class ViewModel: ObservableObject { @Published var count = 0 } struct MyView: View { @StateObject private var vm = ViewModel() var body: some View { Text("\(vm.count)") } } ``` ### @EnvironmentObject ```swift // App 层级注入 ContentView() .environmentObject(AuthService()) // 视图中使用 @EnvironmentObject var auth: AuthService ``` ## 列表 ### ForEach ```swift List { ForEach(items) { item in ItemRow(item: item) } } ``` ### 动态列表 ```swift List(items, id: \.id) { item in Text(item.name) } ``` ### 分组 ```swift List { Section("Header 1") { Text("Item 1") Text("Item 2") } Section("Header 2") { Text("Item 3") } } ``` ## 导航 ### NavigationStack ```swift NavigationStack { List(items) { item in NavigationLink(item.name, value: item) } .navigationDestination(for: Item.self) { item in DetailView(item: item) } } ``` ### Sheet ```swift struct ContentView: View { @State private var showingSheet = false Button("Show Sheet") { showingSheet = true } .sheet(isPresented: $showingSheet) { SheetView() } } ``` ## 表单 ### TextField ```swift @State private var name = "" @State private var email = "" Form { TextField("Name", text: $name) TextField("Email", text: $email) .keyboardType(.emailAddress) .textContentType(.emailAddress) } ``` ### Picker ```swift @State private var selectedColor = 0 Picker("Color", selection: $selectedColor) { Text("Red").tag(0) Text("Blue").tag(1) Text("Green").tag(2) } ``` ## 动画 ### 隐式动画 ```swift withAnimation(.easeInOut(duration: 0.3)) { isExpanded.toggle() } ``` ### 显式动画 ```swift Button("Animate") { withSpring { offset = CGSize(width: 100, height: 0) } } ``` ### 过渡 ```swift Text("Hello") .transition(.opacity.combined(with: .scale)) ``` FILE:references/uikit-advanced.md # UIKit 进阶参考 > 来源：Apple UIKit Documentation（2026-04-23） > https://developer.apple.com/documentation/uikit ## UICollectionView ### 基础用法 ```swift class ViewController: UIViewController { private var collectionView: UICollectionView! override func viewDidLoad() { super.viewDidLoad() setupCollectionView() } private func setupCollectionView() { let layout = UICollectionViewFlowLayout() layout.itemSize = CGSize(width: 100, height: 100) layout.minimumInteritemSpacing = 10 layout.minimumLineSpacing = 10 layout.sectionInset = UIEdgeInsets(top: 10, left: 10, bottom: 10, right: 10) collectionView = UICollectionView( frame: view.bounds, collectionViewLayout: layout ) collectionView.backgroundColor = .systemBackground collectionView.delegate = self collectionView.dataSource = self collectionView.register(Cell.self, forCellWithReuseIdentifier: "Cell") collectionView.translatesAutoresizingMaskIntoConstraints = false view.addSubview(collectionView) NSLayoutConstraint.activate([ collectionView.topAnchor.constraint(equalTo: view.topAnchor), collectionView.leadingAnchor.constraint(equalTo: view.leadingAnchor), collectionView.trailingAnchor.constraint(equalTo: view.trailingAnchor), collectionView.bottomAnchor.constraint(equalTo: view.bottomAnchor) ]) } } extension ViewController: UICollectionViewDataSource { func collectionView(_ collectionView: UICollectionView, numberOfItemsInSection section: Int) -> Int { return items.count } func collectionView(_ collectionView: UICollectionView, cellForItemAt indexPath: IndexPath) -> UICollectionViewCell { let cell = collectionView.dequeueReusableCell( withReuseIdentifier: "Cell", for: indexPath ) as! Cell cell.configure(with: items[indexPath.item]) return cell } } extension ViewController: UICollectionViewDelegate { func collectionView(_ collectionView: UICollectionView, didSelectItemAt indexPath: IndexPath) { // 处理选择 } } ``` ### Compositional Layout（现代用法） ```swift private func createLayout() -> UICollectionViewCompositionalLayout { // 3 列网格布局 let itemSize = NSCollectionLayoutSize( widthDimension: .fractionalWidth(1/3), heightDimension: .fractionalHeight(1.0) ) let item = NSCollectionLayoutItem(layoutSize: itemSize) item.contentInsets = NSDirectionalEdgeInsets(top: 8, leading: 8, bottom: 8, trailing: 8) let groupSize = NSCollectionLayoutSize( widthDimension: .fractionalWidth(1.0), heightDimension: .fractionalWidth(1/3) ) let group = NSCollectionLayoutGroup.horizontal(layoutSize: groupSize, subitems: [item]) let section = NSCollectionLayoutSection(group: group) section.contentInsets = NSDirectionalEdgeInsets(top: 16, leading: 8, bottom: 16, trailing: 8) return UICollectionViewCompositionalLayout(section: section) } ``` --- ## SnapKit 进阶 ```swift import SnapKit class ViewController: UIViewController { private let headerView = UIView() private let tableView = UITableView() private let footerView = UIView() override func viewDidLoad() { super.viewDidLoad() setupViews() setupConstraints() } private func setupViews() { view.backgroundColor = .systemBackground headerView.backgroundColor = .systemBlue tableView.delegate = self tableView.dataSource = self footerView.backgroundColor = .systemGray5 view.addSubview(headerView) view.addSubview(tableView) view.addSubview(footerView) } private func setupConstraints() { headerView.snp.makeConstraints { make in make.top.equalTo(view.safeAreaLayoutGuide) make.leading.trailing.equalToSuperview() make.height.equalTo(100) } tableView.snp.makeConstraints { make in make.top.equalTo(headerView.snp.bottom).offset(16) make.leading.trailing.equalToSuperview().inset(16) // 底部在 footer 之上 make.bottom.equalTo(footerView.snp.top).offset(-16) } footerView.snp.makeConstraints { make in make.leading.trailing.equalToSuperview() make.bottom.equalTo(view.safeAreaLayoutGuide) make.height.equalTo(60) } // 更新约束 headerView.snp.updateConstraints { make in make.height.equalTo(isExpanded ? 200 : 100) } // 重新布局动画 UIView.animate(withDuration: 0.3) { self.view.layoutIfNeeded() } } } ``` ### 复杂布局示例 ```swift private func setupCardConstraints() { cardView.snp.makeConstraints { make in make.center.equalToSuperview() make.width.equalToSuperview().multipliedBy(0.8) make.height.lessThanOrEqualTo(400) } imageView.snp.makeConstraints { make in make.top.leading.trailing.equalToSuperview() make.height.equalTo(cardView.snp.width).multipliedBy(0.6) } titleLabel.snp.makeConstraints { make in make.top.equalTo(imageView.snp.bottom).offset(16) make.leading.trailing.equalToSuperview().inset(16) } descriptionLabel.snp.makeConstraints { make in make.top.equalTo(titleLabel.snp.bottom).offset(8) make.leading.trailing.equalToSuperview().inset(16) make.bottom.equalToSuperview().offset(-16) } } ``` --- ## UIStackView ```swift // 水平栈 let hStack = UIStackView() hStack.axis = .horizontal hStack.spacing = 8 hStack.alignment = .center hStack.distribution = .fillEqually // 垂直栈 let vStack = UIStackView() vStack.axis = .vertical vStack.spacing = 16 vStack.alignment = .fill vStack.distribution = .fill // 添加视图 hStack.addArrangedSubview(avatarView) hStack.addArrangedSubview(nameLabel) hStack.addArrangedSubview(arrowImage) // 设置优先级 nameLabel.setContentHuggingPriority(.defaultLow, for: .horizontal) arrowImage.setContentHuggingPriority(.required, for: .horizontal) ``` --- ## UIScrollView ```swift let scrollView = UIScrollView() scrollView.translatesAutoresizingMaskIntoConstraints = false scrollView.alwaysBounceVertical = true // 弹性滚动 scrollView.showsVerticalScrollIndicator = true let contentView = UIView() contentView.translatesAutoresizingMaskIntoConstraints = false scrollView.addSubview(contentView) view.addSubview(scrollView) NSLayoutConstraint.activate([ scrollView.topAnchor.constraint(equalTo: view.topAnchor), scrollView.leadingAnchor.constraint(equalTo: view.leadingAnchor), scrollView.trailingAnchor.constraint(equalTo: view.trailingAnchor), scrollView.bottomAnchor.constraint(equalTo: view.bottomAnchor), contentView.topAnchor.constraint(equalTo: scrollView.topAnchor), contentView.leadingAnchor.constraint(equalTo: scrollView.leadingAnchor), contentView.trailingAnchor.constraint(equalTo: scrollView.trailingAnchor), contentView.bottomAnchor.constraint(equalTo: scrollView.bottomAnchor), // 关键：内容宽度等于 scrollView contentView.widthAnchor.constraint(equalTo: scrollView.widthAnchor) ]) // 内容高度动态 descriptionLabel.numberOfLines = 0 descriptionLabel.snp.makeConstraints { make in make.top.equalToSuperview().offset(16) make.leading.trailing.equalToSuperview().inset(16) make.bottom.equalToSuperview().offset(-16) } ``` --- ## 手势识别 ### 常用手势 ```swift // 点击 let tap = UITapGestureRecognizer(target: self, action: #selector(handleTap)) view.addGestureRecognizer(tap) // 拖拽 let pan = UIPanGestureRecognizer(target: self, action: #selector(handlePan(_:))) view.addGestureRecognizer(pan) @objc func handlePan(_ gesture: UIPanGestureRecognizer) { let translation = gesture.translation(in: view) let velocity = gesture.velocity(in: view) switch gesture.state { case .changed: view.transform = CGAffineTransform(translationX: translation.x, y: translation.y) case .ended: // 弹回去动画 UIView.animate(withDuration: 0.3) { view.transform = .identity } default: break } } // 缩放 let pinch = UIPinchGestureRecognizer(target: self, action: #selector(handlePinch(_:))) view.addGestureRecognizer(pinch) @objc func handlePinch(_ gesture: UIPinchGestureRecognizer) { view.transform = view.transform.scaledBy(x: gesture.scale, y: gesture.scale) gesture.scale = 1.0 } // 旋转 let rotation = UIRotationGestureRecognizer(target: self, action: #selector(handleRotation(_:))) view.addGestureRecognizer(rotation) // 长按 let longPress = UILongPressGestureRecognizer(target: self, action: #selector(handleLongPress(_:))) longPress.minimumPressDuration = 0.5 view.addGestureRecognizer(longPress) // 边缘滑动（iOS 侧滑返回） let edgePan = UIScreenEdgePanGestureRecognizer(target: self, action: #selector(handleEdgePan)) edgePan.edges = .left view.addGestureRecognizer(edgePan) ``` ### 同时识别多个手势 ```swift // 允许多个手势同时识别 tap.require(toFail: longPress) // 点击优先于长按 ``` --- ## UITabBarController ```swift class MainTabBarController: UITabBarController { override func viewDidLoad() { super.viewDidLoad() setupTabs() setupAppearance() } private func setupTabs() { let homeVC = UINavigationController(rootViewController: HomeViewController()) homeVC.tabBarItem = UITabBarItem( title: "首页", image: UIImage(systemName: "house"), selectedImage: UIImage(systemName: "house.fill") ) let searchVC = UINavigationController(rootViewController: SearchViewController()) searchVC.tabBarItem = UITabBarItem( title: "搜索", image: UIImage(systemName: "magnifyingglass"), selectedImage: UIImage(systemName: "magnifyingglass") ) let profileVC = UINavigationController(rootViewController: ProfileViewController()) profileVC.tabBarItem = UITabBarItem( title: "我的", image: UIImage(systemName: "person"), selectedImage: UIImage(systemName: "person.fill") ) viewControllers = [homeVC, searchVC, profileVC] } private func setupAppearance() { let appearance = UITabBarAppearance() appearance.configureWithOpaqueBackground() appearance.backgroundColor = .systemBackground tabBar.standardAppearance = appearance if #available(iOS 15.0, *) { tabBar.scrollEdgeAppearance = appearance } tabBar.tintColor = .systemBlue } } ``` --- ## 键盘处理 ```swift class FormViewController: UIViewController { @IBOutlet weak var scrollView: UIScrollView! @IBOutlet weak var emailField: UITextField! @IBOutlet weak var passwordField: UITextField! override func viewDidLoad() { super.viewDidLoad() setupKeyboardObservers() setupTapGesture() } private func setupKeyboardObservers() { NotificationCenter.default.addObserver( self, selector: #selector(keyboardWillShow), name: UIResponder.keyboardWillShowNotification, object: nil ) NotificationCenter.default.addObserver( self, selector: #selector(keyboardWillHide), name: UIResponder.keyboardWillHideNotification, object: nil ) } private func setupTapGesture() { let tap = UITapGestureRecognizer(target: self, action: #selector(dismissKeyboard)) tap.cancelsTouchesInView = false view.addGestureRecognizer(tap) } @objc func keyboardWillShow(_ notification: Notification) { guard let keyboardFrame = notification.userInfo?[ UIResponder.keyboardFrameEndUserInfoKey ] as? CGRect else { return } let contentInsets = UIEdgeInsets( top: 0, left: 0, bottom: keyboardFrame.height, right: 0 ) scrollView.contentInset = contentInsets scrollView.scrollIndicatorInsets = contentInsets } @objc func keyboardWillHide(_ notification: Notification) { scrollView.contentInset = .zero scrollView.scrollIndicatorInsets = .zero } @objc func dismissKeyboard() { view.endEditing(true) } deinit { NotificationCenter.default.removeObserver(self) } } ``` --- ## 自定义 UIView ```swift class CustomCardView: UIView { private let titleLabel = UILabel() private let subtitleLabel = UILabel() private let iconImageView = UIImageView() override init(frame: CGRect) { super.init(frame: frame) setupView() setupConstraints() } required init?(coder: NSCoder) { super.init(coder: coder) setupView() setupConstraints() } private func setupView() { backgroundColor = .systemBackground layer.cornerRadius = 16 layer.shadowColor = UIColor.black.cgColor layer.shadowOpacity = 0.1 layer.shadowOffset = CGSize(width: 0, height: 2) layer.shadowRadius = 8 titleLabel.font = .systemFont(ofSize: 17, weight: .semibold) titleLabel.textColor = .label subtitleLabel.font = .systemFont(ofSize: 14) subtitleLabel.textColor = .secondaryLabel iconImageView.contentMode = .scaleAspectFit iconImageView.tintColor = .systemBlue addSubview(iconImageView) addSubview(titleLabel) addSubview(subtitleLabel) } private func setupConstraints() { iconImageView.translatesAutoresizingMaskIntoConstraints = false titleLabel.translatesAutoresizingMaskIntoConstraints = false subtitleLabel.translatesAutoresizingMaskIntoConstraints = false NSLayoutConstraint.activate([ iconImageView.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 16), iconImageView.centerYAnchor.constraint(equalTo: centerYAnchor), iconImageView.widthAnchor.constraint(equalToConstant: 40), iconImageView.heightAnchor.constraint(equalToConstant: 40), titleLabel.leadingAnchor.constraint(equalTo: iconImageView.trailingAnchor, constant: 12), titleLabel.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -16), titleLabel.topAnchor.constraint(equalTo: topAnchor, constant: 16), subtitleLabel.leadingAnchor.constraint(equalTo: titleLabel.leadingAnchor), subtitleLabel.trailingAnchor.constraint(equalTo: titleLabel.trailingAnchor), subtitleLabel.topAnchor.constraint(equalTo: titleLabel.bottomAnchor, constant: 4), subtitleLabel.bottomAnchor.constraint(lessThanOrEqualTo: bottomAnchor, constant: -16) ]) } func configure(title: String, subtitle: String, icon: String) { titleLabel.text = title subtitleLabel.text = subtitle iconImageView.image = UIImage(systemName: icon) } } ``` FILE:references/uikit-basics.md # UIKit 基础参考 > 来源：Apple UIKit Documentation（2026-04-23） > https://developer.apple.com/documentation/uikit ## UIViewController ### 基础控制器 ```swift import UIKit class MyViewController: UIViewController { override func viewDidLoad() { super.viewDidLoad() view.backgroundColor = .systemBackground } } ``` ### 生命周期 | 方法 | 调用时机 | |------|---------| | viewDidLoad | 视图加载完成 | | viewWillAppear | 即将显示 | | viewDidAppear | 已显示 | | viewWillDisappear | 即将消失 | | viewDidDisappear | 已消失 | ## UIView ### 常用视图 ```swift let label = UILabel() label.text = "Hello" label.font = .systemFont(ofSize: 17) label.textColor = .label let button = UIButton(type: .system) button.setTitle("Click", for: .normal) let imageView = UIImageView(image: UIImage(systemName: "star")) ``` ### 布局（Auto Layout） ```swift label.translatesAutoresizingMaskIntoConstraints = false NSLayoutConstraint.activate([ label.centerXAnchor.constraint(equalTo: view.centerXAnchor), label.centerYAnchor.constraint(equalTo: view.centerYAnchor) ]) ``` ### SnapKit 布局 ```swift import SnapKit view.addSubview(label) label.snp.makeConstraints { make in make.center.equalToSuperview() make.width.equalTo(200) } ``` ## UITableView ### 数据源 ```swift class MyViewController: UIViewController, UITableViewDataSource { var items = ["A", "B", "C"] func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int { return items.count } func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell { let cell = tableView.dequeueReusableCell(withIdentifier: "Cell", for: indexPath) cell.textLabel?.text = items[indexPath.row] return cell } } ``` ### 委托 ```swift extension MyViewController: UITableViewDelegate { func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) { tableView.deselectRow(at: indexPath, animated: true) // 处理点击 } func tableView(_ tableView: UITableView, heightForRowAt indexPath: IndexPath) -> CGFloat { return 44 } } ``` ## UINavigationController ```swift // 推入 let detailVC = DetailViewController() navigationController?.pushViewController(detailVC, animated: true) // 弹出 navigationController?.popViewController(animated: true) // 返回根 navigationController?.popToRootViewController(animated: true) ``` ## UIAlertController ```swift // Alert let alert = UIAlertController( title: "标题", message: "消息内容", preferredStyle: .alert ) alert.addAction(UIAlertAction(title: "取消", style: .cancel)) alert.addAction(UIAlertAction(title: "确认", style: .default) { _ in // 处理确认 }) present(alert, animated: true) // Action Sheet let actionSheet = UIAlertController( title: nil, message: nil, preferredStyle: .actionSheet ) actionSheet.addAction(UIAlertAction(title: "选项1", style: .default)) actionSheet.addAction(UIAlertAction(title: "删除", style: .destructive)) actionSheet.addAction(UIAlertAction(title: "取消", style: .cancel)) ``` ## 通知与手势 ### 通知中心 ```swift // 监听 NotificationCenter.default.addObserver( self, selector: #selector(handleNotification), name: UIApplication.didEnterBackgroundNotification, object: nil ) // 发送 NotificationCenter.default.post( name: .myCustomNotification, object: nil, userInfo: ["key": "value"] ) // 移除 deinit { NotificationCenter.default.removeObserver(self) } ``` ### 手势识别 ```swift let tap = UITapGestureRecognizer(target: self, action: #selector(handleTap)) view.addGestureRecognizer(tap) @objc func handleTap() { // 处理点击 } ``` ## 网络请求 ### URLSession async/await ```swift func fetchData() async throws -> Data { guard let url = URL(string: "https://api.example.com/data") else { throw URLError(.badURL) } let (data, response) = try await URLSession.shared.data(from: url) guard let httpResponse = response as? HTTPURLResponse, (200...299).contains(httpResponse.statusCode) else { throw URLError(.badServerResponse) } return data } ``` ### JSON 解码 ```swift struct User: Codable { let id: String let name: String } func decodeUsers(from data: Data) throws -> [User] { let decoder = JSONDecoder() decoder.keyDecodingStrategy = .convertFromSnakeCase return try decoder.decode([User].self, from: data) } ``` FILE:references/widget.md # Widget 开发参考 > 来源：Apple WidgetKit Documentation（2026-04-23） > https://developer.apple.com/documentation/widgetkit ## Widget 概述 Widget 在锁屏、主屏幕、通知中心展示应用的实时信息。 ### 支持尺寸 | 尺寸 | 平台 | 尺寸 (pt) | |------|------|-----------| | systemSmall | iOS/macOS | 155×155 | | systemMedium | iOS/macOS | 329×155 | | systemLarge | iOS/macOS | 329×345 | | accessoryCircular | watchOS | 圆形 | | accessoryRectangular | watchOS | 矩形 | | accessoryInline | watchOS | 单行 | | accessoryCorner | iOS 16+ | 角落 | ### 锁屏 Widget | 类型 | 形状 | 用途 | |------|------|------| | accessoryCircular | 圆形 | 进度环、数据指标 | | accessoryRectangular | 矩形 | 标题+副标题 | | accessoryInline | 单行文字 | 简短信息 | ## 基础 Widget ### 项目结构 ``` MyWidget/ ├── MyWidget.swift # Widget 配置 ├── MyWidgetBundle.swift # App Entry ├── MyWidgetEntryView.swift # 视图 └── Assets.xcassets/ # 图片资源 ``` ### WidgetBundle ```swift import WidgetKit import SwiftUI @main struct MyWidgetBundle: WidgetBundle { var body: some Widget { MyWidget() if #available(iOS 17.0, *) { MyWidget_Interactive() // iOS 17+ 交互 } } } ``` ### Widget 配置 ```swift struct MyWidget: Widget { let kind: String = "MyWidget" var body: some WidgetConfiguration { StaticConfiguration(kind: kind, provider: Provider()) { entry in MyWidgetEntryView(entry: entry) } .configurationDisplayName("我的 Widget") .description("显示实时信息") .supportedFamilies([.systemSmall, .systemMedium, .systemLarge]) } } ``` ### TimelineProvider ```swift struct Provider: TimelineProvider { typealias Entry = MyWidgetEntry func placeholder(in context: Context) -> MyWidgetEntry { MyWidgetEntry(date: Date(), data: .placeholder) } func getSnapshot(in context: Context, completion: @escaping (MyWidgetEntry) -> Void) { let entry = MyWidgetEntry(date: Date(), data: fetchData()) completion(entry) } func getTimeline(in context: Context, completion: @escaping (Timeline) -> Void) { var entries: [MyWidgetEntry] = [] let currentDate = Date() for offset in 0..<5 { let entryDate = Calendar.current.date(byAdding: .minute, value: offset * 15, to: currentDate)! let entry = MyWidgetEntry(date: entryDate, data: fetchData()) entries.append(entry) } let timeline = Timeline(entries: entries, policy: .atEnd) completion(timeline) } private func fetchData() -> WidgetData { // 从 App Group 获取数据 return WidgetData() } } ``` ### Entry 模型 ```swift struct MyWidgetEntry: TimelineEntry { let date: Date let data: WidgetData } struct WidgetData { let title: String let value: String let trend: Double // 变化趋势 static let placeholder = WidgetData( title: "加载中", value: "...", trend: 0 ) } ``` ### Widget 视图 ```swift struct MyWidgetEntryView: View { var entry: Provider.Entry @Environment(\.widgetFamily) var family var body: some View { switch family { case .systemSmall: SmallView(data: entry.data) case .systemMedium: MediumView(data: entry.data) case .systemLarge: LargeView(data: entry.data) default: SmallView(data: entry.data) } } } struct SmallView: View { let data: WidgetData var body: some View { VStack(alignment: .leading, spacing: 4) { Text(data.title) .font(.caption) .foregroundStyle(.secondary) Text(data.value) .font(.title2) .fontWeight(.bold) TrendView(trend: data.trend) } .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .leading) .containerBackground(.fill.tertiary, for: .widget) } } ``` ## App Group 数据共享 ### 配置 1. Xcode: Signing & Capabilities → App Groups → 添加 group.xxx 2. 主 App 和 Widget Extension 都启用同一 App Group ### 共享数据 ```swift // 主 App 写入 let sharedDefaults = UserDefaults(suiteName: "group.xxx") sharedDefaults?.set(value, forKey: "widgetData") // Widget 读取 let sharedDefaults = UserDefaults(suiteName: "group.xxx") let value = sharedDefaults?.string(forKey: "widgetData") // 通知 Widget 刷新 WidgetCenter.shared.reloadTimelines(ofKind: "MyWidget") ``` ## Widget 交互（iOS 17+） ### Link 跳转 ```swift struct MyWidgetEntryView: View { var entry: Provider.Entry var body: some View { Link(destination: URL(string: "myapp://detail/\(entry.data.id)")!) { VStack { Text(entry.data.title) } } } } ``` ### Interactive Widget（iOS 17+） ```swift // iOS 17+ Button struct InteractiveWidget: Widget { var body: some WidgetConfiguration { StaticConfiguration(kind: "Interactive", provider: Provider()) { entry in InteractiveWidgetView(entry: entry) } .configurationDisplayName("交互 Widget") } } struct InteractiveWidgetView: View { var entry: MyWidgetEntry var body: some View { Button(intent: IncrementIntent()) { VStack { Text("\(entry.data.value)") .font(.largeTitle) Text("点击 +1") .font(.caption) } } .buttonStyle(.plain) } } // AppIntent import AppIntents struct IncrementIntent: AppIntent { static var title: LocalizedStringResource = "增加计数" func perform() async throws -> some IntentResult { // 更新数据 return .result() } } ``` ## Widget 刷新策略 | 策略 | 说明 | 使用场景 | |------|------|---------| | `.atEnd` | Timeline 末尾刷新 | 定期更新 | | `.after(date)` | 指定时间刷新 | 定时任务 | | `.never` | 不自动刷新 | 依赖外部触发 | ```swift let timeline = Timeline(entries: entries, policy: .after(nextUpdateDate)) ``` ### 背景刷新 ```swift // WidgetCenter 触发刷新 WidgetCenter.shared.reloadTimelines(ofKind: "MyWidget") WidgetCenter.shared.reloadAllTimelines() // 主 App 生命周期 class AppDelegate: NSObject, UIApplicationDelegate { func applicationDidBecomeActive(_ application: UIApplication) { WidgetCenter.shared.reloadTimelines(ofKind: "MyWidget") } } ``` ## Lock Screen Widget（iOS 16+） ```swift struct LockScreenWidget: Widget { var body: some WidgetConfiguration { StaticConfiguration(kind: "LockScreen", provider: Provider()) { entry in LockScreenView(entry: entry) } .configurationDisplayName("锁屏 Widget") .supportedFamilies([.accessoryCircular, .accessoryRectangular, .accessoryInline]) } } struct LockScreenView: View { @Environment(\.widgetFamily) var family var body: some View { switch family { case .accessoryCircular: Gauge(value: 0.7) { Text("%") } currentValueLabel: { Text("70") } .gaugeStyle(.accessoryCircularCapacity) case .accessoryRectangular: VStack(alignment: .leading) { Text("今日步数") .font(.headline) Text("8,542") .font(.title) } case .accessoryInline: Text("步数: 8,542") default: EmptyView() } } } ``` ## 避坑指南 | 错误做法 | 正确做法 | |---------|---------| | ❌ 复杂布局 | ✅ 简洁信息展示 | | ❌ 频繁网络请求 | ✅ 读取 App Group 数据 | | ❌ 耗时操作 | ✅ Timeline 预计算 | | ❌ 直接更新 UI | ✅ 触发 reloadTimelines | | ❌ 大图资源 | ✅ SF Symbols / 小图 | ## 来源 > Apple WidgetKit Documentation > https://developer.apple.com/documentation/widgetkit

Ios Dev Skill

Comments (0)