页面导航与路由:Navigation、路由与参数
本篇要点:能用一个
NavPathStack管住整棵页面的进出,把返回值、拦截、深层链接三条链路都跑通,并说清宽屏下单栏与分栏是怎么切换的。 前置:《状态管理:@State 家族与 V2 状态管理》解决了"状态放哪、往哪个方向流",这一章的页面栈本身也是一个状态,而且是最容易被多写一份的状态。
为什么需要它
详情页加一个"收藏",半小时能写完。让这个页面返工的是另一件事:同一份代码要同时跑手机和平板,平板要求左边列表、右边详情,两栏同时可见。
2026 年 7 月,一个做二手交易的团队就卡在这里。他们用 router.pushUrl 进详情,页面是 @Entry 组件,一次只显示一屏;为了做出两栏,只能用 Row 拼一个列表加一个详情,再拿 @State 手动同步"当前选中哪一条"。拼到第三版,返回栈和选中态开始互相打架:从详情按返回,列表的选中项还停在旧记录上。
router 做不到这件事,不是用法没找对。官方能力对照表里,"一次开发多端部署"这一行,Navigation 支持、Router 不支持;"路由拦截""获取页面栈对象""清理指定路由"同样是不支持。@ohos.router 的标题后面也跟着"(不推荐)",router.pushUrl 从 API 18 起标为废弃。
这一章讲 Navigation 这条路:栈怎么建、参数怎么传、返回值怎么接、没登录怎么拦、外部链接怎么进来,以及 600vp 那条分栏线。版本以截至 2026 年 11 月的 HarmonyOS 6.0.0(API 20)为准,超出这个基线的接口会单独标注。
核心概念
三个对象:容器、栈、页面
定义:Navigation 是容器组件,负责标题栏、内容区、工具栏;NavPathStack 是页面栈,所有进出操作都在它上面;NavDestination 是栈里的一页。
类比:Navigation 是相框,NavPathStack 是一叠照片的顺序,NavDestination 是照片本身。相框只有一个,顺序只有一份,照片可以换。
这里有一条最常见的错误:每个页面自己 new NavPathStack()。栈不是全局对象,它是构造 Navigation 时传进去的那一个实例;子页面要么从 onReady 的 NavDestinationContext 里取 ctx.pathStack,要么在根页面 aboutToAppear 时存进 AppStorage。自己 new 出来的那份是空栈,push 出去什么也不会发生,也不报错。
页面本身要靠路由表登记,否则 pushPathByName('detail') 找不到对应的构建函数。路由表是一个 JSON 文件,放在 resources/base/profile/ 下,逐条写 name、pageSourceFile、buildFunction 三个字段,再在 module.json5 里用 routerMap 指向它。
参数与返回值:两条方向不同的边
下行靠 pushPathByName(name, param),参数挂在 NavPathInfo 上,页面在 onReady 里用 ctx.pathInfo.param 取,或者事后用 getParamByName(name) 从栈上查。
上行有两条路。一是 pushPathByName 的第三个参数 onPop 回调,出栈时触发,拿得到 PopInfo.result。二是 NavDestination.onResult()(API 15 起),在页面组件内接收回传值。
如图 4-1 所示,一次带返回值的跳转在栈上留下三段痕迹:入栈时多一项,出栈时少一项,onPop 在出栈后触发。
图 4-1 一次携带返回值的跳转
有一个时序细节值得单独记:无论哪个拦截回调,进入时栈都已经变了。所以在 willShow 里想"阻止跳转",做法不是返回 false(没有这个返回值),而是把刚压进去的那一项 pop() 掉,再 push 到你真正想去的页面。
栈上的操作就那么几类,按语义记比按名字记牢。
| 操作 | 方法 | 语义 | 注意 |
|---|---|---|---|
| 入栈 | pushPathByName | 压入一页 | 参数随页面走,页面出栈后即丢 |
| 带错误码入栈 | pushDestinationByName | 压入并返回 Promise | 目标页不存在时能 catch 到,普通入栈只会静默失败 |
| 替换栈顶 | replacePathByName | 当前页换成另一页 | 适合"登录成功后换主页",不留返回入口 |
| 出栈 | pop(result) | 弹出一页并回传结果 | onPop 在出栈之后触发 |
| 回退到指定页 | popToName / popToIndex | 一次弹掉多层 | 适合"提交后直接回列表" |
| 清栈 | clear() | 清空整个栈 | 退出登录时用,记得同时清掉登录态 |
| 查询 | getParamByName / getAllPathName / getIndexByName | 读栈 | getParamByName 返回数组,可能为空 |
replacePathByName 值得单独说一句。登录成功后把登录页换成主页,返回键就不会退回登录页;用 push 也能到主页,但登录页还留在栈里,返回键一按就回去了。
路由拦截:先跳再纠正
定义:setInterception()(API 12 起)给 NavPathStack 挂一个拦截对象,常用的回调是 willShow(页面跳转前,允许操作栈)和 didShow(跳转后)。
它的语义不是"拦住不让走",而是"走完了再纠正"。代价是被拦的那个页面会被创建一次再销毁,视觉上会闪一下。文档里 API 22 起给这个对象加了 interception 回调,触发时机早于 willShow,被拦的页面根本不会创建——如果你的 SDK 还没到 22,就接受那一闪。
权限校验、登录态校验、灰度开关都适合放这里,因为它们要拦的是"所有进入某个页面的路径",而不是某个按钮。
深层链接:从外部进到某一页
定义:Deep Linking 是让外部(浏览器、扫码、另一个应用、hdc 命令)用一个 URI 把应用拉到指定页面的机制,走的是隐式 Want 的 uri 匹配。
三处配置最容易漏。skills 下必须新建一个独立的 skill 对象,不能写进标识应用入口的那个默认对象里,写进去不生效。actions 不能为空,通常写 ohos.want.action.viewData。scheme 可以自定义,但不能以 ohos 开头,也不建议用 http、https、file,那几个是系统保留的。
参数从 want.uri 里取,onCreate 和 onNewWant 两个生命周期都要处理:冷启动走前者,应用已在后台时走后者。少写一个,现象是"第一次能跳,第二次没反应"。
多设备形态:600vp 这条线
Navigation 的 mode 有三个值:Stack 单栏、Split 分栏、Auto 自适应。Auto 的判定线是宽度 600vp:大于等于 600vp 走分栏,小于走单栏。这个 600 不是拍出来的,它等于 minNavBarWidth(240vp) 加 minContentWidth(360vp)。API 9 及之前这条线是 520vp,从 API 10 起改成 600vp。
API 24 又加了一个 AUTO_WITH_ASPECT_RATIO(本篇基线的 API 20 上还取不到这个值):宽度够 600vp、且高宽比不大于 1.2 才分栏,否则单栏。折叠屏展开后接近方形,用它比 Auto 稳。
配套还有 navBarWidth、navBarWidthRange(可拖动范围)、enableDragBar(API 14 起,是否显示拖动条)。分栏时导航栏常驻,右侧内容区随 NavPathStack 切换;单栏时导航栏就是首页,压入子页面后整屏被 NavDestination 占满。
还有一处和形态无关、但常被漏掉的:NavDestination 支持 onBackPressed(),返回 true 表示这次返回键由页面自己处理。表单页有未保存内容时,用它弹一个确认框;方向写反的代价是用户按返回键时页面直接出栈,输入内容一起没了。
要注意的是形态切换不会清栈。折叠屏合上时页面还在栈里,展开后同一份栈变成两栏显示,modeChange 回调会通知你。所以别在 onReady 里假设"我现在一定是单栏",也别把宽度相关的计算写死在页面里。
动手实践
四步,从建栈到从外部拉起来。
第一步,注册路由表。建 entry/src/main/resources/base/profile/router_map.json,并在 module.json5 的 module 字段里加一行指向它。
// entry/src/main/resources/base/profile/router_map.json
{
"routerMap": [
{
"name": "detail",
"pageSourceFile": "src/main/ets/pages/DetailPage.ets",
"buildFunction": "DetailBuilder"
}
]
}
// entry/src/main/module.json5 的 module 字段内
// "routerMap": "$profile:router_map"运行结果:重新编译后不报错;把 routerMap 那行注释掉再编译,pushPathByName('detail') 会失败,日志里出现找不到页面的错误——这一步是为了让你确认注册确实生效,而不是碰巧能跑。
第二步,列表页入栈并接返回值。
class DetailParam {
id: string = '';
}
class FavorResult {
id: string = '';
favorited: boolean = false;
}
@Entry
@Component
struct BillList {
stack: NavPathStack = new NavPathStack();
@State favoritedId: string = '';
build() {
Navigation(this.stack) {
List() {
ListItem() {
Row({ space: 8 }) {
Text('B-1 午餐')
Text(this.favoritedId === 'B-1' ? '★' : '☆')
}
.onClick(() => {
const p = new DetailParam();
p.id = 'B-1';
this.stack.pushPathByName('detail', p, (info: PopInfo) => {
const r = info.result as FavorResult;
console.info(`pop from ${info.info.name}, favorited=${r.favorited}`);
if (r.favorited) {
this.favoritedId = r.id;
}
});
})
}
}
}
.title('账单')
.mode(NavigationMode.Auto)
}
}运行结果:点列表项进入详情;在详情页点收藏再返回,控制台打印 pop from detail, favorited=true,列表那颗星从 ☆ 变成 ★。
第三步,详情页出栈时带回结果。
class DetailParam {
id: string = '';
}
class FavorResult {
id: string = '';
favorited: boolean = false;
}
@Builder
export function DetailBuilder(name: string, param: Object) {
DetailPage({ param: param as DetailParam });
}
@Component
export struct DetailPage {
param: DetailParam = new DetailParam();
stack: NavPathStack = new NavPathStack();
build() {
NavDestination() {
Button('收藏并返回').onClick(() => {
const r = new FavorResult();
r.id = this.param.id;
r.favorited = true;
this.stack.pop(r);
})
}
.title(`详情 ${this.param.id}`)
.onReady((ctx: NavDestinationContext) => {
// 子页面拿栈只能从这里取,或者从 AppStorage 取存好的那一份
this.stack = ctx.pathStack;
})
}
}运行结果:标题显示"详情 B-1";点按钮后页面出栈,回到列表并触发 onPop。把 onReady 里那行赋值删掉试一次——点按钮没反应,因为 this.stack 是自己 new 的空栈。
第四步,拦截与外部拉起。拦截写在根页面的 aboutToAppear:
aboutToAppear(): void {
this.stack.setInterception({
willShow: (from: NavDestinationContext | 'navBar', to: NavDestinationContext | 'navBar',
operation: NavigationOperation, animated: boolean) => {
if (typeof to === 'string') {
return; // 目标是 Navigation 首页,不拦
}
const target = to as NavDestinationContext;
if (target.pathInfo.name === 'detail' && !AppStorage.get<boolean>('loggedIn')) {
target.pathStack.pop(); // 栈已经变了,先退掉刚压进去的
target.pathStack.pushPathByName('login', null);
console.info('intercepted: redirect to login');
}
}
});
}运行结果:未登录时点列表项,页面直接落在登录页,控制台打印 intercepted: redirect to login,栈里没有留下 detail;把 AppStorage 里的 loggedIn 置为 true 再点,正常进详情。login 页同样要先在路由表里登记一条,否则重定向会静默失败。
外部拉起要先配 skills:
// entry/src/main/module.json5,abilities 下新增一个独立 skill 对象
{
"actions": ["ohos.want.action.viewData"],
"uris": [{ "scheme": "shopapp", "host": "detail" }]
}运行结果:重新打包后,scheme 为 shopapp、host 为 detail 的 URI 能匹配到这个 Ability;把这段写进默认 skill 对象则始终匹配不上,而且没有任何报错。
# 设备已连接,应用已安装
$ hdc shell "aa start -A ohos.want.action.viewData -U 'shopapp://detail?id=42'"运行结果:应用被拉起并进入详情页;EntryAbility 里用 url.URL.parseURL(want.uri).params.get('id') 读到 42。命令返回 start ability successfully.。
常见误解
"willShow 里 return false 能拦住跳转。" 这个回调没有返回值。进回调时栈已经变了,你能做的是把刚压进去的项 pop 掉再 push 到别处——"先跳再纠正"。
"router 和 Navigation 只是新旧两套写法。" router 的页面是 @Entry 组件,栈由系统管,拿不到栈对象;Navigation 的页面是 NavDestination,栈是你手上的对象,能查、能改、能拦。这个差别决定了"获取指定页面参数"和"路由拦截"这两件事在 router 上做不到。
"深层链接配了 uris 就能跳。" 还有三处会挡住:写进了默认的 skill 对象、actions 留空、scheme 用了保留值。三者都不报错,只是匹配不上。
"分栏是另一套页面。" 分栏只是把同一个栈渲染成两栏,栈内容一模一样。折叠屏合并展开时页面不会重建,onReady 也不会再跑一次。
小结
- 一个
Navigation配一个NavPathStack;子页面的栈从onReady的ctx.pathStack取,自己 new 出来的那份是空栈。 - 下行用
pushPathByName传参,上行用onPop或onResult接result;getParams()拿不到回传值。 - 拦截语义是"先跳再纠正":
willShow里先pop再push,被拦页面会闪一下;API 22 起才有创建前拦截的回调。 - 深层链接要独立 skill 对象、非空
actions、非保留scheme,onCreate与onNewWant都要处理。 - 600vp 是
Auto的分栏线,等于 240 加 360;形态切换不重建页面、不清栈。
相关主题
页面能进能出之后,接下来要回答"数据从哪来"。《网络与数据:HTTP、数据持久化与首选项》讲 网络与数据:HTTP、数据持久化与首选项,把请求、JSON 解析、关系型数据库和首选项串成一层。本篇的 DetailParam 到了那一章会变成接口返回值,类型对不上的问题会以另一种方式回来。