SwiftUI UI Patterns 是一套面向 SwiftUI 界面构建与重构的组件模式与示例集合，主要用于在塑造导航、状态、布局、控件或屏幕组合时提供可参考的实践指引。
用途 该技能围绕 SwiftUI 的界面开发，帮助开发者在已有项目或新项目中采用一致的组件模式。它适用于需要处理导航结构、状态管理、布局组织、控件使用以及屏幕组合等任务的场景。
主要能力 它提供按目标划分的使用路径。对于已有项目，流程包括：识别功能或屏幕及其主要交互模型（列表、详情、编辑器、设置、标签页）；在仓库中查找相近示例（例如使用 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，并在模式依赖最低操作系统版本时注明；仅在编辑遗留文件时维护现有遗留模式；遵循项目的格式化工具与风格指南。
关于 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。应先选择所有权位置，再选择包装器，当普通值状态足够时不要引入引用模型。
跨领域参考 除上述参考外，当 SwiftUI API、可用性或平台指引可能已变化时，建议使用网络搜索查阅当前的 Apple Developer 文档。列出的参考文档包括：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、fixtures、模拟环境与隔离预览设置）、references/performance.md（稳定标识、观察范围、惰性容器与渲染成本护栏）。
反模式 该技能列出若干反模式：在一个文件中混合布局、业务逻辑、网络、路由与格式化的巨型视图；为互斥的 sheets、alerts 或导航目标使用多个布尔标志；在由 body 驱动的代码路径中直接进行实时服务调用，而不是在视图生命周期钩子或注入的模型/服务中进行；为绕过类型不匹配而使用 AnyView，而这类问题应通过更好的组合解决；在没有明确所有权理由的情况下将每个共享依赖默认为 @EnvironmentObject 或全局路由器。
新 SwiftUI 视图的工作流程 该技能给出新视图的工作流程：在编写 UI 代码前定义视图的状态、所有权位置与最低操作系统假设；确定哪些依赖属于 @Environment，哪些应保持为显式初始化器输入；勾勒视图层级、路由模型与呈现点，将重复部分提取为子视图，复杂导航可阅读 references/navigationstack.md、references/sheets.md 或 references/deeplinks.md，并在继续前构建并验证无编译器错误；使用 .task 或 .task(id:) 实现异步加载，并在需要时显式处理加载与错误状态，当工作依赖变化的输入或取消时阅读 references/async-state.md；为主要与次要状态添加预览，然后在 UI 可交互时添加无障碍标签或标识符，当视图需要 fixtures 或注入模拟依赖时阅读 references/previews.md；通过构建进行验证：确认无编译器错误，检查预览渲染不崩溃，确保状态变化正确传播，并检查列表标识与观察范围不会导致可避免的重新渲染，如果屏幕较大、滚动密集或频繁更新则阅读 references/performance.md。对于常见 SwiftUI 编译错误（缺少 @State 注解、模糊的 ViewBuilder 闭包或不匹配的泛型类型），应在更新调用点前解决。如果构建失败，仔细阅读错误信息，修复已识别的问题，然后重新构建再继续下一步。如果预览崩溃，隔离出问题的子视图，确认其状态初始化有效，然后重新运行预览再继续。
组件参考 使用 references/components-index.md 作为入口点。每个组件参考应包含：意图与最适用场景；带有本地约定的最小使用模式；陷阱与性能注意事项；当前仓库中现有示例的路径。
添加新组件参考 添加新组件参考的步骤：创建 references/<component>.md；保持简短且可操作，链接到当前仓库中的具体文件；用新条目更新 references/components-index.md。
适用场景与限制 该技能适用于 SwiftUI 项目的界面构建与重构，尤其是涉及导航、状态、布局、控件与屏幕组合的场景。其规则区分了 iOS 17+ 与 iOS 16 及更早版本的 API 选择，并强调在模式依赖最低操作系统版本时注明。关于具体收费、价格、平台支持范围等信息，资料中暂未提供。