HarmonyOS ArkTS 组件级导航（Navigation）详解
Navigation是 HarmonyOS（ArkTS/ArkUI）应用中的页面导航容器组件。它负责管理界面之间的跳转、栈结构、显示模式、页面参数传递等导航行为，是构建多页面应用的官方推荐方式。华为开发者
一、什么是 Navigation？
在 HarmonyOS ArkTS 框架下，Navigation 是一个 UI 容器组件，承载应用的页面路由逻辑：
- 作为根视图容器 在应用根组件（通常是主页面 @Entry 的组件中）使用。
- 支持多种显示模式：Stack、Split、Auto。
- 管理内部页面 的切换、过渡和返回行为。 华为开发者
简单来说，它类似于传统手机开发的“导航栈控制器”，只是内置为声明式 UI 的一等组件。 华为开发者
二、核心能力与职责
Navigation 主要负责三件事：
- 页面栈管理 每个 Navigation 内部都有一个页面栈，由框架自动维护，支持进栈、出栈、替换等操作。 博客园
- 多显示模式支持 适配不同屏幕尺寸和场景。 华为开发者
- 跨模块/跨包导航 Navigation 不受模块边界限制，可以在应用模块之间跳转。 华为开发者
三、三种显示模式（NavigationMode）
Navigation 组件可以根据设备特性自动调整 UI 布局，主要有三种模式：
| 模式 | 说明 | 适用场景 |
|---|---|---|
| Stack | 单栏导航 | 手机竖屏等传统 UI |
| Split | 双栏导航（左右分栏） | 大屏/平板/横屏设备 |
| Auto | 自动适配 Stack 或 Split | 响应式布局（推荐） |
推荐使用 Auto 模式在不同设备上实现响应式导航（自动在单栏与分栏之间切换）。 华为开发者
四、Navigation 与页面路由关系
在 ArkTS/ArkUI 中，Navigation 承担了类似于“路由控制器 + 页面容器”的角色：
- Navigation 内嵌多个 NavDestination（页面目的地） 组件。
- 每个 NavDestination 代表一个可导航的页面。
- 页面之间的跳转由栈动作实现（push/pop/replace）。 华为开发者
简单结构示意：
Navigation() {
NavDestination({ name: "Home" }) { /* 主页面内容 */ }
NavDestination({ name: "Detail" }) { /* 详情页内容 */ }
}
内部实现上，Navigation 隐式维护一个 页面栈，当 push 一个目的地时，栈顶层 “当前可见”。 华为开发者
五、页面导航基本操作
1. Push（推入一个页面）
将新页面压入栈顶，使其显示：
this.navStack.pushPathByName("DetailPage", { id: 100 });
其中：
"DetailPage"表示目标页面名称（通常是在 route map 或 NavDestination 注册的名称）- 第二个参数是传递给页面的参数。 博客园
2. Pop（返回/出栈）
从当前栈顶返回上一个页面：
this.navStack.pop();
3. Replace（替换当前页面）
将当前页面替换为另一个页面：
this.navStack.replacePathByName("OtherPage", { foo: "bar" });
替换的行为不会增加栈深度，而是替换当前页面。 博客园
六、Navigation 配置与生命周期
虽然 Navigation 是 UI 组件，但它还有一些常见设置和生命周期行为：
NavigationLayout
Navigation 内通常包括：
- 导航栏标题
- 工具栏
- 内容区
开发者可以在 Navigation 中直接设置标题/样式属性，或使用自定义插槽（CustomBuilder）来自定义 UI。 CSDN
生命周期回调
- 子页面显示与隐藏具有生命周期。例如在 NavDestination 包装的页面上监听显示事件等。
- 使用 Navigation 时，页面自身组件生命周期也会在 push/pop 时触发。 DEV Community
七、与 Router 的关系
在早期 HarmonyOS 中，页面跳转常常使用 Router 进行：
router.pushUrl({ url: 'pages/Second' });
但随着 ArkTS Navigation 的出现，官方推荐：
优先使用 Navigation + NavPathStack 进行页面管理 而非 Router API，因为 Navigation 更契合声明式 UI 模型和栈式导航逻辑。 华为开发者
Router 仍可用于简单跳转（如跳转系统界面），但在应用内部正式结构建议全用 Navigation。 华为开发者
八、实战建议（Tips）
把 Navigation 放在 @Entry 组件的根节点 这样整个应用的路由管理更清晰。
所有可导航页面通过 NavDestination 或系统路由表注册 建立页面名称与组件映射。
统一使用 NavPathStack 管理栈 避免直接操纵 UI 状态而绕过栈逻辑。
使用 Auto 模式做跨设备适配 能够自动处理手机 / 平板 / 电视的大屏布局。 华为开发者
🏁 九、总结：为什么用 Navigation？
| 特性 | Navigation | Router |
|---|---|---|
| 栈式管理 | ✅ | ❌ |
| 多端自适配 | ✅ | ⚠️ |
| 参数传递 | 对象式 | URL query |
| 嵌套导航 | 支持 | 有限 |
Navigation 是 ArkTS 推荐的导航方式，可实现灵活、声明式、栈式的页面导航体验，是构建复杂 HarmonyOS 应用的核心导航组件。 华为开发者
