鸿蒙应用页面路由实战:Navigation 与 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,而在传参方式不统一、返回栈没管好、重复点击没防住。先把跳转入口收敛、参数规则定好,页面导航这层地基就稳了,之后再叠加深链接、应用内跳转这些能力也会顺手得多。
- 点赞
- 收藏
- 关注作者
评论(0)