小白必看 HarmonyOS NEXT HMRouter 轻松上手秘籍

前言

HMRouter 作为 HarmonyOS 的页面跳转场景解决方案，聚焦解决应用内原生页面的跳转逻辑。

HMRouter 底层对系统 Navigation 进行封装，集成了 Navigation、NavDestination、NavPathStack 的系统能力，提供了可复用的路由拦截、页面生命周期、自定义转场动画，并且在跳转传参、额外的生命周期、服务型路由方面对系统能力进行了扩展。

目的是让开发者在开发过程中无需关注 Navigation、NavDestination 容器组件的相关细节及模板代码，屏蔽跳转时的判断逻辑，降低拦截器、自定义转场动画实现复杂度，更好的进行模块间解耦

对比

目前鸿蒙应用开发中，官方推出的路由方案有两个，分别是 Router 和 Navigation。目前官方主要推荐的也是 Navigation。

但是原生的 Navigation 缺少了路由拦截、页面生命周期、自定义转场动画，并且在跳转传参、额外的生命周期、服务型路由。

因此 HMRouter 便是对此做出了拓展和增强。

学习目标

接下来，将通过这篇文章带领小伙伴上手 HMRouter 的应用。

工程目录

新建完工程后，再新建一个 Cart 动态共享包模块

1. 工程的目录名称是 study

2. 入口模块是 entry

3. cart 是 hsp 模块

配置环境

使用 ohpm 安装依赖

 编译插件配置

修改工程的 hvigor/hvigor-config.json 文件，加入路由编译插件

在使用到 HMRouter 的模块中引入路由编译插件，修改 hvigorfile.ts

我们项目的模块无非是 Hap、Har 和 Hsp。对应你当前的模块是哪种类型，就使用对应的写法

Hap

Har

Hsp

 初始化路由框架

entry/src/main/ets/entryability/EntryAbility.ets

 定义路由入口

entry/src/main/ets/pages/Index.ets

当前页面作为整个路由的根容器

 模块内跳转

我们先演示跳转到当前模块中的某个页面。

HMRouter 默认指定了 页面目录 为 entry/src/main/ets/components

我们在这个里新建一个组件 entry/src/main/ets/components/LoginPage.ets

此时，回到首页中，进行点击跳转登录

路由传参

传递

接收

指定编译目录

刚才的登录页面是存放到 components 目录下的，实际开发中，我们可以会通过 views 来存放页面，所以这里来设置下

在项目根目录创建路由编译插件配置文件 study/hmrouter_config.json（可选）

然后重命名之前的文件夹名字 entry/src/main/ets/components 为 entry/src/main/ets/views

重新编译执行即可

模块之间跳转

刚才的演示是在同一个模块内进行的，现在我们来演示不同模块之间的跳转

演示的目标是 entry 模块跳转到 cart 模块

cart 模块配置编译插件

cart 是 hsp

cart/hvigorfile.ts

新建购物详情页面

cart/src/main/ets/views/CartDetail.ets

entry 模块引入 cart 模块

entry/oh-package.json5

首页中进行跳转

entry/src/main/ets/pages/Index.ets

效果

跳转动画

我们可以在跳转页面的时候来指定跳转动画

分类两个步骤

1. 定义动画

2. 使用动画

定义动画

假设 A 跳转 B, 那么就是 B 使用动画，为了方便使用，可以在 B 页面定义动画

我们继续使用上面的例子

index 跳转到 CarDetail ， 所以在 CarDetail 定义动画

cart/src/main/ets/views/CartDetail.ets

 使用动画

在 HMRouter 上使用

 效果

拦截器

拦截器可以分成 2 种，局部拦截器和全局拦截器

标记在实现了 IHMInterceptor 的对象上，声明此对象为一个拦截器

· interceptorName: string, 拦截器名称，必填

· priority: number, 拦截器优先级，数字越大优先级越高，非必填，默认为 9；

· global: boolean, 是否为全局拦截器，当配置为 true 时，所有跳转均过此拦截器；默认为 false，当为 false 时需要配置在 @HMRouter 的 interceptors 中才生效。

执行时机：

在路由栈发生变化前，转场动画发生前进行回调。

1.当发生 push/replace 路由时，pageUrl 为空时，拦截器不会执行，需传入 pageUrl 路径；

2.当跳转 pageUrl 目标页面不存在时，执行全局以及发起页面拦截器，当拦截器未执行 DO_REJECT 时，然后执行路由的 onLost 回调

3.当跳转 pageUrl 目标页面存在时，执行全局，发起页面和目标页面的拦截器；

拦截器执行顺序：

1.按照优先级顺序执行，不区分自定义或者全局拦截器，优先级相同时先执行 @HMRouter 中定义的自定义拦截器

2.当优先级一致时，先执行 srcPage>targetPage>global

srcPage 表示跳转发起页面。

targetPage 表示跳转结束时展示的页面。

局部拦截器

局部拦截器只对单个页面生效。我们拿 登录页面来测试 从首页 跳转到登录页面，登录页面的拦截器便会触发

entry/src/main/ets/views/LoginPage.ets

定义拦截器

使用拦截器

输出效果

全局拦截器

直接在 index 页面上使用

生命周期

标记在实现了 IHMLifecycle 的对象上，声明此对象为一个自定义生命周期处理器

· lifecycleName: string, 自定义生命周期处理器名称，必填

· priority: number, 生命周期优先级，数字越大优先级越高，非必填，默认为 9；

· global: boolean, 是否为全局生命周期，当配置为 true 时，所有页面生命周期事件会转发到此对象；默认为 false

生命周期触发顺序：

按照优先级顺序触发，不区分自定义或者全局生命周期，优先级相同时先执行 @HMRouter 中定义的自定义生命周期

我们可以继续在登录页面上测试对应的生命周期

entry/src/main/ets/views/LoginPage.ets

定义生命周期

使用生命周期

完整生命周期

页面组件和生命周期数据交互

生命周期实例中可以初始化对象，并且在 UI 组件中获取做为状态变量

小结

hmrouter 的官网文档还是挺零散的，需要结合文档配套学习使用

HMRouter 接口和属性列表：https://gitee.com/hadss/hmrouter/blob/dev/docs/Reference.md

HMRouterPlugin 编译插件使用说明：https://gitee.com/hadss/hmrouter/blob/dev/HMRouterPlugin/README.md

HMRouterTransitions 高阶转场动画使用说明：https://gitee.com/hadss/hmrouter/blob/dev/HMRouterTransitions/README.md

自定义模板使用说明：https://gitee.com/hadss/hmrouter/blob/dev/docs/CustomTemplate.md

自定义转场动画使用说明：https://gitee.com/hadss/hmrouter/blob/dev/docs/CustomTransition.md

原生到原生页面跳转场景解决方案：https://gitee.com/hadss/hmrouter/blob/dev/docs/Scene.md

SampleCode：https://gitee.com/harmonyos_samples/HMRouter

更多示例：https://gitee.com/hadss/hmrouter/tree/dev/HMRouterExamples

FAQ：https://gitee.com/hadss/hmrouter/blob/dev/docs/FAQ.md

原理介绍：https://developer.huawei.com/consumer/cn/forum/topic/0207153170697988820?fid=0109140870620153026

踏入鸿蒙世界的敲门砖，标志着您在技术征途上的全新起点，提升就业竞争力，获得行业认可，点亮职业成长先机，快人一步抢占未来应用开发赛道！