鸿蒙应用页面路由实战:Navigation 与 Router 选型及页面传参避坑

举报
yd_295436472 发表于 2026/11/13 10:47:32 2026/11/13
【摘要】 鸿蒙应用页面路由实战:Navigation 与 Router 选型及页面传参避坑页面跳转是每个鸿蒙应用都绕不开的基础能力,但 ArkTS 里 Router 和 Navigation 两套路由 API 常常让人纠结:新页面到底用哪个跳?参数怎么传才不会丢?返回时数据怎么带回去?本文结合实际开发经验,把选型、传参和几个常见坑一次讲清。 一、两套路由 API 的定位Router 是鸿蒙最早提供的...

鸿蒙应用页面路由实战:Navigation 与 Router 选型及页面传参避坑

页面跳转是每个鸿蒙应用都绕不开的基础能力,但 ArkTS 里 Router 和 Navigation 两套路由 API 常常让人纠结:新页面到底用哪个跳?参数怎么传才不会丢?返回时数据怎么带回去?本文结合实际开发经验,把选型、传参和几个常见坑一次讲清。

一、两套路由 API 的定位

Router 是鸿蒙最早提供的页面路由能力,基于页面栈管理,API 简单直接,适合页面层级不深、跳转关系简单的应用。Navigation 是后来推出的新一代导航组件,基于 NavPathStack 管理,支持路由表、页面间共享转场动画、分栏布局,适合页面层级多、需要嵌套导航的中大型应用。

官方的演进方向很明确:新项目优先用 Navigation,老项目用 Router 也完全没问题,不用为了追新而重构。但一个应用里不要两套混用——混用会让返回栈变得不可预测,出现“按返回键回到意料之外的页面”的问题。

二、Router:简单直接,适合轻量应用

Router 的用法非常直观,跳转、返回、替换各一个 API:

import { router } from '@kit.ArkUI';

// 跳转到详情页并传参
router.pushUrl({
  url: 'pages/DetailPage',
  params: { itemId: '1001', from: 'home' }
});

// 返回上一页
router.back();

// 替换当前页(登录成功后跳首页,不希望用户返回登录页时用)
router.replaceUrl({ url: 'pages/HomePage' });

Router 的参数通过目标页面的 router.getParams() 读取。需要注意两点:第一,params 只能传基础类型和简单对象,不要传函数或带有循环引用的对象,序列化会失败;第二,页面被系统回收后重建时,params 可能丢失,关键 ID 建议同时用 AppStorage 或数据库做一份兜底。

三、Navigation:路由表 + NavPathStack,适合复杂应用

Navigation 的核心是 NavPathStack 和路由表。先在模块的 router_map.json 里注册页面,再通过 NavPathStack 做跳转:

// 路由表 router_map.json(节选)
{
  "routerMap": [
    { "name": "DetailPage", "pageSourceFile": "src/main/ets/pages/DetailPage.ets", "buildFunction": "DetailPageBuilder" },
    { "name": "SettingPage", "pageSourceFile": "src/main/ets/pages/SettingPage.ets", "buildFunction": "SettingPageBuilder" }
  ]
}
import { NavPathStack } from '@kit.ArkUI';

@Entry
@Component
struct MainPage {
  @Provide('pageStack') pageStack: NavPathStack = new NavPathStack();

  build() {
    Navigation(this.pageStack) {
      List() {
        ListItem() {
          Text('去详情页').onClick(() => {
            // pushPathByName 按路由表名字跳转,改名只改一处
            this.pageStack.pushPathByName('DetailPage', { itemId: '1001' });
          });
        }
      }
    }.title('首页')
  }
}

Navigation 相比 Router 的优势主要在三点:一是路由表集中管理页面,页面改名、改路径只改一处;二是 NavPathStack 可以跨组件共享,子组件也能触发跳转,不用层层回调;三是天然支持分栏(Navigation + NavDestination 的双栏布局),平板和折叠屏上体验更好。

四、页面传参的几种方式,怎么选

场景 推荐方式 说明
跳转时带少量参数 pushUrl / pushPathByName 的 params 最常用,简单直接
跨多级页面共享数据 @Provide/@Consume 或 AppStorage 避免一层层透传
返回时带回结果 Navigation 的 onPop 回调或事件通知 Router 没有原生回传机制
敏感或大量数据 先存数据库,页面间只传 ID 参数有大小限制,别塞大对象

Router 没有原生的“返回带结果”机制,常见做法有两种:一是跳转前把回调登记到一个单例的事件总线,详情页返回前发事件;二是详情页直接把结果写进 AppStorage 或数据库,上一页在 onPageShow 里读取。前者实时性好,后者更稳妥,关键结果建议用后者。

五、返回与拦截:最容易踩的坑

坑一:返回栈里混入了不该返回的页面。 登录页、启动页、支付成功页通常不希望用户按返回键回去。Router 用 replaceUrl 替换,Navigation 用 pageStack.clear() 后再 push,或者用 moveToTop 调整栈顶,都能避免。

坑二:连续快速点击导致重复跳转。 用户快速点两次列表项,可能压入两个相同的详情页。解决办法是在跳转入口加一把简单的节流锁:记录上次跳转时间,300 毫秒内重复点击直接忽略。

// 跳转节流:300 毫秒内重复点击只执行一次
let lastJumpTime = 0;
function jumpToDetail(itemId: string) {
  const now = Date.now();
  if (now - lastJumpTime < 300) {
    return;
  }
  lastJumpTime = now;
  router.pushUrl({ url: 'pages/DetailPage', params: { itemId } });
}

坑三:系统返回键和手势返回没拦截。 需要拦截返回做“表单未保存提醒”时,Router 可以在页面 onBackPress 里返回 true 拦截;Navigation 则监听 NavDestination 的 onBackPressed。拦截后记得弹确认框让用户选择“保存并离开”或“直接离开”,不要静默拦截,否则用户会觉得返回键坏了。

六、选型建议:按页面复杂度决定

  • 页面少于 10 个、跳转关系简单:Router 足够,代码量少、上手快。
  • 页面多、有多级嵌套、需要分栏或共享转场:选 Navigation,一次投入长期受益。
  • 已经用 Router 的老项目:不用重构,等有新模块或大改版时再逐步迁移。
  • 无论选哪个:跳转入口集中收敛到一个工具类,不要散落在各页面;参数只传 ID 和少量字段,大对象走存储;返回栈里的页面都要经过“是否允许返回”的检查。

结语

Router 和 Navigation 没有绝对的好坏,只有合不合适。小应用用 Router 更轻,大应用用 Navigation 更稳。真正的坑不在选哪个 API,而在传参方式不统一、返回栈没管好、重复点击没防住。先把跳转入口收敛、参数规则定好,页面导航这层地基就稳了,之后再叠加深链接、应用内跳转这些能力也会顺手得多。


【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。