开放代码社区 › ZRouter 鸿蒙动态路由框架
ZRouter 鸿蒙动态路由框架
开发工具TypeScriptZRouter 是一款轻量级、非侵入性的鸿蒙动态路由框架，用于解决 HAR/HSP 业务模块间的耦合与通信问题。它简化 Navigation 使用，无需配置路由表，支持链式 API、服务路由、自定义拦截器、生命周期管理、跨多级参数返回监听、URL 跳转及多种转场动画，适用于鸿蒙应用模块解耦与页面跳转场景。
仓库地址
https://gitee.com/common-apps/ZRouter.gitREADME
## 介绍
ZRouter是一款轻量级且非侵入性的鸿蒙动态路由框架，可解决HAR/HSP业务模块间的耦合与通信问题。主要特性：
- 简化Navigation使用，无需关注路由表的配置，对Navigation及NavDestination组件保持零侵入；
- **支持API链式调用，让API更简洁直观；**
- **为了进一步简化使用，支持NavDestination页面模板化，是一个可选项；**
- 注解参数支持使用静态常量，可跨模块定义；
- 支持自定义拦截器，可实现页面重定向、登录验证、数据预取、埋点等业务场景。
- **支持服务路由，可实现Har/Hsp模块间的通信；**
- 支持全局及单个页面的生命周期函数管理，可使任意类都能享有与组件相同的生命周期特性，可用于页面埋点统计等业务场景；
- 支持跨多级页面参数携带返回监听；
- 支持自定义URL路径跳转，可在拦截器内自行解析URL实现业务逻辑；
- 内置多种转场动画效果（平移、旋转、渐变、缩放、高斯模糊、共享一镜到底动画），并支持自定义动画；
- 支持启动模式、混淆、嵌套Navigation、Hap、**元服务**；
- **支持与您现有项目中的Navigation无缝融合，实现零成本向本库迁移；**
- 支持ArkUI-X跨平台上使用；
- 支持第三方应用Navigation的使用本库API；
**使用十分简单，没有繁琐的配置，两行代码就可以完成页面的跳转**，如下:
<center>
[](https://img.z4a.net/image/WX20250805-102507.lQeP3)
</center>
ZRouter已上架录入到[华为鸿蒙生态伙伴组件专区](https://developer.huawei.com/consumer/cn/market/prod-detail/7b3615ee364d4b36bcdd2549678a63f1/50e449ed4fcd418785706add0c40eab6)
## 使用收集
为了持续优化鸿蒙ZRouter路由库，恳请您花一点时间填写下应用名称。您的每一次反馈，都是我们持续改进的重要动力。
https://wj.qq.com/s2/25201566/76c1/
## 快速入门
[ZRouter快速入门](https://gitee.com/common-apps/ZRouter/wikis/ZRouter%20%E5%BF%AB%E9%80%9F%E5%85%A5%E9%97%A8)
## **router-register-plugin编译插件 — 很重要**
### 下载安装
**在项目根目录的hvigor目录下的`hvigor-config.json5`文件中配置安装**
<center>
[](https://imgse.com/i/pEovcrt)
</center>
```
"dependencies": {
"router-register-plugin":"x.x.x"
},
```
**编译插件最新版本**: 
[](https://www.npmjs.com/package/router-register-plugin)
最后记得Sync Now或重新build让插件安装生效。
或者使用hvigorw命令行工具执行任一命令，命令行工具会自动执行安装构建依赖。
```
hvigorw --sync
```
### 配置
支持两种配置方式：
- **工程级配置**: 即在工程根目录下的hvigorfile.ts文件中全局配置；
- **模块级配置**：即在每个模块目录下的hvigorfile.ts文件中单独配置；
> 不建议一个项目同时使用两种配置方式，虽然是这种混合方式也是支持的，但容易出现配置冲突。模块级配置相对繁琐些，但配置项会更精细化些。
步骤：
```
// 1、导入
import { routerRegisterPlugin, OptionalPluginConfig } from 'router-register-plugin'
// 2、初始化配置
const config: OptionalPluginConfig = {
scanDirs: ['src/main/ets/pages', 'src/main/ets/views'], // 扫描的目录，如果不设置，默认是扫描src/main/ets目录
logEnabled: true, // 查看日志
viewNodeInfo: false, // 查看节点信息
ignoredModules:['RouterApi','common','xxx'], // 忽略的参与构建的模块，根据自己项目自行设置
enableUiPreviewBuild: false, // 启用UI预览构建，不建议启动
}
export default {
// 3、添加插件
plugins:[routerRegisterPlugin(config)]
}
```
> **注意：hvigorfile.ts文件中默认配置不要删除了。**
配置参数说明：
| 参数名 | 类型 | 默认值 | 描述 |
|----------------------------------|----------|-------------------|------------------------------------------------------------------------------|
| `scanDirs` | string[] | ['src/main/ets'] | 扫描的目录，如果不设置，默认是扫描src/main/ets目录。建议配置该字段，避免扫描所有目录，影响工程编译效率** | |
| `logEnabled` | boolean | true | 是否打印日志 | |
| `viewNodeInfo` | boolean | false | 查看节点信息，只有与logEnable同时为true才会打印输出 |
| ~~`isAutoDeleteHistoryFiles`~~ | boolean | false | 是否在构建时删除编译产物，已弃用，在项目`clean`自动删除无用编译产物，请不要设置此参数。 | |
| `lifecycleObserverAttributeName` | string | lifecycleObserver | 如果使用了NavDest页面模板化功能，该配置字段会生效，默认属性名是lifecycleObserver，也可以在@Route注解上单独设置这个属性 |
| **`ignoredModules`** | string[] | [] | 忽略需要扫描的模块，填写模块名称，默认是全部模块；**插件在工程级时使用**，该字段才会生效。**建议配置该字段，避免扫描所有模块，影响工程编译效率** |
| `enableUiPreviewBuild` | boolean | false | 是否在ui预览构建时生成，默认不启用, 会降低ui预览构建效率 |
> **注意：** 以上配置参数都是可选的，建议配置`scanDirs`和`ignoredModules`字段，避免扫描所有目录和模块，影响工程编译效率。
编译阶段会自动生成一些文件，建议在git的`.gitignore`忽略掉这些文件。
```gitignore
_generated
**/route_map.json
**/router_map.json
```
## ZRouter的基本使用
### 下载安装
在每个har/hsp模块中，通过ohpm工具下载安装库：
```
ohpm install @hzw/zrouter
```
### 页面跳转
新建三个模块分别是harA、harB、hspC，三者之间没有依赖关系，entry模块依赖了这三个模块，通过ZRouter可以在四个模块间相互跳转，从而达到模块解耦效果。模块关系图如下图：
<center>
[](https://img.z4a.net/image/ohos-zrouter-1.lQ0uz)</center>
1、在EntryAbility的onCreate()方法中初始化ZRouter，**建议使用initialize()方法进行初始化，init()方法已弃用**
```
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
// 如果项目中存在hsp模块则传入true
ZRouter.initialize((config) => {
config.isLoggingEnabled = BuildProfile.DEBUG
config.isHSPModuleDependent = true
})
}
```
**建议在`AbilityStage`的`onCreate()`方法中完成初始化**
```typescript
export class AppAbilityStage extends AbilityStage{
onCreate(): void {
// 应用HAP首次加载时触发，可以在此执行该Module的初始化操作（例如资源预加载、线程创建等）。
// 在module.json5配置文件中，通过配置 srcEntry 参数来指定模块对应的代码路径，以作为HAP加载的入口。
// 初始化路由
ZRouter.initialize((config) => {
// 设置context
config.context = this.context
config.isLoggingEnabled = BuildProfile.DEBUG
config.isHSPModuleDependent = true
// 服务路由初始化配置，如果没有使用服务路由，可不设置
config.loadDynamicModule = ['@hzw/hara', 'harb', 'hspc']
config.onDynamicLoadComplete = () => {
console.log("已完成所有模块的加载")
}
})
}
}
```
2、在Index页面**使用Navigation作为根视图，通过ZRouter的`getNavStack()`方法获取NavPathStack实例，将其传入到Navigation的构造函数中。**
**如果在Index入口文件中启动Splash页面，建议放在Navigation的`onAppear`方法中进行启动，或者组件的`onPageShow`方法**，具体可参考demo
```
// Index 中使用 aboutToAppear 生命周期函数会因为 Navigation 还没初始化完成导致无法有效跳转,可使用替换成 onPageShow
@Entry
@Component
struct Index {
build() {
// 获取NavPathStack实例对象
Navigation(ZRouter.getNavStack()){
Column({space:12}){
Button('toHarAMainPage').onClick((event: ClickEvent) => {