ios-navigation

iOS 导航（Modular MVVM-C）

为采用 clinic 模块化架构的 SwiftUI 应用提供明确的导航规范。重点关注协调器与路由外壳的接线、功能隔离，以及可靠的 push／sheet／深层链接流程。

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

• 每个导航视图都使用 @Equatable 宏，绝不使用 AnyView
• 全面使用 @Observable，绝不使用 ObservableObject / @Published
• App 目标中的协调器拥有 NavigationPath；路由外壳负责 .navigationDestination 映射
• 模态状态由协调器拥有，绝不使用内联 @State 布尔值控制 sheet
• Domain 层定义协调器协议；具体协调器不得放在功能模块中

Clinic 架构约定（iOS 26 / Swift 6.2）

本技能中的所有指导均基于 clinic 模块化 MVVM-C 架构：

• 功能模块仅导入 Domain + DesignSystem（绝不导入 Data，也不导入同级功能模块）
• App 目标是汇合点，拥有 DependencyContainer、具体协调器和路由外壳接线
• Domain 保持纯 Swift，并定义模型以及 repository、*Coordinating、ErrorRouting 和 AppError 契约
• Data 负责 SwiftData／网络／同步／重试／后台 I/O，并实现 Domain 协议
• 读写流程默认采用 stale-while-revalidate 读取和乐观排队写入
• ViewModel 直接调用 repository 协议（默认不设用例／interactor 层）

适用场景

在以下场景中参考这些指南：

• 使用 NavigationStack 或 NavigationSplitView 设计导航层级
• 选择 push、sheet 或 fullScreenCover
• 实现 hero 动画、缩放转场或手势驱动的关闭操作
• 构建多步骤流程（引导、结账、注册）
• 使用 @Observable、@Environment 和 @Bindable 共享导航状态
• 审查代码中的导航反模式和模块化架构合规性
• 添加深层链接、状态恢复或标签页持久化
• 确保导航支持 VoiceOver 和减弱动态效果

按优先级划分的规则类别

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

| 3 | 转场与动画 | HIGH | anim- | | 4 | 模态呈现 | HIGH | modal- | | 5 | 流程编排 | HIGH | flow- | | 6 | 导航性能 | MEDIUM-HIGH | perf- | | 7 | 导航无障碍性 | MEDIUM | ally- | | 8 | 状态与恢复 | MEDIUM | 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 - 对共享状态使用 @Observable 和 @Bindable 搭配 @Environment
• 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 - 下钻时使用 push，补充内容使用 sheet
• modal-detents - 使用呈现 detents 设置上下文相关的 sheet 尺寸
• 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 - 使用带有 selection 绑定的 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 - 避免在视图 body 中产生副作用

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 - 避免在 App 级别定义 NavigationPath

使用方法

阅读各个参考文件，了解详细说明和代码示例：

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

参考文件

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