name: swiftui-ui-patternsdescription: Apply proven SwiftUI UI patterns for navigation, sheets, async state, and reusable screens.risk: safesource: “Dimillian/Skills (MIT)”date_added: “2026-03-25”SwiftUI UI 模式快速开始何时使用创建或重构 SwiftUI 界面、流程或可复用 UI 组件时。需要导航、弹窗、异步状态、预览或组件模式方面的指导时。根据你的目标选择一条路径已有项目识别功能或界面以及主要交互模型列表、详情、编辑器、设置、标签页式。在仓库中用rg TabView\(或类似方式找到相近的示例然后阅读最接近的 SwiftUI 视图。遵循本地约定优先使用 SwiftUI 原生状态尽可能保持状态局部化对共享依赖使用环境注入。从references/components-index.md中选择相关组件参考并遵循其指导。如果交互是通过拖拽或滚动移开主内容来揭示次级内容在手动实现手势前先阅读references/scroll-reveal.md。用小而专注的子视图和 SwiftUI 原生数据流构建视图。新项目脚手架从references/app-wiring.md开始装配 TabView NavigationStack 弹窗。基于提供的骨架添加一个最小的AppTab和RouterPath。根据你首先需要的 UI 选择下一个组件参考TabView、NavigationStack、Sheets。随着新界面的加入扩展路由和弹窗枚举。应遵循的通用规则使用现代 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:)。避免在弹窗 body 内使用if let。弹窗应拥有自己的操作并在内部调用dismiss()而不是转发onCancel/onConfirm闭包。滚动驱动的揭示优先从滚动偏移量推导归一化进度值并从这个单一数据源驱动视觉状态。除非仅靠滚动无法表达该交互否则避免并行的手势状态机。状态所有权总结使用与所有权模型匹配的最窄状态工具场景首选模式单个视图拥有的局部 UI 状态State子视图修改父视图拥有的值状态BindingiOS 17 上根拥有的引用模型State搭配Observable类型子视图读取或修改注入的Observable模型iOS 17将其显式作为存储属性传递共享应用服务或配置Environment(Type.self)iOS 16 及更早版本的遗留引用模型根部用StateObject注入时用ObservedObject先选择所有权位置再选择包装器。当普通值状态就足够时不要引入引用模型。跨领域参考references/navigationstack.md导航所有权、每个标签页的历史记录和枚举路由。references/sheets.md集中式模态展示和枚举驱动的弹窗。references/deeplinks.mdURL 处理以及将外部链接路由到应用目的地。references/app-wiring.md根依赖图、环境用法和应用外壳装配。references/async-state.md.task、.task(id:)、取消、防抖和异步 UI 状态。references/previews.md#Preview、fixtures、模拟环境和隔离的预览设置。references/performance.md稳定身份、观察范围、懒加载容器和渲染成本护栏。反模式在单个文件中混入布局、业务逻辑、网络、路由和格式化的巨型视图。用多个布尔标志管理互斥的弹窗、警告或导航目的地。在body驱动的代码路径中直接进行实时服务调用而不是使用视图生命周期钩子或注入的模型/服务。为了绕过本应通过更好组合解决的类型不匹配而使用AnyView。在没有明确所有权理由的情况下把每个共享依赖都默认成EnvironmentObject或全局路由器。新 SwiftUI 视图的工作流程在编写 UI 代码之前定义视图的状态、所有权位置和最低 OS 假设。识别哪些依赖应放在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。限制仅当任务与上述范围明确匹配时使用此技能。不要将输出视为特定环境验证、测试或专家审查的替代品。如果缺少必需的输入、权限、安全边界或成功标准停下来询问澄清。