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

小_铁51CTO

发布于 2025-2-27 23:06

浏览

0收藏

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();
}
})