
第五课: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('页面离开');
}
