swiftui-patterns

SwiftUI 模式（iOS 17+）

SwiftUI 17+ 通过 @Observable 去除了 ObservableObject 样板代码，使用 @Environment 简化了环境注入，并引入了基于任务的异步模式。核心原则：使用 Apple 的现代 API，而非响应式库。

概览

快速参考

需求	使用（iOS 17+）	不要使用
可观察模型	@Observable	ObservableObject
已发布属性	普通属性	@Published
自有状态	@State	@StateObject
传入的模型（绑定）	@Bindable	@ObservedObject
环境注入	environment(_:)	environmentObject(_:)
访问环境	@Environment(Type.self)	@EnvironmentObject
显示时执行异步操作	.task { }	.onAppear { Task {} }
值变化	onChange(of:initial:_:)	onChange(of:perform:)

核心工作流

1. 使用 @Observable 定义模型类（无需 @Published）
2. 使用 @State 保存视图拥有的模型，使用 @Bindable 接收传入的模型
3. 使用 .task { } 执行异步工作（视图消失时自动取消）
4. 使用 NavigationStack 搭配 NavigationPath 实现编程式导航
5. 为可交互元素应用 .accessibilityLabel() 和 .accessibilityHint()

参考资料加载指南

只要有一丝可能需要这些内容，就务必加载参考文件。 有上下文总比遗漏模式或犯错要好。

参考资料	何时加载
Observable	创建新的 @Observable 模型类时
State Management	在 @State、@Bindable 和 @Environment 之间选择时
Environment	向视图层级注入依赖项时
View Modifiers	使用 onChange、task 或 iOS 17+ 修饰符时
Migration Guide	将 iOS 16 代码更新到 iOS 17+ 时
MVVM Observable	搭建视图模型架构时
Navigation	实现编程式导航或深层链接导航时
Performance	列表包含 100+ 项或发生过多重新渲染时
UIKit Interop	封装 UIKit 组件（WKWebView、PHPicker）时
Accessibility	使用 VoiceOver、Dynamic Type 或辅助功能操作时
Async Patterns	处理加载状态、刷新或后台任务时
Composition	创建可复用视图修饰符或复杂的条件式 UI 时

常见错误

1. 对传入的模型过度使用 @Bindable — 为每个属性都创建 @Bindable 会导致不必要的视图重新加载。仅对需要双向绑定的可变模型属性使用 @Bindable。只读计算属性应使用普通属性。

2. 状态放置错误 — 将模型状态放在视图中，而不是专用的 @Observable 模型中，会导致视图逻辑变得混乱。务必将模型和视图职责分开。

3. NavigationPath 状态损坏 — 错误地修改 NavigationPath 可能使其处于不一致状态。使用 navigationDestination(for:destination:) 并妥善管理状态，以避免路径损坏。

4. 未处理 .task 取消 — .task 会在视图消失时自动处理取消，但嵌套的 Task 不会。复杂的异步流程需要显式跟踪取消，以避免残留任务。

5. 忽略环境失效 — 在父视图中更改环境值不会自动使子视图失效。请始终一致地使用 @Environment，并了解观察机制会在何时触发重新渲染。

6. UIKit 互操作导致内存泄漏 — 如果未打破委托引用循环，UIViewRepresentable 和 UIViewControllerRepresentable 可能导致内存泄漏。必须使用弱引用并进行显式清理。