swiftui-navigation-navigator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SwiftUI Navigation with Navigator

基于Navigator的SwiftUI导航

When assisting the user with SwiftUI navigation in a project that uses Navigator or the NavigatorUI library, follow the conventions and patterns below. The skill is agent-agnostic; apply it whenever the user mentions Navigator, NavigatorUI, SwiftUI navigation, deep linking, checkpoints, managed navigation stack, or navigation destinations.

当你在使用Navigator或NavigatorUI库的项目中协助用户处理SwiftUI导航相关问题时，请遵循以下约定和模式。本技能不与特定Agent绑定，只要用户提及Navigator、NavigatorUI、SwiftUI导航、深链接、检查点、托管导航栈或导航目标时都可以使用。

When to use this skill

适用场景

Apply this skill when the user:

Mentions Navigator, NavigatorUI, or navigation in a Navigator-based codebase.
Asks about SwiftUI navigation patterns (push, sheet, deep link, return to a screen).
Works on deep linking, checkpoints, routes, or dismissible behavior.
Defines or refactors NavigationDestination enums or ManagedNavigationStack usage.

当用户出现以下情况时应用本技能：

提及Navigator、NavigatorUI，或基于Navigator的代码库中的导航相关内容
询问SwiftUI导航模式（入栈、弹窗、深链接、返回指定页面）
开发深链接、检查点、路由或可关闭行为相关功能
定义或重构NavigationDestination枚举或ManagedNavigationStack的用法

Core conventions

核心约定

Destinations: Enums conforming to
```
NavigationDestination
```
(Hashable + View). Provide a
```
body
```
that returns the correct view for each case; use associated values for parameters. Do not use
```
NavigationLink(value:label:)
```
or
```
NavigationLink(destination:label:)
```
for destination-driven navigation when using Navigator's no-registration flow.

Links: Use NavigationLink(to: SomeDestination.case, label: { ... })
. Navigator wraps the value internally; no per-type

navigationDestination(for: MyType.self)

registration is required.

Stack: Use ManagedNavigationStack { ... }
where a
```
NavigationStack
```
would go. It provides the
```
Navigator
```
in the environment and a single internal registration for all
```
NavigationDestination
```
types.
Navigator access: Use @Environment(\.navigator) var navigator
. Use the navigator for the current stack (from the closure of
```
ManagedNavigationStack
```
or from a child view). Do not assume the environment navigator is the root when inside a tab or presented view—it is the navigator for that stack.

目标（Destinations）：遵循
```
NavigationDestination
```
协议的枚举（同时满足Hashable + View协议）。提供
```
body
```
属性为每个枚举case返回对应的视图，使用关联值传递参数。使用Navigator的免注册流时，不要使用
```
NavigationLink(value:label:)
```
或
```
NavigationLink(destination:label:)
```
实现目标驱动的导航。
链接（Links）：使用**
```
NavigationLink(to: SomeDestination.case, label: { ... })
```
**。Navigator会在内部封装值，无需为每个类型单独注册
```
navigationDestination(for: MyType.self)
```
。
导航栈（Stack）：在原本使用
```
NavigationStack
```
的位置使用**
```
ManagedNavigationStack { ... }
```
**。它会在环境中提供
```
Navigator
```
实例，并为所有
```
NavigationDestination
```
类型提供统一的内部注册。
获取Navigator实例：使用**
```
@Environment(\.navigator) var navigator
```
**。获取的是当前栈对应的navigator（来自
```
ManagedNavigationStack
```
的闭包或子视图中）。在标签栏或弹出视图中不要默认环境中的navigator是根实例，它只对应当前栈的navigator。

Quick patterns

常用模式

Navigate / push:

navigator.navigate(to: HomeDestinations.pageN(55))

navigator.push(HomeDestinations.pageN(55))

; override method with

navigator.navigate(to: destination, method: .sheet)

(or

.managedSheet

.cover

.managedCover

.send

Declarative:

.navigate(to: $optionalDestination)

.navigate(trigger: $bool, destination: someDestination)

Checkpoint return: Define with

NavigationCheckpoints

and

checkpoint()

; attach with

.navigationCheckpoint(KnownCheckpoints.home)

; return with

navigator.returnToCheckpoint(KnownCheckpoints.home)

.navigationReturnToCheckpoint(trigger: $flag, checkpoint: KnownCheckpoints.home)

Deep link / send:

navigator.send(RootTabs.home, HomeDestinations.page2)

(or

navigator.perform(route: KnownRoutes.profilePhoto)

). Receive with

.onNavigationReceive { (tab: RootTabs) in ... return .auto }

.onNavigationReceive(assign: $selectedTab)

; for destinations use

.onNavigationReceive { (dest: HomeDestinations, navigator) in navigator.navigate(to: dest); return .auto }

.navigationAutoReceive(HomeDestinations.self)

Dismiss: From inside a presented view use
```
navigator.dismiss()
```
. From a parent use
```
dismissPresentedViews()
```
,
```
dismissAnyChildren()
```
, or
```
dismissAny()
```
as appropriate. Custom sheets/covers presented outside
```
navigate(to:)
```
must be wrapped in ManagedPresentationView { content }
or content.managedPresentationView()
(or ManagedNavigationStack { content }
if the sheet has its own stack) so Navigator can manage and dismiss them.
Lock: Use .navigationLocked()
on a view to make global
```
dismissAny()
```
throw (e.g. during a transaction).

导航/入栈：

navigator.navigate(to: HomeDestinations.pageN(55))

或

navigator.push(HomeDestinations.pageN(55))

；可以通过method参数覆盖导航方式：

navigator.navigate(to: destination, method: .sheet)

（可选值还有

.managedSheet

、

.cover

、

.managedCover

、

.send

）。

声明式导航：

.navigate(to: $optionalDestination)

或

.navigate(trigger: $bool, destination: someDestination)

。

返回检查点：通过

NavigationCheckpoints

和

checkpoint()

定义检查点；使用

.navigationCheckpoint(KnownCheckpoints.home)

绑定检查点；通过

navigator.returnToCheckpoint(KnownCheckpoints.home)

或

.navigationReturnToCheckpoint(trigger: $flag, checkpoint: KnownCheckpoints.home)

返回指定检查点。

深链接/发送：

navigator.send(RootTabs.home, HomeDestinations.page2)

（或

navigator.perform(route: KnownRoutes.profilePhoto)

）。使用

.onNavigationReceive { (tab: RootTabs) in ... return .auto }

或

.onNavigationReceive(assign: $selectedTab)

接收；针对目标的接收可以用

.onNavigationReceive { (dest: HomeDestinations, navigator) in navigator.navigate(to: dest); return .auto }

或

.navigationAutoReceive(HomeDestinations.self)

。

关闭视图：在弹出视图内部使用
```
navigator.dismiss()
```
。在父视图中可以按需使用
```
dismissPresentedViews()
```
、
```
dismissAnyChildren()
```
或
```
dismissAny()
```
。在
```
navigate(to:)
```
之外自定义弹出的sheet/cover必须用**
```
ManagedPresentationView { content }
```
或
```
content.managedPresentationView()
```
包裹（如果弹窗有自己的导航栈则用
```
ManagedNavigationStack { content }
```
**），这样Navigator才能管理和关闭这些视图。
导航锁定：在视图上使用**
```
.navigationLocked()
```
**可以让全局的
```
dismissAny()
```
调用抛出错误（例如处理事务过程中）。

Topic index (reference docs)

主题索引（参考文档）

For detailed explanations, code samples, and "why" notes, use the reference files:

Destinations — Defining NavigationDestination enums, body, associated values, delegation to a private View for environment/DI, destination-as-view in sheets, coordination pattern, external provided views.
Navigation — ManagedNavigationStack, why no registration is needed (AnyNavigationDestination), NavigationLink(to:label), imperative and declarative navigation, NavigationMethod, modular cards/tabs.
Dismissible — Navigation tree, dismiss vs dismissPresentedViews vs dismissAnyChildren vs dismissAny, navigationLocked, state-driven modifiers, wrapping custom sheets/covers.
Checkpoints — Defining and establishing checkpoints, returning and returning with value, state-driven return, state restoration, coordinator pattern.
Deep linking — send(values:), onNavigationReceive and resume types, routes vs destinations, NavigationRouteHandling, perform(route:), one router for URL and in-app.
Provided destinations — NavigationProvidedDestination, onNavigationProvidedView, NavigationProvidedView and placeholders, modular apps.

如需详细说明、代码示例和设计思路说明，请参考以下文件：

目标（Destinations） — 定义NavigationDestination枚举、body、关联值、委托给私有View实现环境/依赖注入、弹窗中的目标即视图、协调模式、外部提供视图。
导航（Navigation） — ManagedNavigationStack、免注册原理（AnyNavigationDestination）、NavigationLink(to:label)、命令式和声明式导航、NavigationMethod、模块化卡片/标签栏。
可关闭视图（Dismissible） — 导航树、dismiss与dismissPresentedViews、dismissAnyChildren、dismissAny的区别、navigationLocked、状态驱动修饰符、包裹自定义弹窗/覆盖层。
检查点（Checkpoints） — 定义和创建检查点、返回及带值返回、状态驱动返回、状态恢复、协调器模式。
深链接（Deep linking） — send(values:)、onNavigationReceive和恢复类型、路由与目标的区别、NavigationRouteHandling、perform(route:)、统一处理URL和应用内路由的路由器。
提供式目标（Provided destinations） — NavigationProvidedDestination、onNavigationProvidedView、NavigationProvidedView和占位符、模块化应用。

Do / don't

注意事项

Do: Use
```
NavigationLink(to: Destination.case)
```
; use
```
ManagedNavigationStack
```
; use checkpoints for "return to this place"; use send/receive for deep linking and tab switching; wrap custom presented views in
```
ManagedPresentationView
```
or
```
.managedPresentationView()
```
when Navigator should manage them.
Don't: Use
```
NavigationLink(destination:label:)
```
; use
```
NavigationLink(value:label:)
```
for destination types when aiming for no-registration flow (unless you explicitly register); present sheets or covers without wrapping when Navigator needs to dismiss or deep-link into the app.

推荐做法：使用
```
NavigationLink(to: Destination.case)
```
；使用
```
ManagedNavigationStack
```
；使用检查点实现“返回指定位置”；使用send/receive实现深链接和标签切换；当需要Navigator管理自定义弹出视图时，用
```
ManagedPresentationView
```
或
```
.managedPresentationView()
```
包裹。
不推荐做法：使用
```
NavigationLink(destination:label:)
```
；在使用免注册流时对目标类型使用
```
NavigationLink(value:label:)
```
（除非你显式注册）；当Navigator需要关闭或深链接进入对应页面时，不包裹自定义弹出的sheet或cover。

Root setup

根节点配置

Create a root

Navigator(configuration: NavigationConfiguration(...))

and apply .navigationRoot(navigator)
at the root view. Register provided destinations and receive handlers (e.g.

.onNavigationProvidedView(...)

.onNavigationRoute(router)

.onNavigationReceive(...)

) above

.navigationRoot(navigator)

as needed.

创建根

Navigator(configuration: NavigationConfiguration(...))

实例，并在根视图上应用**

.navigationRoot(navigator)

**。按需在

.navigationRoot(navigator)

上方注册提供式目标和接收处理器（例如

.onNavigationProvidedView(...)

、

.onNavigationRoute(router)

、

.onNavigationReceive(...)

）。

References

参考资料

In-repo: README, Documentation.docc, NavigatorDemo app for patterns.
External: Navigator Documentation; Medium articles — Advanced Navigation Destinations, Eliminating Navigation Registrations, Advanced Deep Linking, Navigation Checkpoints, SwiftUI Navigation With Dismissible.

仓库内：README、Documentation.docc、NavigatorDemo示例应用中的模式实现。
外部：Navigator官方文档；Medium文章 — Advanced Navigation Destinations、Eliminating Navigation Registrations、Advanced Deep Linking、Navigation Checkpoints、SwiftUI Navigation With Dismissible。