ios-navigation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Apple iOS Navigation Best Practices

Apple iOS 导航最佳实践

Comprehensive guide for building fluid, golden-standard navigation in iOS apps with SwiftUI. Contains 51 rules across 8 categories covering architecture, anti-patterns, transitions, modals, flow orchestration, performance, accessibility, and state restoration.

这是一份使用SwiftUI在iOS应用中构建流畅、黄金标准导航的综合指南。包含8个类别下的51条规则，覆盖架构、反模式、过渡、模态视图、流程编排、性能、无障碍访问和状态恢复。

When to Apply

适用场景

Reference these guidelines when:

Designing navigation hierarchies with NavigationStack or NavigationSplitView
Choosing between push, sheet, and fullScreenCover
Implementing hero animations, zoom transitions, or gesture-driven dismissals
Building multi-step flows (onboarding, checkout, registration)
Using @Observable with @Environment and @Bindable for shared navigation state
Reviewing code for navigation anti-patterns
Adding deep linking, state restoration, or tab persistence
Ensuring VoiceOver and reduce motion support for navigation

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

使用NavigationStack或NavigationSplitView设计导航层级
在push、sheet和fullScreenCover之间做选择
实现英雄动画、缩放过渡或手势驱动的关闭操作
构建多步骤流程（引导页、结账、注册）
结合@Environment和@Bindable使用@Observable来管理共享导航状态
检查导航代码中的反模式
添加深度链接、状态恢复或标签页持久化
确保导航支持VoiceOver和减少动态效果

Rule Categories by Priority

按优先级划分的规则类别


arch-
anti-
anim-
modal-
flow-
perf-
ally-
state-

Priority	Category	Impact	Prefix
1	Navigation Architecture	CRITICAL	`arch-`
2	Navigation Anti-Patterns	CRITICAL	`anti-`
3	Transition & Animation	HIGH	`anim-`
4	Modal Presentation	HIGH	`modal-`
5	Flow Orchestration	HIGH	`flow-`
6	Navigation Performance	MEDIUM-HIGH	`perf-`
7	Navigation Accessibility	MEDIUM	`ally-`
8	State & Restoration	MEDIUM	`state-`


arch-
anti-
anim-
modal-
flow-
perf-
ally-
state-

优先级	类别	影响程度	前缀
1	导航架构	关键	`arch-`
2	导航反模式	关键	`anti-`
3	过渡与动画	高	`anim-`
4	模态视图呈现	高	`modal-`
5	流程编排	高	`flow-`
6	导航性能	中高	`perf-`
7	导航无障碍访问	中	`ally-`
8	状态与恢复	中	`state-`

Quick Reference

快速参考

1. Navigation Architecture (CRITICAL)

1. 导航架构（关键）

```
arch-navigation-stack
```
- Use NavigationStack over deprecated NavigationView
```
arch-value-based-links
```
- Use value-based NavigationLink over destination closures
```
arch-destination-registration
```
- Register navigationDestination at stack root
```
arch-destination-item
```
- Use navigationDestination(item:) for optional-based navigation (iOS 17+)
```
arch-route-enum
```
- Define routes as Hashable enums
```
arch-split-view
```
- Use NavigationSplitView for multi-column layouts
```
arch-coordinator
```
- Extract navigation logic into Observable coordinator
```
arch-observable-environment
```
- Use @Environment with @Observable and @Bindable for shared state
```
arch-deep-linking
```
- Handle deep links by appending to NavigationPath
```
arch-navigation-path
```
- Use NavigationPath for heterogeneous type-erased navigation

```
arch-navigation-stack
```
- 使用NavigationStack替代已弃用的NavigationView
```
arch-value-based-links
```
- 使用基于值的NavigationLink而非目标闭包
```
arch-destination-registration
```
- 在栈根注册navigationDestination
```
arch-destination-item
```
- 使用navigationDestination(item:)实现基于可选值的导航（iOS 17+）
```
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实现异构类型擦除的导航

2. Navigation Anti-Patterns (CRITICAL)

2. 导航反模式（关键）

```
anti-mixed-link-styles
```
- Avoid mixing NavigationLink(destination:) with NavigationLink(value:)
```
anti-scattered-destinations
```
- Avoid scattering navigationDestination across views
```
anti-shared-stack
```
- Avoid sharing NavigationStack across tabs
```
anti-hidden-back-button
```
- Avoid hiding back button without preserving swipe gesture
```
anti-navigation-in-init
```
- Avoid heavy work in view initializers
```
anti-hamburger-menu
```
- Avoid hamburger menu navigation
```
anti-programmatic-tab-switch
```
- Avoid programmatic tab selection changes

```
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. Transition & Animation (HIGH)

3. 过渡与动画（高）

```
anim-zoom-transition
```
- Use zoom navigation transition for hero animations (iOS 18+)
```
anim-matched-geometry-same-view
```
- Use matchedGeometryEffect only within same view hierarchy
```
anim-spring-config
```
- Use modern spring animation syntax (iOS 17+)
```
anim-gesture-driven
```
- Use interactive spring animations for gesture-driven transitions
```
anim-transition-source-styling
```
- Style transition sources with shape and background
```
anim-reduce-motion-transitions
```
- Respect reduce motion for all navigation animations
```
anim-scroll-driven
```
- Use onScrollGeometryChange for scroll-driven transitions (iOS 18+)

```
anim-zoom-transition
```
- 使用缩放导航过渡实现英雄动画（iOS 18+）
```
anim-matched-geometry-same-view
```
- 仅在同一视图层级内使用matchedGeometryEffect
```
anim-spring-config
```
- 使用现代弹簧动画语法（iOS 17+）
```
anim-gesture-driven
```
- 为手势驱动的过渡使用交互式弹簧动画
```
anim-transition-source-styling
```
- 为过渡源添加形状和背景样式
```
anim-reduce-motion-transitions
```
- 所有导航动画均需遵循减少动态效果的设置
```
anim-scroll-driven
```
- 使用onScrollGeometryChange实现滚动驱动的过渡（iOS 18+）

4. Modal Presentation (HIGH)

4. 模态视图呈现（高）

```
modal-sheet-vs-push
```
- Use push for drill-down, sheet for supplementary content
```
modal-detents
```
- Use presentation detents for contextual sheet sizing
```
modal-fullscreen-cover
```
- Use fullScreenCover only for immersive standalone experiences
```
modal-sheet-placement
```
- Place .sheet on container view, not on NavigationLink
```
modal-interactive-dismiss
```
- Guard unsaved changes with interactiveDismissDisabled
```
modal-nested-navigation
```
- Use separate NavigationStack inside modals

```
modal-sheet-vs-push
```
- 向下钻取使用push，补充内容使用sheet
```
modal-detents
```
- 使用presentation detents实现上下文相关的sheet尺寸
```
modal-fullscreen-cover
```
- 仅在沉浸式独立体验中使用fullScreenCover
```
modal-sheet-placement
```
- 将.sheet添加到容器视图，而非NavigationLink
```
modal-interactive-dismiss
```
- 使用interactiveDismissDisabled保护未保存的更改
```
modal-nested-navigation
```
- 在模态视图内部使用独立的NavigationStack

5. Flow Orchestration (HIGH)

5. 流程编排（高）

```
flow-tab-independence
```
- Give each tab its own NavigationStack
```
flow-multi-step
```
- Use NavigationStack with route array for multi-step flows
```
flow-sidebar-navigation
```
- Use NavigationSplitView with selection binding for sidebar
```
flow-tab-sidebar-adaptive
```
- Use sidebarAdaptable TabView for iPad tab-to-sidebar (iOS 18+)
```
flow-pop-to-root
```
- Implement pop-to-root by clearing NavigationPath
```
flow-screen-independence
```
- Keep screens independent of parent navigation context

```
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. Navigation Performance (MEDIUM-HIGH)

6. 导航性能（中高）

```
perf-lazy-destinations
```
- Use value-based NavigationLink for lazy destination construction
```
perf-task-modifier
```
- Use .task for async data loading on navigation
```
perf-state-object-ownership
```
- Own @Observable state with @State, pass as plain property
```
perf-avoid-body-side-effects
```
- Avoid side effects in view body
```
perf-lazy-view-wrapper
```
- Use LazyView wrapper for pre-iOS 16 destination loading

```
perf-lazy-destinations
```
- 使用基于值的NavigationLink实现目标视图的延迟构建
```
perf-task-modifier
```
- 使用.task在导航时加载异步数据
```
perf-state-object-ownership
```
- 使用@State持有@Observable状态，以普通属性传递
```
perf-avoid-body-side-effects
```
- 避免在视图body中产生副作用
```
perf-lazy-view-wrapper
```
- 使用LazyView包装器实现iOS 16之前的目标视图延迟加载

7. Navigation Accessibility (MEDIUM)

7. 导航无障碍访问（中）

```
ally-rotor-headers
```
- Mark navigation section headers for VoiceOver rotor
```
ally-focus-after-navigation
```
- Manage focus after programmatic navigation events
```
ally-group-navigation-elements
```
- Group related navigation elements to reduce swipe count
```
ally-hide-decorative-navigation
```
- Hide decorative navigation elements from VoiceOver
```
ally-keyboard-focus
```
- Use @FocusState for keyboard navigation in forms

```
ally-rotor-headers
```
- 为VoiceOver转子标记导航章节标题
```
ally-focus-after-navigation
```
- 在编程式导航事件后管理焦点
```
ally-group-navigation-elements
```
- 对相关导航元素进行分组以减少滑动次数
```
ally-hide-decorative-navigation
```
- 向VoiceOver隐藏装饰性导航元素
```
ally-keyboard-focus
```
- 在表单中使用@FocusState实现键盘导航

8. State & Restoration (MEDIUM)

8. 状态与恢复（中）

```
state-codable-routes
```
- Make route enums Codable for navigation persistence
```
state-scene-storage
```
- Use SceneStorage for per-scene navigation persistence
```
state-tab-persistence
```
- Persist selected tab with SceneStorage
```
state-deep-link-urls
```
- Parse deep link URLs into route enums
```
state-avoid-app-level-path
```
- Avoid defining NavigationPath at App level

```
state-codable-routes
```
- 将路由枚举设为Codable以实现导航持久化
```
state-scene-storage
```
- 使用SceneStorage实现每个场景的导航持久化
```
state-tab-persistence
```
- 使用SceneStorage持久化选中的标签页
```
state-deep-link-urls
```
- 将深度链接URL解析为路由枚举
```
state-avoid-app-level-path
```
- 避免在App级别定义NavigationPath

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件获取详细说明和代码示例：

章节定义 - 类别结构和影响级别
规则模板 - 添加新规则的模板

Reference Files

参考文件

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

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