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

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

媒介

HMRouter 作为 HarmonyOS 的页面跳转场景办理方案，聚焦办理应用内原生页面的跳转逻辑。
HMRouter 底层对体系 Navigation 举行封装，集成了 Navigation、NavDestination、NavPathStack 的体系能力，提供了可复用的路由拦截、页面生命周期、自界说转场动画，而且在跳转传参、额外的生命周期、服务型路由方面对体系能力举行了扩展。
目的是让开发者在开发过程中无需关注 Navigation、NavDestination 容器组件的相关细节及模板代码，屏蔽跳转时的判断逻辑，降低拦截器、自界说转场动画实现复杂度，更好的举行模块间解耦
对比

现在鸿蒙应用开发中，官方推出的路由方案有两个，分别是Router和Navigation。现在官方主要推荐的也是 Navigation。
业务场景NavigationRouter一多能力支持，Auto 模式自顺应单栏跟双栏显示不支持跳转指定页面pushPath & pushDestinationpushUrl & pushNameRoute跳转 HSP 中页面支持支持跳转 HAR 中页面支持支持跳转传参支持支持获取指定页面参数支持不支持传参范例传参为对象情势传参为对象情势，对象中暂不支持方法变量跳转效果回调支持支持跳转单例页面支持支持页面返回支持支持页面返回传参支持支持返回指定路由支持支持页面返回弹窗支持，通过路由拦截实现showAlertBeforeBackPage路由替换replacePath & replacePathByNamereplaceUrl & replaceNameRoute路由栈整理clearclear整理指定路由removeByIndexes & removeByName不支持转场动画支持支持自界说转场动画支持支持，动画范例受限屏蔽转场动画支持全局和单次支持 设置 pageTransition 方法 duration 为 0geometryTransition 共享元素动画支持（NavDestination 之间共享）不支持页面生命周期监听UIObserver.on(‘navDestinationUpdate’)UIObserver.on(‘routerPageUpdate’)获取页面栈对象支持不支持路由拦截支持通过 setInterception 做路由拦截不支持路由栈信息查询支持getState() & getLength()路由栈 move 操作moveToTop & moveIndexToTop不支持沉醉式页面支持不支持，需通过 window 设置设置页面标题栏（titlebar）和工具栏（toolbar）支持不支持模态嵌套路由支持不支持 但是原生的 Navigation 缺少了路由拦截、页面生命周期、自界说转场动画，而且在跳转传参、额外的生命周期、服务型路由。
因此 HMRouter 便是对此做出了拓展和加强。
学习目标

接下来，将通过这篇文章带领小搭档上手HMRouter的应用。
工程目录

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

• 工程的目录名称是 study
  
• 入口模块是 entry
  
• cart 是 hsp 模块
  

设置情况

使用 ohpm 安装依赖

1. ohpm install @hadss/hmrouter
2. ohpm install @hadss/hmrouter-transitions

复制代码

编译插件设置

• 修改工程的hvigor/hvigor-config.json文件，加入路由编译插件
  
  1. {
  2.   "dependencies": {
  3.     "@hadss/hmrouter-plugin": "^1.0.0-rc.10"
  4.     // 使用npm仓版本号
  5.   }
  6.   // ...其他配置
  7. }

  复制代码
• 在使用到 HMRouter 的模块中引入路由编译插件，修改hvigorfile.ts
         我们项目的模块无非是 Hap、Har 和 Hsp。对应你当前的模块是哪种范例，就使用对应的写法
  
  
  
  • Hap
    
    1. // entry/hvigorfile.ts  entry模块的hvigorfile.ts
    2. import { hapTasks } from "@ohos/hvigor-ohos-plugin";
    3. import { hapPlugin } from "@hadss/hmrouter-plugin";
    5. export default {
    6.   system: hapTasks,
    7.   plugins: [hapPlugin()], // 使用HMRouter标签的模块均需要配置，与模块类型保持一致
    8. };

    复制代码
  • Har
    
    1. import { harTasks } from "@ohos/hvigor-ohos-plugin";
    2. import { harPlugin } from "@hadss/hmrouter-plugin";
    4. export default {
    5.   system: harTasks,
    6.   plugins: [harPlugin()], // 使用HMRouter标签的模块均需要配置，与模块类型保持一致
    7. };

    复制代码
  • Hsp
    
    1. import { hspTasks } from "@ohos/hvigor-ohos-plugin";
    2. import { hspPlugin } from "@hadss/hmrouter-plugin";
    4. export default {
    5.   system: hspTasks,
    6.   plugins: [hspPlugin()], // 使用HMRouter标签的模块均需要配置，与模块类型保持一致
    7. };

    复制代码
  
  

初始化路由框架

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

1. export default class EntryAbility extends UIAbility {
2.   onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
3.     HMRouterMgr.init({
4.       context: this.context,
5.     });
6.   }
7. }

复制代码

界说路由入口

   entry/src/main/ets/pages/Index.ets
  当前页面作为整个路由的根容器

1. import { HMDefaultGlobalAnimator, HMNavigation } from "@hadss/hmrouter";
2. import { AttributeUpdater } from "@kit.ArkUI";
4. class MyNavModifier extends AttributeUpdater<NavigationAttribute> {
5.   initializeModifier(instance: NavigationAttribute): void {
6.     // instance.hideNavBar(true);  // 先注释掉  否则看不见结果
7.   }
8. }
10. @Entry
11. @Component
12. export struct Index {
13.   modifier: MyNavModifier = new MyNavModifier();
15.   build() {
16.     // @Entry中需要再套一层容器组件,Column或者Stack
17.     Column() {
18.       // 使用HMNavigation容器
19.       HMNavigation({
20.         navigationId: 'mainNavigation', homePageUrl: 'MainPage',
21.         options: {
22.           standardAnimator: HMDefaultGlobalAnimator.STANDARD_ANIMATOR,
23.           dialogAnimator: HMDefaultGlobalAnimator.DIALOG_ANIMATOR,
24.           modifier: this.modifier
25.         }
26.       }) {
27.         Column({ space: 10 }) {
28.           Button("跳转到 登录页面")
29.         }
30.       }
31.     }
32.     .height('100%')
33.     .width('100%')
34.   }
35. }

复制代码

模块内跳转

我们先演示跳转到当前模块中的某个页面。
HMRouter 默认指定了 页面貌录 为 entry/src/main/ets/components
我们在这个里新建一个组件 entry/src/main/ets/components/LoginPage.ets

1. import { HMRouter } from "@hadss/hmrouter"
3. @HMRouter({
4.   pageUrl: 'LoginPage',
5. })
6. @Component
7. export struct LoginPage {
8.   build() {
9.     Column() {
10.       Button('登录页面')
11.     }
12.     .width("100%")
13.     .height("100%")
14.     .justifyContent(FlexAlign.Center)
15.   }
16. }

复制代码

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

1. Button("跳转到 登录页面").onClick(() => {
2.   HMRouterMgr.push({ pageUrl: "LoginPage" });
3. });

复制代码

路由传参

转达

1. HMRouterMgr.push({ pageUrl: "LoginPage", param: { 数据 } });

复制代码

接收

1. HMRouterMgr.getCurrentParam(HMParamType.all);

复制代码

指定编译目录

刚才的登录页面是存放到 components 目录下的，现实开发中，我们可以会通过 views来存放页面，所以这里来设置下
在项目根目录创建路由编译插件设置文件study/hmrouter_config.json（可选）

1. {
2.   "scanDir": ["src/main/ets/views"]
3. }

复制代码

然后重命名之前的文件夹名字 entry/src/main/ets/components 为 entry/src/main/ets/views
重新编译执行即可
模块之间跳转

刚才的演示是在同一个模块内举行的，现在我们来演示差异模块之间的跳转
演示的目标是 entry 模块跳转到 cart 模块
cart 模块设置编译插件

   cart 是 hsp
  cart/hvigorfile.ts

1. import { hspTasks } from "@ohos/hvigor-ohos-plugin";
2. import { hspPlugin } from "@hadss/hmrouter-plugin";
4. export default {
5.   system: hspTasks,
6.   plugins: [hspPlugin()], // 使用HMRouter标签的模块均需要配置，与模块类型保持一致
7. };

复制代码

新建购物详情页面

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

1. import { HMRouter } from "@hadss/hmrouter"
3. @HMRouter({
4.   pageUrl: 'CartDetail',
5. })
6. @Component
7. export struct CartDetail {
8.   build() {
9.     Column() {
10.       Button('我的是购物车详情页面')
11.     }
12.     .width("100%")
13.     .height("100%")
14.     .justifyContent(FlexAlign.Center)
15.   }
16. }

复制代码

entry 模块引入 cart 模块

   entry/oh-package.json5

1.   "dependencies": {
2.     "cart": "file:../cart"
3.   },

复制代码

首页中举行跳转

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

1. Button("跳转到 购物车详情页面").onClick(() => {
2.   HMRouterMgr.push({ pageUrl: "CartDetail" });
3. });

复制代码

效果

跳转动画

我们可以在跳转页面的时候来指定跳转动画
分类两个步骤

• 界说动画
  
• 使用动画
  

界说动画

假设 A 跳转 B, 那么就是 B 使用动画，为了方便使用，可以在 B 页面界说动画
我们继续使用上面的例子
index 跳转到 CarDetail ， 所以在 CarDetail 界说动画
   cart/src/main/ets/views/CartDetail.ets

1. @HMAnimator({ animatorName: "liveCommentsAnimator" })
2. export class liveCommentsAnimator implements IHMAnimator {
3.   effect(enterHandle: HMAnimatorHandle, exitHandle: HMAnimatorHandle): void {
4.     // 入场动画
5.     enterHandle.start(
6.       (
7.         translateOption: TranslateOption,
8.         scaleOption: ScaleOption,
9.         opacityOption: OpacityOption
10.       ) => {
11.         translateOption.y = "100%";
12.       }
13.     );
14.     enterHandle.finish(
15.       (
16.         translateOption: TranslateOption,
17.         scaleOption: ScaleOption,
18.         opacityOption: OpacityOption
19.       ) => {
20.         translateOption.y = "0";
21.       }
22.     );
23.     enterHandle.duration = 500;
25.     // 出场动画
26.     exitHandle.start(
27.       (
28.         translateOption: TranslateOption,
29.         scaleOption: ScaleOption,
30.         opacityOption: OpacityOption
31.       ) => {
32.         translateOption.y = "0";
33.       }
34.     );
35.     exitHandle.finish(
36.       (
37.         translateOption: TranslateOption,
38.         scaleOption: ScaleOption,
39.         opacityOption: OpacityOption
40.       ) => {
41.         translateOption.y = "100%";
42.       }
43.     );
44.     exitHandle.duration = 500;
45.   }
46. }

复制代码

使用动画

在 HMRouter 上使用

1. @HMRouter({
2.   pageUrl: 'CartDetail',
3.   // 2 使用动画
4.   animator: "liveCommentsAnimator"
5. })
6. @Component
7. export struct CartDetail {
8.   build() {
9.     Column() {
10.       Button('我的是购物车详情页面')
11.     }
12.     .width("100%")
13.     .height("100%")
14.     .justifyContent(FlexAlign.Center)
15.   }
16. }

复制代码

效果

拦截器

拦截器可以分成 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 目标页面存在时，执行全局，发起页面和目标页面的拦截器；
拦截器执行顺序：

• 按照优先级顺序执行，不区分自界说大概全局拦截器，优先级雷同时先执行@HMRouter 中界说的自界说拦截器
  
• 当优先级一致时，先执行 srcPage>targetPage>global
  

   srcPage 体现跳转发起页面。
  targetPage 体现跳转竣事时展示的页面。
  局部拦截器

局部拦截器只对单个页面生效。我们拿 登录页面来测试 从首页 跳转到登录页面，登录页面的拦截器便会触发
   entry/src/main/ets/views/LoginPage.ets
  界说拦截器

1. @HMInterceptor({ interceptorName: "Loginterceptor", global: false })
2. export class JumpInfoInterceptor implements IHMInterceptor {
3.   handle(info: HMInterceptorInfo): HMInterceptorAction {
4.     console.log("拦截器", JSON.stringify(info));
5.     // DO_NEXT  正常跳转
6.     // DO_REJECT 拒绝跳转
7.     return HMInterceptorAction.DO_NEXT;
8.   }
9. }

复制代码

使用拦截器

1. // 使用拦截器
2. @HMRouter({
3.   pageUrl: 'LoginPage',
4.   interceptors: ['Loginterceptor']
5. })
6. @Component
7. export struct LoginPage {
8.   build() {
9.     Column() {
10.       Button('登录页面')
11.     }
12.     .width("100%")
13.     .height("100%")
14.     .justifyContent(FlexAlign.Center)
15.   }
16. }

复制代码

输出效果

1. {
2.   "srcName": "HM_NavBar",
3.   "targetName": "LoginPage",
4.   "type": "push",
5.   "routerPathInfo": {
6.     "pageUrl": "LoginPage"
7.   },
8.   "context": {
9.     "instanceId_": 100000
10.   },
11.   "isSrc": false
12. }

复制代码

全局拦截器

直接在 index 页面上使用

1.   aboutToAppear(): void {
2.     // 注册全局拦截器
3.     HMRouterMgr.registerGlobalInterceptor({
4.       interceptorName: "拦截器的名字",
5.       // 优先级
6.       priority: 1,
7.       // 拦截器
8.       interceptor: {
9.         // 处理函数
10.         handle(info: HMInterceptorInfo) {
11.           return HMInterceptorAction.DO_NEXT
12.         }
13.       }
14.     })
15.   }

复制代码

生命周期

1. @HMLifecycle(lifecycleName, priority, global)

复制代码

标志在实现了 IHMLifecycle 的对象上，声明此对象为一个自界说生命周期处置惩罚器

• lifecycleName: string, 自界说生命周期处置惩罚器名称，必填
  
• priority: number, 生命周期优先级，数字越大优先级越高，非必填，默认为 9；
  
• global: boolean, 是否为全局生命周期，当设置为 true 时，所有页面生命周期事件会转发到此对象；默认为 false
  

生命周期触发顺序：
按照优先级顺序触发，不区分自界说大概全局生命周期，优先级雷同时先执行@HMRouter 中界说的自界说生命周期
我们可以继续在登录页面上测试对应的生命周期
   entry/src/main/ets/views/LoginPage.ets
  界说生命周期

1. @HMLifecycle({ lifecycleName: 'LoginLifecycle' })
2. export class PageDurationLifecycle implements IHMLifecycle {
3.   private time: number = 0;
5.   onShown(ctx: HMLifecycleContext): void {
6.     this.time = new Date().getTime();
7.     console.log("生命周期", JSON.stringify(ctx))
8.   }
10.   onHidden(ctx: HMLifecycleContext): void {
11.     const duration = new Date().getTime() - this.time;
12.   }
13. }

复制代码

使用生命周期

2. // 使用拦截器
3. @HMRouter({
4.   pageUrl: 'LoginPage',
5.   interceptors: ['Loginterceptor'],
6.   lifecycle: "LoginLifecycle"
7. })
8. @Component
9. export struct LoginPage {
10.   build() {
11.     Column() {
12.       Button('登录页面')
13.     }
14.     .width("100%")
15.     .height("100%")
16.     .justifyContent(FlexAlign.Center)
17.   }
18. }

复制代码

完整生命周期

1. export interface HMLifecycleContext {
2.     uiContext: UIContext;
3.     navContext?: NavDestinationContext;
4. }
5. export type HMLifecycleCallback = (ctx: HMLifecycleContext) => boolean | void;
6. export interface IHMLifecycle {
7.     onPrepare?(ctx: HMLifecycleContext): void;
8.     onAppear?(ctx: HMLifecycleContext): void;
9.     onDisAppear?(ctx: HMLifecycleContext): void;
10.     onShown?(ctx: HMLifecycleContext): void;
11.     onHidden?(ctx: HMLifecycleContext): void;
12.     onWillAppear?(ctx: HMLifecycleContext): void;
13.     onWillDisappear?(ctx: HMLifecycleContext): void;
14.     onWillShow?(ctx: HMLifecycleContext): void;
15.     onWillHide?(ctx: HMLifecycleContext): void;
16.     onReady?(ctx: HMLifecycleContext): void;
17.     onBackPressed?(ctx: HMLifecycleContext): boolean;
18. }

复制代码

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

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

1. import {
2.   HMInterceptor,
3.   HMInterceptorAction,
4.   HMInterceptorInfo,
5.   HMLifecycle,
6.   HMLifecycleContext,
7.   HMRouter,
8.   HMRouterMgr,
9.   IHMInterceptor,
10.   IHMLifecycle
11. } from '@hadss/hmrouter';
13. // 定义拦截器
14. @HMInterceptor({ interceptorName: 'Loginterceptor', global: false })
15. export class JumpInfoInterceptor implements IHMInterceptor {
16.   handle(info: HMInterceptorInfo): HMInterceptorAction {
17.     console.log("拦截器", JSON.stringify(info))
18.     return HMInterceptorAction.DO_NEXT;
19.   }
20. }
22. @Observed
23. export class ObservedModel {
24.   isLoad: boolean = false;
25. }
27. @HMLifecycle({ lifecycleName: 'LoginLifecycle' })
28. export class PageDurationLifecycle implements IHMLifecycle {
29.   model: ObservedModel = new ObservedModel()
31.   onAppear(ctx: HMLifecycleContext): void {
32.   }
33. }
36. // 使用拦截器
37. @HMRouter({
38.   pageUrl: 'LoginPage',
39.   interceptors: ['Loginterceptor'],
40.   lifecycle: "LoginLifecycle"
41. })
42. @Component
43. export struct LoginPage {
44.   @State model: ObservedModel | null =
45.     (HMRouterMgr.getCurrentLifecycleOwner()?.getLifecycle() as PageDurationLifecycle).model;
47.   build() {
48.     Column() {
49.       Button('登录页面' + this.model?.isLoad)
50.         .onClick(() => {
51.           this.model!.isLoad = !this.model?.isLoad
52.         })
54.     }
55.     .width("100%")
56.     .height("100%")
57.     .justifyContent(FlexAlign.Center)
58.   }
59. }

复制代码

小结

hmrouter 的官网文档还是挺零散的，需要联合文档配套学习使用
HMRouter 接口和属性列表

查看详情
HMRouterPlugin 编译插件使用阐明

查看详情
HMRouterTransitions 高阶转场动画使用阐明

查看详情
自界说模板使用阐明

查看详情
自界说转场动画使用阐明

查看详情
原生到原生页面跳转场景办理方案

查看详情
SampleCode

查看详情
更多示例

查看详情
FAQ

查看详情
原理先容

查看详情

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。