iOS导航（模块化MVVM-C）Skill ios-navigation

---

name: ios-navigation description: 面向iOS 26 / Swift 6.2诊所模块化MVVM-C应用的固执己见SwiftUI导航强制实施。强制实施领域协调器协议、应用目标DependencyContainer + 具体协调器 + 路由外壳、NavigationPath所有权、协调器拥有的模态状态、深度链接/状态恢复准备、以及陈旧-同时-重新验证/乐观排队流兼容性。在设计或重构诊所导航流程时使用。

iOS导航（模块化MVVM-C）

面向使用诊所模块化架构的SwiftUI应用的固执己见导航强制实施。专注于协调器 + 路由外壳接线、功能隔离和弹性推送/模态/深度链接流程。

不可协商的约束（iOS 26 / Swift 6.2）

• 每个导航视图上使用@Equatable宏，从不使用AnyView
• 到处使用@Observable，从不使用ObservableObject / @Published
• 应用目标协调器拥有NavigationPath；路由外壳拥有.navigationDestination映射
• 协调器拥有的模态状态，从不使用内联@State布尔值用于模态
• 领域层定义协调器协议；具体协调器保持在功能模块之外

诊所架构契约（iOS 26 / Swift 6.2）

本技能中的所有指导假设诊所模块化MVVM-C架构：

• 功能模块仅导入Domain + DesignSystem（从不导入Data，从不导入兄弟功能）
• 应用目标是聚合点并拥有DependencyContainer、具体协调器和路由外壳接线
• Domain保持纯Swift并定义模型加上仓库、*Coordinating、ErrorRouting和AppError契约
• Data拥有SwiftData/网络/同步/重试/后台I/O并实现Domain协议
• 读/写流默认采用陈旧-同时-重新验证读取和乐观排队写入
• 视图模型直接调用仓库协议（无默认用例/交互器层）

何时应用

参考这些指南当：

• 使用NavigationStack或NavigationSplitView设计导航层次结构
• 选择推送、模态和全屏覆盖
• 实现英雄动画、缩放过渡或手势驱动的取消
• 构建多步骤流程（如入门、结账、注册）
• 使用@Observable与@Environment和@Bindable共享导航状态
• 审查代码以查找导航反模式和模块化架构合规性
• 添加深度链接、状态恢复或选项卡持久化
• 确保VoiceOver和减少运动支持导航

按优先级分类的规则类别

优先级	类别	影响	前缀
1	导航架构	关键	arch-
2	导航反模式	关键	anti-

| 3 | 过渡与动画 | 高 | anim- | | 4 | 模态展示 | 高 | modal- | | 5 | 流程编排 | 高 | flow- | | 6 | 导航性能 | 中高 | perf- | | 7 | 导航可访问性 | 中 | ally- | | 8 | 状态与恢复 | 中 | state- |

快速参考

1. 导航架构（关键）

• arch-navigation-stack - 使用NavigationStack替代已弃用的NavigationView
• arch-value-based-links - 使用基于值的NavigationLink替代目的地闭包
• arch-destination-registration - 在堆栈根处注册navigationDestination
• arch-destination-item - 使用navigationDestination(item:)进行基于可选的导航（iOS 26 / Swift 6.2）
• arch-route-enum - 将路由定义为Hashable枚举
• arch-split-view - 使用NavigationSplitView进行多列布局
• arch-coordinator - 将导航逻辑提取到Observable协调器中
• arch-observable-environment - 使用@Environment与@Observable和@Bindable共享状态
• arch-deep-linking - 通过附加到NavigationPath处理深度链接
• arch-navigation-path - 使用NavigationPath进行异构类型擦除导航
• arch-equatable-views - 将@Equatable宏应用于每个导航视图
• arch-observable-only - 仅使用@Observable — 从不使用ObservableObject或@Published
• arch-no-anyview - 在导航中从不使用AnyView — 使用@ViewBuilder或泛型
• arch-coordinator-modals - 通过协调器呈现所有模态 — 从不使用内联@State

2. 导航反模式（关键）

• anti-mixed-link-styles - 避免混合使用NavigationLink(destination:)与NavigationLink(value:)
• anti-scattered-destinations - 避免在视图间分散navigationDestination
• anti-shared-stack - 避免在选项卡间共享NavigationStack
• anti-hidden-back-button - 避免隐藏后退按钮而不保留滑动手势
• anti-navigation-in-init - 避免在视图初始化器中执行繁重工作
• anti-hamburger-menu - 避免汉堡菜单导航
• anti-programmatic-tab-switch - 避免程序化选项卡选择更改

3. 过渡与动画（高）

• anim-zoom-transition - 使用缩放导航过渡进行英雄动画（iOS 18+）
• anim-matched-geometry-same-view - 仅在同一视图层次结构中使用matchedGeometryEffect
• anim-spring-config - 使用现代弹簧动画语法（iOS 26 / Swift 6.2）
• anim-gesture-driven - 为手势驱动的过渡使用交互式弹簧动画
• anim-transition-source-styling - 使用形状和背景样式化过渡源
• anim-reduce-motion-transitions - 尊重减少运动设置以处理所有导航动画
• anim-scroll-driven - 使用onScrollGeometryChange进行滚动驱动的过渡（iOS 18+）

4. 模态展示（高）

• modal-sheet-vs-push - 使用推送进行向下钻取，使用模态进行补充内容
• modal-detents - 使用展示detents进行上下文模态大小设置
• modal-fullscreen-cover - 仅对沉浸式独立体验使用fullScreenCover
• modal-sheet-placement - 将.sheet放在容器视图上，而不是NavigationLink上
• modal-interactive-dismiss - 使用interactiveDismissDisabled保护未保存的更改
• modal-nested-navigation - 在模态内使用单独的NavigationStack

5. 流程编排（高）

• flow-tab-independence - 给每个选项卡自己的NavigationStack
• flow-multi-step - 使用NavigationStack与路由数组进行多步骤流程
• flow-sidebar-navigation - 使用NavigationSplitView与选择绑定进行侧边栏
• flow-tab-sidebar-adaptive - 使用sidebarAdaptable TabView进行iPad选项卡到侧边栏（iOS 18+）
• flow-pop-to-root - 通过清除NavigationPath实现弹出到根
• flow-screen-independence - 保持屏幕独立于父导航上下文

6. 导航性能（中高）

• perf-lazy-destinations - 使用基于值的NavigationLink进行懒惰目的地构建
• perf-task-modifier - 使用.task进行导航上的异步数据加载
• perf-state-object-ownership - 使用@State拥有@Observable状态，作为普通属性传递
• perf-avoid-body-side-effects - 避免在视图体中产生副作用

7. 导航可访问性（中）

• ally-rotor-headers - 标记导航部分标题以用于VoiceOver转子
• ally-focus-after-navigation - 在程序化导航事件后管理焦点
• ally-group-navigation-elements - 分组相关导航元素以减少滑动次数
• ally-hide-decorative-navigation - 从VoiceOver隐藏装饰性导航元素
• ally-keyboard-focus - 在表单中使用@FocusState进行键盘导航

8. 状态与恢复（中）

• state-codable-routes - 使路由枚举Codable以进行导航持久化
• state-scene-storage - 使用SceneStorage进行每场景导航持久化
• state-tab-persistence - 使用SceneStorage持久化选定的选项卡
• state-deep-link-urls - 将深度链接URL解析为路由枚举
• state-avoid-app-level-path - 避免在应用级别定义NavigationPath

如何使用

阅读单个参考文件以获取详细解释和代码示例：

• 部分定义 - 类别结构和影响级别
• 规则模板 - 用于添加新规则的模板

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息