Skip to content

页面导航与路由: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 字段里加一行指向它。

json5
// 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') 会失败,日志里出现找不到页面的错误——这一步是为了让你确认注册确实生效,而不是碰巧能跑。

第二步,列表页入栈并接返回值。

arkts
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,列表那颗星从 ☆ 变成 ★。

第三步,详情页出栈时带回结果。

arkts
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:

arkts
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:

json5
// entry/src/main/module.json5,abilities 下新增一个独立 skill 对象
{
  "actions": ["ohos.want.action.viewData"],
  "uris": [{ "scheme": "shopapp", "host": "detail" }]
}

运行结果:重新打包后,scheme 为 shopapp、host 为 detail 的 URI 能匹配到这个 Ability;把这段写进默认 skill 对象则始终匹配不上,而且没有任何报错。

bash
# 设备已连接,应用已安装
$ 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 到了那一章会变成接口返回值,类型对不上的问题会以另一种方式回来。