首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >鸿蒙的 Navigation 和 router 该怎么分工

鸿蒙的 Navigation 和 router 该怎么分工

原创
作者头像
权哥说IT
发布于 2026-11-17 14:28:31
发布于 2026-11-17 14:28:31
10
举报

最典型的乱用,是在一个已经用了 Navigation 的工程里,某个二级页面又写了 router.pushUrl。结果两种返回行为混在一起,物理返回键有时回到上一个页面,有时直接退出应用。

这两个东西不是新旧关系,是两种页面组织模型。router 是页面对页面,Navigation 是容器对内容。搞混这一点,后面所有问题都是连锁的。

这篇按三块讲:先看两套模型的本质差别,再给「什么时候必须用哪个」的判断线,最后说三个混用之后才会出现的问题。

一、两套模型的本质:谁是「一堆页面的管理者」

router 的思路很简单:全局有一个页面栈,pushUrl 往里压一个页面,back 弹出去。它的管理权在一个全局对象上。

Navigation 的思路不一样:它本身是个组件,你把它放进页面里,它内部自己维护一个路由栈。管理权在这个组件实例上。

这个区别带来的第一个后果是栈的归属。

用 router 的时候,整个应用只有一个页面栈,getLength() 拿到的是全局深度。用 Navigation 的时候,如果你在一个页面里嵌了一个 Navigation,那个 Navigation 内部有自己的栈——而且可以有多个 Navigation 并存,各自管自己的栈。

这不是设计缺陷,是刻意为之。分栏布局(左边列表、右边详情)就是靠这个做的:左边一个 Navigation,右边一个 Navigation,互不干扰。router 做不了这件事,因为它只有一个栈。

二、判断线:什么情况必须用哪个

不给模糊建议,直接给判断条件。

必须用 Navigation 的四种情况

场景

为什么 router 不行

分栏布局(平板、折叠屏)

需要两个独立的栈,router 只有一个

需要系统级转场能力

Navigation 支持 navDestination 转场配置与系统级转场动画;router 的页面转场要靠每页单独写 pageTransition(),且官方已标注不推荐(转场能力以 Navigation 为主)

单页面内多视图切换

Navigation 可以把内容当子组件换,不涉及页面级跳转

需要拿到路由栈做深层控制

Navigation 的 NavPathStack 能直接查询和操作,API 更完整

可以用 router 的情况

只有一个:整个应用是简单的单栈线性流程,首页 → 列表 → 详情 → 设置,没有分栏、没有自定义动画、不需要多栈。

这种情况其实很少。只要应用要上平板,或者要做有点设计感的转场,就会撞到 router 的天花板。

所以更实际的说法是:新工程默认用 Navigation,router 只用在维护老代码时。

三、最小可用写法

先看 Navigation 的最小骨架,很多人卡在第一步是因为不知道 NavPathStack 怎么和页面绑起来。

代码语言:typescript
复制
@Entry
@Component
struct Index {
 // 1. 声明栈,这是整个路由的控制中心
 @Provide('pathStack') pathStack: NavPathStack = new NavPathStack();

 // 2. 页面构建器,按名字返回对应组件
 @Builder
 pageMap(name: string) {
 if (name === 'detail') {
 DetailPage();
 } else if (name === 'setting') {
 SettingPage();
 }
 }

 build() {
 Navigation(this.pathStack) {
 // 这里是「首页」的内容,Navigation 的直接子内容就是根页面
 Column() {
 Button('去详情')
 .onClick(() => {
 this.pathStack.pushPathByName('detail', { id: 1 });
 })
 }
 .width('100%')
 .height('100%')
 }
 .navDestination(this.pageMap) // 3. 挂上构建器
 .mode(NavigationMode.Stack) // 4. 单栏模式;分栏用 Split
 .title('首页')
 }
}

四个关键点,缺一个就跑不起来:

  1. NavPathStack 要用 @Provide 声明,这样子页面才能 @Consume 到同一个栈。
  2. pageMap 必须是 @Builder,普通方法不行。
  3. navDestination() 挂的是构建器引用,不是 pageMap() 的调用结果。
  4. mode 要显式写,不写时默认值在不同 API 版本上不一致。

子页面这边,必须用 NavDestination 包起来:

代码语言:typescript
复制
@Component
struct DetailPage {
 @Consume('pathStack') pathStack: NavPathStack;
 @State params: Record<string, Object> = {};

 build() {
 NavDestination() {
 Column() {
 Text(`收到的 id:${this.params.id}`)
 Button('返回')
 .onClick(() => this.pathStack.pop())
 }
 }
 .title('详情')
 .onReady((ctx: NavDestinationContext) => {
 // 参数在这里拿,不是构造函数里
 this.params = ctx.pathInfo.param as Record<string, Object>;
 })
 }
}

onReady 这一步是新手最容易漏的。参数不会自动出现在成员变量上,必须在 onReady 里从 pathInfo.param 取。

四、混用之后才会出现的三个问题

问题一:物理返回键行为不确定。

router 的 back() 和 Navigation 的 pop() 操作的是两个不同的栈。如果应用里两套都在用,物理返回键该走哪一套取决于当前页面属于哪个栈,用户体感就是「有时候返回上一页,有时候直接退出」。

这个问题很难在测试阶段发现,因为单页面测试都正常,只有走完整流程才露出来。

问题二:页面状态被重置。

问题二:页面状态被重置。

router.pushUrl 默认使用 RouterMode.Standard,每次跳转都创建新实例;返回时销毁栈顶页面。Navigation 的 pushPathByName 会保留栈内页面实例。

所以同一个「去详情再返回」的动作,两套写法下首页的 @State 一个被重置、一个被保留。如果你的首页有列表滚动位置或分页数据,这个差别非常明显。

问题三:aboutToAppear 的调用次数对不上。

Navigation 在 Stack 模式下,pushPathByName 会创建新实例;但在 Split 模式下,右侧内容替换时可能复用实例。这意味着 aboutToAppear 在某些场景只调一次、某些场景调多次。

依赖 aboutToAppear 做数据请求的页面,会在这两种模式下表现不一致。稳妥做法是把请求放进 onReady(NavDestination 才有),或者在请求前判断是否已有数据。

五、从 router 迁到 Navigation 的顺序

老工程要迁,别一把梭。按这个顺序,每一步都能独立验证:

第一步,加一个 Navigation 容器,但不改任何现有跳转。 让 Navigation 只作为根容器存在,内部还是用 router 跳。这一步验证的是「加容器有没有破坏现有布局」。

第二步,把最外层的三到五个页面换成 pushPathByName。 选那些没有复杂返回逻辑的页面。验证物理返回键行为。

第三步,逐个把 router.back() 换成 pathStack.pop()。 这一步必须和第二步同一个页面一起改,不能分开。

第四步,删掉 router 相关代码,检查有没有残留的 router.pushUrl。 用全局搜索确认,包括那些「暂时用不到」的分支。

第五步,处理参数传递。 router 的 params 是 URL 参数风格,Navigation 的 param 是任意对象。这一步要改所有接收参数的页面。

六、参数传递上的一个实际差别

router 传参走 URL:

代码语言:typescript
复制
router.pushUrl({ url: 'pages/Detail', params: { id: 1 } });

Navigation 传参走对象:

代码语言:typescript
复制
this.pathStack.pushPathByName('detail', { id: 1 });

看起来差不多,但有个关键差别:router 的 params 在页面重建后会丢,Navigation 的 param 存在 pathInfo 里,页面重建后还能拿到。

这个差别在做「返回后刷新」时很实用。用 router 你得自己存一份参数,用 Navigation 不需要。

另一个差别是类型。router 的 params 是 Object,取出来要 as。Navigation 的 pushPathByName 支持泛型,可以约定类型:

代码语言:typescript
复制
this.pathStack.pushPathByName<DetailParam>('detail', { id: 1, from: 'list' });

然后在子页面 onReady 里拿到的是 DetailParam 类型,不用手动 as。这一点在页面多了以后收益很明显。

七、自学容易卡在哪

卡点一:pageMap 写了但页面出不来。 九成是因为 navDestination() 写成了 navDestination(this.pageMap())——多了括号,传的是调用结果而不是引用。

卡点二:@Consume 拿不到栈。 检查 @Provide 的 key 和 @Consume 的 key 是否完全一致,包括引号。不同层级的组件之间要能对上,中间隔了几层也可以。

卡点三:mode 不写,平板和手机上表现不一样。 NavigationMode.Stack 是单栏,Split 是分栏。不写时默认可能是 Auto,它会根据屏幕宽度自动选,这在真机上和模拟器上结果可能不同。

卡点四:NavDestination 忘了包。 子页面直接写 Column 也行,但那样 title、转场动画、onReady 这些能力都没了,等于白用 Navigation。

卡点五:以为 pop() 能传参回去。 pop 的入参是 popResult,但接收方要在 pushPathByName 的返回值 .then() 里拿,这个链式写法不熟的话容易漏。

路由这一块的选择,一旦定下来后面很难改,因为涉及所有页面的跳转写法。新建工程时先想清楚要不要上平板、要不要自定义转场,答案是要,就直接上 Navigation,别先用 router 后迁。这类「选型决定后面所有写法」的内容,成体系的课程一般会在项目起步阶段就把两套模型讲清,避免学员写完二十个页面再回头重构。如果你不确定该用哪套,也可以拿这篇的判断表去对照,或者看看誉天教育的鸿蒙课里架构那部分怎么排这个顺序。

栈的归属定对了,后面写路由就是在填空,不用每次都想「该用哪个」。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 一、两套模型的本质:谁是「一堆页面的管理者」
  • 二、判断线:什么情况必须用哪个
  • 三、最小可用写法
  • 四、混用之后才会出现的三个问题
  • 五、从 router 迁到 Navigation 的顺序
  • 六、参数传递上的一个实际差别
  • 七、自学容易卡在哪
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档