鸿蒙Router与Navigation组件导航示例详解（零基础实战）

鸿蒙Router与Navigation组件导航示例详解（零基础实战）
在鸿蒙（HarmonyOS）应用开发中，页面导航是最核心的基础能力，所有页面跳转、参数传递、页面栈管理都依赖 Router 系统路由 和 Navigation 组件导航 两套方案。
很多新手开发者经常混淆两者的使用场景，不知道该如何选型、如何实现跳转传参、如何混合使用。本文将从零拆解两大导航方案的核心原理、代码示例、差异对比、混合实战、避坑要点，所有代码可直接复制运行，适配鸿蒙标准开发规范，适合入门学习与项目落地。

一、核心概念：Router 与 Navigation 定位差异

首先明确两者的核心定位，这是选型的关键：

1. Router（系统路由模块）

Router 是鸿蒙全局页面路由，属于应用级别的页面管理方案，管控整个应用的页面栈，适用于跨页面、跨模块的全局页面跳转。
核心特点：

• 无UI组件，纯逻辑路由API
• 页面需在 main_page.json 全局注册
• 支持页面入栈、替换、返回、参数传递
• 适合应用全局页面跳转（首页、列表、详情、设置等独立页面）

2. Navigation（组件化导航）

Navigation 是鸿蒙容器级导航组件，是带UI的导航容器，依赖 NavPathStack 管理局部路由栈，主打局部页面嵌套导航。
核心特点：

• 自带标题栏、导航栏、返回按钮等UI能力
• 路由配置在 route_map.json 组件路由表
• 拥有独立局部页面栈，和全局Router栈相互隔离
• 适合单页面内多子页面嵌套、局部模块导航（个人中心、详情多层跳转）

二、Router 系统路由完整实战示例

Router 是项目中最常用的全局跳转方案，下面演示页面注册、跳转、传参、页面返回、替换页面全流程。

1. 页面注册配置（必做）

所有通过 Router 跳转的页面，必须在src/main/resources/base/profile/main_page.json 中注册：

{ "src": [ "pages/Index", "pages/SecondPage" ] }

2. 基础跳转与参数传递

Router 核心两大跳转模式：

• pushUrl：压栈跳转，保留当前页面，可返回
• replaceUrl：替换当前页面，销毁原页面，无法返回

首页 Index.ets 跳转代码：

import router from '@ohos.router' @Entry @Component struct Index { build() { Column() { // 普通压栈跳转 + 传参 Button("Router跳转二级页面") .margin(20) .onClick(() => { router.pushUrl({ url: "pages/SecondPage", params: { title: "鸿蒙Router实战", id: 1001 } }) }) // 替换页面跳转 Button("Router替换当前页面") .margin(20) .onClick(() => { router.replaceUrl({ url: "pages/SecondPage", params: { title: "替换页面跳转" } }) }) } .width('100%') .height('100%') .justifyContent(FlexAlign.Center) } }

3. 目标页面接收参数 + 页面返回

SecondPage.ets 接收参数、返回上一页、弹窗确认返回：

import router from '@ohos.router' @Entry @Component struct SecondPage { @State pageTitle: string = "" @State pageId: number = 0 // 页面加载获取参数 aboutToAppear() { const params = router.getParams() as Record<string, string | number> this.pageTitle = params.title as string || "默认标题" this.pageId = params.id as number || 0 } build() { Column({ space: 20 }) { Text(`页面标题：${this.pageTitle}`).fontSize(18) Text(`页面ID：${this.pageId}`).fontSize(18) // 普通返回上一页 Button("返回上一页").onClick(() => { router.back() }) // 带弹窗确认返回 Button("弹窗确认返回").onClick(() => { router.showAlertBeforeBackPage({ message: "确定要返回上一页吗？" }) }) // 返回到指定页面 Button("返回首页").onClick(() => { router.backToIndex() }) } .width('100%') .height('100%') .justifyContent(FlexAlign.Center) } }

三、Navigation 组件导航完整实战示例

Navigation 主打局部嵌套导航，依靠 NavPathStack 管理路由栈，需要单独配置组件路由表，自带标题栏、返回交互，适配单页面多子模块场景。

1. 配置组件路由表

在 src/main/resources/base/profile/ 新建 route_map.json，注册 Navigation 子页面：

{ "routerMap": [ { "name": "NavSecondPage", "pageSourceFile": "src/main/ets/pages/NavSecondPage.ets", "buildFunction": "NavSecondPageBuilder" } ] }

2. 封装子页面 @Builder

新建 NavSecondPage.ets，通过 @Builder 暴露页面构造方法，供 Navigation 调用：

@Builder export function NavSecondPageBuilder(params: Record<string, string>) { NavSecondPage({ pageParams: params }) } @Component export struct NavSecondPage { @Param pageParams: Record<string, string> build() { Column({ space: 20 }) { Text("Navigation 嵌套子页面").fontSize(20).fontWeight(FontWeight.Bold) Text(`接收参数：${this.pageParams.desc}`).fontSize(16) } .width('100%') .height('100%') .justifyContent(FlexAlign.Center) } }

3. Navigation 主页面跳转逻辑

通过 NavPathStack 实现页面压栈、传参、返回，自带导航栏：

import { NavPathStack } from '@ohos.arkui.advanced.Navigation' @Entry @Component struct NavIndexPage { // 初始化导航栈 pathStack: NavPathStack = new NavPathStack() build() { // 绑定导航栈 Navigation(this.pathStack) { Column() { Button("Navigation跳转子页面") .margin(20) .onClick(() => { // 压栈跳转并传参 this.pathStack.pushPathByName("NavSecondPage", { desc: "Navigation组件导航传参测试" }) }) } .width('100%') .height('100%') .justifyContent(FlexAlign.Center) } // 开启自带标题栏 .title("Navigation主页面") .titleBarMode(NavigationTitleBarMode.FIXED) } }

四、Router 与 Navigation 混合使用实战

实际项目中经常需要全局Router + 局部Navigation混用，核心规则：两者路由栈相互独立、互不干扰。
典型场景：全局Router跳转到模块页面，模块页面内部通过Navigation实现多层子页面跳转。

混合跳转流程

首页（Router全局）→ 模块页（Navigation容器）→ 多层子页面（Navigation局部跳转）
该场景无需特殊适配，Router管理全局大页面，Navigation管控页面内部局部子页面，栈隔离不会冲突，是鸿蒙项目最主流的导航架构。

五、Router与Navigation核心差异对比表

对比维度	Router 系统路由	Navigation 组件导航
本质	纯逻辑路由API，无UI	带UI的导航容器组件
配置文件	main_page.json	route_map.json
路由栈	全局唯一页面栈	局部独立页面栈
适用场景	应用全局跨页面跳转	单页面内嵌套子页面导航
自带UI	无，需自定义导航栏	自带标题栏、返回按钮
返回方式	router.back()	pathStack.pop()

六、开发避坑要点（高频问题）

• 页面注册报错：Router页面必须注册在 main_page.json，Navigation页面必须配置 route_map.json，否则跳转失效
• 参数获取为空：Router参数在 aboutToAppear 生命周期获取，不要在 build 中直接获取
• 导航栈混乱：禁止多层Navigation嵌套，每个页面仅保留一个Navigation容器，避免多栈冲突
• 页面无法返回：replaceUrl 会销毁原页面，如需保留返回栈，必须使用 pushUrl
• Navigation无标题栏：需手动开启 titleBarMode，默认可能隐藏

七、总结与选型建议

1.优先用Router：应用全局页面跳转、跨模块页面切换、首页/列表/详情等独立页面场景；
2. 优先用Navigation：单页面多层嵌套、局部模块内部导航、需要自带导航栏UI、精细化管控局部页面栈场景；
3. 最佳实践：全局Router做页面分发，局部Navigation做嵌套导航，两者结合搭建完整应用路由体系，兼顾简洁性与灵活性。

拓展学习

后续可基于本文示例拓展：导航动画自定义、页面栈清空、路由拦截、登录权限跳转、Navigation沉浸式导航栏等进阶功能。下面补充项目必备进阶实操案例，补齐生产开发核心能力。

八、鸿蒙导航进阶实战（生产必备）

1. Router 进阶：清空页面栈跳转（登录页跳转首页）

开发登录场景高频需求：登录成功跳转到首页，并清空所有页面栈，禁止返回登录页。Router 提供 clear: true 参数实现一键清栈。

import router from '@ohos.router' // 登录成功跳转首页，清空全部页面栈 router.pushUrl({ url: "pages/Index", clear: true // 清空历史页面栈 })

2. Router 跳转异常捕获（容错处理）

线上项目必须加异常捕获，避免页面未注册、路径错误导致应用崩溃。

import router from '@ohos.router' // 带异常捕获的安全跳转 async function safeJumpPage() { try { await router.pushUrl({ url: "pages/SecondPage", params: { name: "异常容错跳转" } }) } catch (error) { console.error("页面跳转失败：", JSON.stringify(error)) } }

3. Navigation 进阶：页面栈清空 & 返回指定页面

Navigation 局部路由栈支持精准栈操作，可实现清栈、回退指定层级、返回根页面。

import { NavPathStack } from '@ohos.arkui.advanced.Navigation' @Entry @Component struct NavIndexPage { pathStack: NavPathStack = new NavPathStack() build() { Navigation(this.pathStack) { Column({ space: 15 }) { // 跳转子页面 Button("跳转嵌套页面").onClick(() => { this.pathStack.pushPathByName("NavSecondPage", {}) }) // 返回上一级 Button("返回上一页").onClick(() => { this.pathStack.pop() }) // 直接返回Navigation根页面，清空所有子栈 Button("返回根页面").onClick(() => { this.pathStack.clear() }) } } .title("Navigation进阶操作") .titleBarMode(NavigationTitleBarMode.FIXED) } }

4. Navigation 沉浸式导航栏适配

默认导航栏为白底黑字，鸿蒙主流项目均采用沉浸式状态栏，适配全屏视觉效果。

Navigation(this.pathStack) { // 页面内容 } .title("沉浸式导航页面") .titleBarMode(NavigationTitleBarMode.FIXED) // 开启沉浸式适配 .ignoreSafeArea([SafeAreaType.SYSTEM, SafeAreaType.CUTOUT])

5. 路由权限拦截实战（登录校验）

核心业务场景：未登录用户禁止进入个人中心、订单页面，实现全局权限拦截逻辑。

import router from '@ohos.router' // 全局路由权限拦截工具 export function checkLoginAndJump(pageUrl: string, params?: Object) { // 模拟登录态，项目中替换为全局状态/本地存储 const isLogin: boolean = false if (isLogin) { // 已登录，正常跳转 router.pushUrl({ url: pageUrl, params }) } else { // 未登录，跳转登录页 router.pushUrl({ url: "pages/LoginPage", params: { redirectUrl: pageUrl } // 登录后回跳原页面 }) } } // 业务页面调用 // checkLoginAndJump("pages/UserCenter")

九、Router与Navigation 核心使用规范总结

1. 强制使用 Router 的场景

• 应用首页、登录页、注册页、设置页等独立顶层页面跳转
• 需要清空页面栈、全局页面替换、返回首页的场景
• 跨业务模块、跨功能页面的全局跳转

2. 强制使用 Navigation 的场景

• 个人中心、详情页、商城模块等单页面多层嵌套场景
• 需要自带导航栏、返回按钮、标题栏的页面模块
• 需要独立局部路由栈，不影响全局页面栈的场景

3. 禁止操作规范

• 禁止混用栈操作：Router 栈操作不影响 Navigation 局部栈，切勿交叉管控
• 禁止多层嵌套 Navigation：会导致栈错乱、返回失效、页面重叠
• 所有线上跳转必须增加异常捕获，规避路径错误、未注册页面报错

本文配套模板、静态源码可前往艾立兹素材库alisucai.com下载