---

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 来解决应该通过其他方式解决的类型不匹配问题。