第五课：‌HarmonyOS Next导航与路由开发指南

一、路由系统核心机制

HarmonyOS Next基于‌ArkUI 5.0路由引擎‌，采用分层管理架构：

路由栈管理 → 页面生命周期控制 → 动画过渡 → 参数解析 ‌核心特性‌：

1. ‌多实例模式‌：支持Standard（默认）和Single（单例）两种页面实例模式
2. ‌路由守卫‌：全局拦截跳转动作实现权限控制
3. ‌动画编排‌：支持15+种预置过渡动画，支持自定义动画

二、基础页面跳转方法

1. ‌普通跳转（router.pushUrl）‌

// 跳转到指定页面  
router.pushUrl({  
  url: 'pages/DetailPage',  
  params: { id: 123 }  
})  

// 接收参数  
@State params: Record<string, string> = router.getParams();  

‌路由模式对比‌： 模式 内存占用 适用场景 Standard 较高 常规多实例页面 Single 低 全局唯一页面

2. ‌返回操作（router.back）‌

// 跳转到指定页面  
router.pushUrl({  
  url: 'pages/DetailPage',  
  params: { id: 123 }  
})  

// 接收参数  
@State params: Record<string, string> = router.getParams();  

三、路由参数传递与接收

1. ‌URL参数传递‌

// 发送参数（自动编码）  
router.pushUrl({  
  url: `pages/DetailPage?id=${encodeURIComponent(123)}`  
})  

// 接收参数（自动解码）  
const id = decodeURIComponent(router.getParams()['id']);  

2. ‌对象参数传递‌

// 定义参数类型  
interface ProductParams {  
  id: number;  
  name: string;  
}  

// 发送结构化参数  
router.pushUrl({  
  url: 'pages/DetailPage',  
  params: {  
    product: JSON.stringify({ id: 1, name: '手机' })  
  }  
})  

// 接收并解析参数  
const product: ProductParams = JSON.parse(router.getParams()['product']);  

四、高级路由功能

1. ‌路由守卫（全局拦截）‌

// 全局前置守卫  
router.addBeforeHook((to, from, next) => {  
  if (to.url === 'pages/ProfilePage' && !isLogin) {  
    next({ url: 'pages/LoginPage' }) // 重定向  
  } else {  
    next() // 放行  
  }  
})  

2. ‌动态路由匹配‌

// 配置动态路径  
{  
  path: 'pages/UserPage/:userId',  
  name: 'UserPage'  
}  

// 跳转时传参  
router.pushUrl({  
  url: `pages/UserPage/${userId}`  
})  

// 获取动态参数  
const userId = router.getParams()['userId'];  

3. ‌自定义转场动画‌

router.pushUrl({  
  url: 'pages/DetailPage',  
  enterAnimation: {  
    duration: 500,  
    curve: Curve.EaseInOut,  
    type: RouteAnimation.SlideRight  
  }  
})  

五、实战案例：电商应用导航

1. ‌商品列表到详情页跳转‌
// 列表项点击事件  
onItemClick(productId: number) {  
  router.pushUrl({  
    url: 'pages/ProductDetailPage',  
    params: { id: productId }  
  })  
}  

// 详情页接收参数  
@Component  
struct ProductDetailPage {  
  @State productId: number = parseInt(router.getParams()['id']);  
}  

2. ‌登录状态路由守卫‌

router.addBeforeHook((to, from, next) => {  
  if (to.url.startsWith('pages/Order') && !checkAuth()) {  
    showToast('请先登录');  
    next({ url: 'pages/LoginPage' });  
  } else {  
    next();  
  }  
})  

六、常见问题与调试技巧 1. ‌参数传递失败排查‌ 1. 检查参数是否经过encodeURIComponent编码
2. 确认目标页面是否已注册路由路径
3. 使用DevEco路由调试器查看参数树

2. ‌页面生命周期管理‌ // 页面显示/隐藏监听
onPageShow() {
console.log('页面进入');
}

onPageHide() {
console.log('页面离开');
}