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

‌HarmonyOS Next导航与路由开发指南

---

一、路由系统核心机制

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

路由栈管理 → 页面生命周期控制 → 动画过渡 → 参数解析

‌核心特性‌：

• ‌多实例模式‌：支持Standard（默认）和Single（单例）两种页面实例模式
• ‌路由守卫‌：全局拦截跳转动作实现权限控制
• ‌动画编排‌：支持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('页面离开');  
}