swiftui-ui-patterns

SwiftUI UI 模式

快速开始

何时使用

• 在创建或重构 SwiftUI 屏幕、流程或可复用 UI 组件时。
• 当你需要关于导航、sheet、异步状态、预览或组件模式的指导时。

根据你的目标选择一条路线：

现有项目

• 确定功能或屏幕以及主要交互模型（列表、详情、编辑器、设置、标签页）。
• 用 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 主体内使用 if let。Sheet 应拥有自己的操作，并在内部调用 dismiss()，而不是转发 onCancel/onConfirm 闭包。
• 滚动驱动的显现：优先从滚动偏移量派生一个归一化的进度值，并从这一个唯一数据源驱动视觉状态。避免并行的手势状态机，除非仅靠滚动无法表达该交互。

状态所有权摘要

使用与所有权模型匹配的最窄状态工具：

场景	首选模式
由一个视图拥有的本地 UI 状态	@State
子视图修改父视图拥有的值状态	@Binding
iOS 17+ 上根拥有的引用模型	@State 配合 @Observable 类型
iOS 17+ 上子视图读取或修改注入的 @Observable 模型	将其作为存储属性显式传递
共享应用服务或配置	@Environment(Type.self)
iOS 16 及更早版本上的遗留引用模型	根处使用 @StateObject，注入时使用 @ObservedObject

先选择所有权位置，再选择包装器。当普通值状态足够时，不要引入引用模型。

跨领域参考

• references/navigationstack.md：导航归属、每个标签页的历史记录，以及 enum 路由。
• references/sheets.md：集中式模态呈现与 enum 驱动的 sheet。
• references/deeplinks.md：URL 处理，以及将外部链接路由到应用目标位置。
• references/app-wiring.md：根依赖图、环境使用，以及应用外壳接线。
• references/async-state.md：.task、.task(id:)、取消、防抖，以及异步 UI 状态。
• references/previews.md：#Preview、fixture、mock 环境，以及隔离的预览设置。
• references/performance.md：稳定标识、观察范围、惰性容器，以及渲染开销护栏。

反模式

• 巨型视图，把布局、业务逻辑、网络、路由和格式化混在一个文件里。
• 为互斥的 sheet、alert 或导航目标使用多个布尔标志。
• 直接在由 body 驱动的代码路径中进行实时服务调用，而不是在视图生命周期钩子或注入的 model/service 中进行。
• 为了绕过本应通过更好组合来解决的类型不匹配而求助于 AnyView。
• 在没有明确归属理由的情况下，把每个共享依赖都默认设为 @EnvironmentObject 或全局 router。

新建 SwiftUI 视图的工作流

1. 在编写 UI 代码之前，先定义视图的状态、归属位置，以及最低 OS 假设。
2. 确定哪些依赖应放在 @Environment 中，哪些应保留为显式的初始化器输入。
3. 勾勒视图层级、路由模型和呈现点；将重复部分提取到子视图中。对于复杂导航，请阅读 references/navigationstack.md、references/sheets.md 或 references/deeplinks.md。在继续之前先构建并确认没有编译器错误。
4. 使用 .task 或 .task(id:) 实现异步加载，并在需要时提供显式的加载和错误状态。当工作依赖于变化的输入或取消时，请阅读 references/async-state.md。
5. 为主要状态和次要状态添加预览，然后在 UI 可交互时添加无障碍标签或标识符。当视图需要 fixture 或注入 mock 依赖时，请阅读 references/previews.md。
6. 通过构建进行验证：确认没有编译器错误，检查预览渲染时不会崩溃，确保状态变更能正确传播，并 sanity-check 列表标识和观察范围不会导致可避免的重复渲染。如果屏幕较大、滚动繁重或频繁更新，请阅读 references/performance.md。对于常见的 SwiftUI 编译错误——缺失 @State 注解、含糊的 ViewBuilder 闭包，或泛型类型不匹配——请在更新调用点之前解决它们。**如果构建失败：**仔细阅读错误消息，修复已识别的问题，然后重新构建，再继续下一步。如果预览崩溃，隔离出有问题的子视图，确认其状态初始化有效，然后重新运行预览再继续。

组件参考

使用 references/components-index.md 作为入口点。每个组件参考应包含：

• 意图和最适配的场景。
• 带有本地约定的最小用法模式。
• 陷阱和性能注意事项。
• 当前仓库中现有示例的路径。

添加新的组件参考

• 创建 references/<component>.md。
• 保持简短且可操作；链接到当前仓库中的具体文件。
• 用新条目更新 references/components-index.md。

限制

• 仅当任务与上述范围明确匹配时使用此技能。
• 不要将输出视为环境特定验证、测试或专家评审的替代品。
• 如果缺少必需输入、权限、安全边界或成功标准，请停止并请求澄清。