HarmonyOS Next 全兼容，三端统一的路由跳转方案

TheRouter 鸿蒙版是货拉拉基于HMRouter深度定制的开源路由框架，提供了 Android、iOS、Harmony 三端高一致性使用，在支持平台化应用实现组件化、跨模块调用、动态化等功能的集成等功能基础上，支持动态路由下发、编译时安全检查、路由Path一对多等高度动态能力。

Github: github.com/HuolalaTech...

官网：therouter.cn/

0、开始之前

如果你的是新项目，请先记住一点：plugin、router 两个依赖的版本号必须保持一致，请继续往下看接入步骤。

0.1、查看最新版本

TheRouter 的版本分为两种，稳定版和 rc版，一般不追求新功能我们就用稳定版就行，可以在官网看到最新的版本号和各种版本的说明：therouter.cn/docs/2022/0...

一、接入

在工程根目录命令行引入依赖库和插件库（必须全部依赖，不能只使用其中一个）。

dart 复制代码

// 引入代码库依赖
ohpm i @therouter/library

// 引入插件依赖
npm i @therouter/plugin

第一步：接入编译插件

打开项目根目录的 hvigor/hvigor-config.json5，检查 dependencies 中是否已经加入了依赖，一般为 "@therouter/plugin": "x.x.x"。
打开工程所有模块（hsp、hap、har）的 hvigorfile.ts 文件。
在 plugins 中加入如下对应的依赖

javascript 复制代码

// 如果是 hap，则类似如下依赖
import { hapPlugin } from "@therouter/plugin";
export default {
  plugins: [hapPlugin()]
}

// 如果是 har，则类似如下依赖
import { harPlugin } from "@therouter/plugin";
export default {
  plugins: [harPlugin()]
}

// 如果是 hsp，则类似如下依赖
import { hspPlugin } from "@therouter/plugin";
export default {
  plugins: [hspPlugin()]
}

第二步：检查依赖是否引入

打开 工程根目录 的 oh-package.json5 文件。
检查 dependencies 中，是否已经加入了依赖，一般为："@therouter/library": "x.x.x"

二、使用

2.1、初始化

在项目入口的 UIAbility 的 onCreate() 中加入如下代码：

csharp 复制代码

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    TheRouter.init(this.context);
}

2.2、定义页面容器

TheRouter 按照华为推荐方案，基于系统 Navigation 实现，所以必须在页面中定义一个容器项 TheRouterPage，建议创建一个完全新的类作为入口并在 /resources/base/profile/main_pages.json 中配置这个类，复制如下代码：

typescript 复制代码

import { TheRouterPage } from '@therouter/library';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      TheRouterPage({
        stackId: 'XXXX',  //【必传】可以自定义当前stack的名字，每个stack必须唯一
        root: 'path'  // 【必传】当前应用的首页 path，推荐按照一定格式定义页面path
		// 还有很多可选参数，详情请见文档
      });
    }
    .height('100%')
    .width('100%')
  }
}

2.3、声明路由

给需要跳转的页面加上路由表声明

arduino 复制代码

@Route({path : "http://therouter.com/home"})
export struct HomePage {
	xxx
}

2.4、发起跳转

在需要跳转页面的位置调用如下代码：

csharp 复制代码

TheRouter
	.build("http://therouter.com/home")
	.withString('k', 'v') // 向落地页传参数（如果没参数，可不调用）
	.with({ hello: 'world' }) // 另一种方式传参
	.navigation()

2.5、获取页面传参

接收有两种形式：

通过注解自动接收，默认支持 String 和8种基本数据类型，也支持自定义对象的解析
通过代码从路由中获取

使用注解接收对象时，必须调用 TheRouter.inject(this) 。

less 复制代码

// 第一种：使用注解自动填充
  // 允许解析成8种基本数据类型或对应封装类
  @Autowired()
  key1 : string = ''

  // 允许自定义传参key，如果不传默认是变量名作为key
  @Autowired('hello')
  key1 : string = ''

  // 使用注解接收对象时，必须调用，建议放在 aboutToApper() 中调用。
  TheRouter.inject(this)



// 第二种：通过代码从路由中获取
  // 可以在任何方法中调用，getCurrentParam() 返回值是个ESObject
  const v = TheRouter.getCurrentParam()['k'];

生命周期

在 TheRouter 中，为每一个 struct 页面都实现了 page 的生命周期方法，你无需再关心 struct 和 page 的区别，可以直接覆写上图中的全部生命周期函数。

例如实现二次点击返回键才关闭页面，只需要这样重写onBackPress()即可：

kotlin 复制代码

  /**
   * 如果自定义 onBackPress()，必须调用 TheRouter.inject(this)
   */
  onBackPress(): boolean | void {
    let time = Date.now();
    if (time - this.lastTime > 1000) {
      this.getUIContext()
        .getPromptAction()
        .showToast({ message: `1s内按两次才关闭页面，当前标题${this.title}`, duration: 1000 });
      this.lastTime = time;
      return true;
    } else {
      return false;
    }
  }

三端统一

从官网首页可以看到，TheRouter 同时支持三端的跳转，且使用的 API 都完全一样，这极大降低了学习成本。比如我们就是直接把 Android 的代码拿过来，让 AI 翻译了一下写的一套鸿蒙代码，期间核心逻辑几乎没有任何改动。而且他三端都开源，很适合跨端学习和使用。

总结

TheRouter 并不仅仅是一个小巧灵活的路由库，而是一整套 Android、iOS、Harmony 三端完整的移动端解决方案，对移动端开发者更友好，上手开发适应性更强。使用 TheRouter 能够解决几乎全部的模块化过程中会遇到的问题。对于现有的路由框架，我们也在最大限度支持平滑迁移。你也可以在 Github issue 中提出需求，我们评估后会尽快支持，也欢迎任何人提供 Pull Requests。