
关于
应用经过验证的 SwiftUI UI 模式,涵盖导航、Sheet、异步状态和可复用页面
name: swiftui-ui-patterns description: 应用经过验证的 SwiftUI UI 模式,涵盖导航、sheets、异步状态和可复用界面。 risk: safe source: "Dimillian/Skills (MIT)" date_added: "2026-03-25"
SwiftUI UI 模式
快速开始
何时使用
- 创建或重构 SwiftUI 界面、流程或可复用 UI 组件时。
- 需要导航、sheets、异步状态、预览或组件模式的指导时。
根据你的目标选择路径:
现有项目
- 确定功能或界面以及主要交互模型(列表、详情、编辑器、设置、标签页)。
- 在仓库中用
rg "TabView\("或类似命令找到附近的示例,然后阅读最接近的 SwiftUI 视图。 - 应用本地约定:优先使用 SwiftUI 原生状态,尽可能保持状态局部化,对共享依赖使用环境注入。
- 从
references/components-index.md中选择相关组件参考并遵循其指导。 - 如果交互通过拖动或滚动主内容来显示次要内容,在手动实现手势之前阅读
references/scroll-reveal.md。 - 使用小型、专注的子视图和 SwiftUI 原生数据流构建视图。
新项目脚手架
- 从
references/app-wiring.md开始,连接 TabView + NavigationStack + sheets。 - 基于提供的骨架添加最小的
AppTab和RouterPath。 - 根据你首先需要的 UI 选择下一个组件参考(TabView、NavigationStack、Sheets)。
- 随着新界面的添加,扩展路由和 sheet 枚举。
通用规则
- 使用现代 SwiftUI 状态(
@State、@Binding、@Observable、@Environment),避免不必要的视图模型。 - 如果部署目标包含 iOS 16 或更早版本且无法使用 iOS 17 引入的 Observation API,则回退到
ObservableObject,使用@StateObject进行根所有权,@ObservedObject用于注入观察,@EnvironmentObject仅用于真正共享的应用级状态。 - 优先组合;保持视图小而专注。
- 使用 async/await 配合
.task和明确的加载/错误状态。关于重启、取消和防抖指导,阅读references/async-state.md。 - 将共享应用服务放在
@Environment中,但对功能局部依赖和模型优先使用显式初始化器注入。关于根连接模式,阅读references/app-wiring.md。 - 优先使用适合部署目标的最新 SwiftUI API,并在模式依赖特定 OS 时标注最低版本。
- 仅在编辑遗留文件时维护现有遗留模式。
- 遵循项目的格式化工具和风格指南。
- Sheets:当状态表示选中的模型时,优先使用
.sheet(item:)而非.sheet(isPresented:)。避免在 sheet body 内使用if let。Sheets 应拥有自己的操作并在内部调用dismiss(),而不是转发onCancel/onConfirm闭包。 - 滚动驱动的显示:优先从滚动偏移量派生归一化进度值,并从该单一数据源驱动视觉状态。除非仅靠滚动无法表达交互,否则避免并行手势状态机。
状态所有权总结
使用与所有权模型匹配的最窄状态工具:
| 场景 | 推荐模式 |
| --- | --- |
| 单个视图拥有的局部 UI 状态 | @State |
| 子视图修改父视图拥有的值状态 | @Binding |
| iOS 17+ 上根拥有的引用模型 | @State 配合 @Observable 类型 |
| iOS 17+ 上子视图读取或修改注入的 @Observable 模型 | 作为存储属性显式传递 |
| 共享应用服务或配置 | @Environment(Type.self) |
| iOS 16 及更早版本的遗留引用模型 | 根处用 @StateObject,注入时用 @ObservedObject |
先选择所有权位置,再选择包装器。当简单值状态足够时,不要引入引用模型。
交叉引用
references/navigationstack.md:导航所有权、每标签历史和枚举路由。references/sheets.md:集中式模态展示和枚举驱动的 sheets。references/deeplinks.md:URL 处理和将外部链接路由到应用目的地。references/app-wiring.md:根依赖图、环境使用和应用外壳连接。references/async-state.md:.task、.task(id:)、取消、防抖和异步 UI 状态。references/previews.md:#Preview、固定数据、模拟环境和隔离预览设置。references/performance.md:稳定标识、观察范围、懒加载容器和渲染成本护栏。
反模式
- 在一个文件中混合布局、业务逻辑、网络请求、路由和格式化的巨型视图。
- 为互斥的 sheets、alerts 或导航目的地使用多个布尔标志。
- 在
body驱动的代码路径中直接进行实时服务调用,而不是使用视图生命周期钩子或注入的模型/服务。 - 使用
AnyView来解决应该通过其他方式解决的类型不匹配问题。
兼容工具
Claude CodeCursor
标签
AI与机器学习