HarmonyOS ArkTS 页面导航（Navigation）全面介绍

在 HarmonyOS ArkTS 开发中，Navigation 组件 是实现页面跳转和路由管理的核心容器组件。它取代了早期的 Router 模式，提供了更加灵活、声明式、栈式的页面导航体验。华为开发者

传统页面跳转往往依赖于 URL 路由（比如 router.pushUrl()），但这在声明式 UI 时代会遇到一些限制：

路由跳转逻辑散落在代码里，维护成本变高
跨组件嵌套跳转难以管理
UI 和导航栈不易统一控制

Navigation 组件 作为"导航容器"，解决了这些痛点，符合 ArkTS 声明式 UI 架构：导航成为组件树的一部分，而不是全局的模块。华为开发者

Navigation 是一个 UI 容器组件，本质上是一个 路由栈容器：

托管多个页面（NavDestination）
管理页面之间的跳转、返回、替换、参数传递
可嵌套、可扩展、与状态控制对象 NavPathStack 配合使用

它既是页面根容器（如根级导航架构），也可在组件内部嵌套作为"局部导航"。[华为开发者 Navigation 核心构成

组件	作用
`Navigation`	主导航容器，包含页面栈逻辑
`NavPathStack`	管理当前 Navigation 所有页面栈操作（push/pop 等）
`NavDestination`	单个子页面容器
`NavigationMode`	决定导航的布局显示方式（Stack / Split / Auto / Full）

你可以把 Navigation 想象成一个"动态页面栈"，NavPathStack 就是导航的控制器。华为开发者

在 ArkUI 组件树中，Navigation 可以嵌套或叠加：

复制代码

 Navigation
 ├─ navbar（可选）
 ├─ 页面内容区（NavDestination）
 ├─ toolbar（可选）

Navigation 不仅负责页面内容切换，还提供可定制的标题栏、工具栏等 UI 区域。华为开发者

显示模式（NavigationMode）

Navigation 支持三种主要显示模式：

模式	说明
`Stack`	经典栈式导航（单页面显示）
`Split`	双栏显示（大屏设备适配）
`Auto`	自动根据屏幕大小切换 Stack / Split

推荐使用 Auto 模式实现响应式导航布局，提升跨设备体验。华为开发者

四、如何进行页面导航

在 ArkTS 中，路由控制并不通过全局 Router 模块，而是通过 Navigation 与 NavPathStack 的配合：

typescript 复制代码

 import { NavigationMode, NavPathStack } from '@ohos.arkui';
 
 @Entry
 @Component
 struct AppRoot {
   private navStack: NavPathStack = new NavPathStack();
 
   build() {
     Navigation(this.navStack)
       .mode(NavigationMode.Auto)
       .title("主导航页")
     {
       // 页面组件、NavDestination...
     }
   }
 }

NavPathStack 是导航操作的"大脑"，负责栈式管理和页面切换。华为开发者

2. 推入页面（Push 页面）

通过 NavPathStack 的方法向 navigation 栈 push 一个页面：

kotlin 复制代码

 this.navStack.pushPathByName("DetailPage", { id: 123 });

这里：

"DetailPage" 是页面在路由表中的名称
{ id: 123 } 是要传递给目标页的参数

NavPathStack 提供 push、replace、pop、remove 等丰富栈管理 API。华为开发者

3. 返回或出栈

返回上一级页面：

kotlin 复制代码

 this.navStack.pop();

也可以替换当前页面：

csharp 复制代码

 this.navStack.replacePathByName("NewPage", params);

NavPathStack 的 API 让你灵活控制栈里的页面。华为开发者

五、为什么不推荐旧 Router？

HarmonyOS 官方文档中明确提到：

页面路由模块 @ohos.router 不推荐用于主导航逻辑 ，建议使用 Navigation + NavPathStack 方式，因为它与声明式 UI 架构更契合。华为开发者

Router 模块仍可用于某些简单场景，但在 Navigation 全面到来之后，它更适合做"嵌套路由"或过渡方案。

特性	Navigation	旧 Router
页面栈控制	✅ 强	❌ 弱
嵌套路由	✅ 支持	❌ 有限
分栏 / 响应式	✅ Auto 模式	❌ 无
参数传递	✅ 对象形式	❌ 仅 URL query
动画与过渡	✅ 丰富可扩展	⚠️ 受限
UI 与导航结合	✅ 原生支持	❌ 逻辑分离

Navigation 正式成为 ArkTS 下推荐的"页面导航标准"方式。华为开发者

七、实践建议（实战派 Tips）

把 Navigation 放在根组件 在应用的入口页 @Entry 定义 Navigation，可以统一管理页面栈。

使用 navDestination 属性映射路由 为页面配置一个映射表，让 Navigation 根据名称动态 push 页面，而不是硬编码组件。

拆分多个 Navigation 对于大型应用的复杂模块级导航，可以拆分多个 Navigation 嵌套使用。

合理运用 NavigationMode 根据屏幕尺寸选择 Stack / Split / Auto，可同时兼容手机与大屏设备。华为开发者

结语

HarmonyOS ArkTS 的 Navigation 组件代表了声明式 UI 下的现代导航方案：它将 UI 与导航深度融合，提供栈式管理、参数传递、嵌套能力和响应式显示 。逐步取代传统 Router，是开发高质量 HarmonyOS 原生应用的推荐架构。华为开发者

HarmonyOS ArkTS 页面导航（Navigation）全面介绍