最典型的乱用,是在一个已经用了 Navigation 的工程里,某个二级页面又写了 router.pushUrl。结果两种返回行为混在一起,物理返回键有时回到上一个页面,有时直接退出应用。
这两个东西不是新旧关系,是两种页面组织模型。router 是页面对页面,Navigation 是容器对内容。搞混这一点,后面所有问题都是连锁的。
这篇按三块讲:先看两套模型的本质差别,再给「什么时候必须用哪个」的判断线,最后说三个混用之后才会出现的问题。
router 的思路很简单:全局有一个页面栈,pushUrl 往里压一个页面,back 弹出去。它的管理权在一个全局对象上。
Navigation 的思路不一样:它本身是个组件,你把它放进页面里,它内部自己维护一个路由栈。管理权在这个组件实例上。
这个区别带来的第一个后果是栈的归属。
用 router 的时候,整个应用只有一个页面栈,getLength() 拿到的是全局深度。用 Navigation 的时候,如果你在一个页面里嵌了一个 Navigation,那个 Navigation 内部有自己的栈——而且可以有多个 Navigation 并存,各自管自己的栈。
这不是设计缺陷,是刻意为之。分栏布局(左边列表、右边详情)就是靠这个做的:左边一个 Navigation,右边一个 Navigation,互不干扰。router 做不了这件事,因为它只有一个栈。
不给模糊建议,直接给判断条件。
必须用 Navigation 的四种情况
场景 | 为什么 router 不行 |
|---|---|
分栏布局(平板、折叠屏) | 需要两个独立的栈,router 只有一个 |
需要系统级转场能力 |
|
单页面内多视图切换 |
|
需要拿到路由栈做深层控制 |
|
可以用 router 的情况
只有一个:整个应用是简单的单栈线性流程,首页 → 列表 → 详情 → 设置,没有分栏、没有自定义动画、不需要多栈。
这种情况其实很少。只要应用要上平板,或者要做有点设计感的转场,就会撞到 router 的天花板。
所以更实际的说法是:新工程默认用 Navigation,router 只用在维护老代码时。
先看 Navigation 的最小骨架,很多人卡在第一步是因为不知道 NavPathStack 怎么和页面绑起来。
@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('首页')
}
}四个关键点,缺一个就跑不起来:
NavPathStack 要用 @Provide 声明,这样子页面才能 @Consume 到同一个栈。pageMap 必须是 @Builder,普通方法不行。navDestination() 挂的是构建器引用,不是 pageMap() 的调用结果。mode 要显式写,不写时默认值在不同 API 版本上不一致。子页面这边,必须用 NavDestination 包起来:
@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 才有),或者在请求前判断是否已有数据。
老工程要迁,别一把梭。按这个顺序,每一步都能独立验证:
第一步,加一个 Navigation 容器,但不改任何现有跳转。 让 Navigation 只作为根容器存在,内部还是用 router 跳。这一步验证的是「加容器有没有破坏现有布局」。
第二步,把最外层的三到五个页面换成 pushPathByName。 选那些没有复杂返回逻辑的页面。验证物理返回键行为。
第三步,逐个把 router.back() 换成 pathStack.pop()。 这一步必须和第二步同一个页面一起改,不能分开。
第四步,删掉 router 相关代码,检查有没有残留的 router.pushUrl。 用全局搜索确认,包括那些「暂时用不到」的分支。
第五步,处理参数传递。 router 的 params 是 URL 参数风格,Navigation 的 param 是任意对象。这一步要改所有接收参数的页面。
router 传参走 URL:
router.pushUrl({ url: 'pages/Detail', params: { id: 1 } });Navigation 传参走对象:
this.pathStack.pushPathByName('detail', { id: 1 });看起来差不多,但有个关键差别:router 的 params 在页面重建后会丢,Navigation 的 param 存在 pathInfo 里,页面重建后还能拿到。
这个差别在做「返回后刷新」时很实用。用 router 你得自己存一份参数,用 Navigation 不需要。
另一个差别是类型。router 的 params 是 Object,取出来要 as。Navigation 的 pushPathByName 支持泛型,可以约定类型:
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 删除。