ZRouter： https://gitee.com/common-apps/ZRouter

一句话总结：使用简单，配置麻烦

ZRouter是一款轻量级且非侵入性的鸿蒙动态路由框架，可解决HAR/HSP业务模块间的耦合与通信问题。主要特性：

简化Navigation使用，无需关注路由表的配置，对Navigation及NavDestination组件保持零侵入；
支持API链式调用，让API更简洁直观；
为了进一步简化使用，支持NavDestination页面模板化，是一个可选项；
注解参数支持使用静态常量，可跨模块定义；
支持自定义拦截器，可实现页面重定向、登录验证、数据预取、埋点等业务场景。
支持服务路由，可实现Har/Hsp模块间的通信；
支持全局及单个页面的生命周期函数管理，可使任意类都能享有与组件相同的生命周期特性，可用于页面埋点统计等业务场景；
支持跨多级页面参数携带返回监听；
支持自定义URL路径跳转，可在拦截器内自行解析URL实现业务逻辑；
内置多种转场动画效果（平移、旋转、渐变、缩放、高斯模糊、共享一镜到底动画），并支持自定义动画；
支持启动模式、混淆、嵌套Navigation、Hap；
支持与您现有项目中的Navigation无缝融合，实现零成本向本库迁移；
支持ArkUI-X跨平台上使用；
支持第三方应用Navigation的使用本库API；

安装

在项目根目录的hvigor目录下的hvigor-config.json5文件中配置安装

截屏2025-08-19 09.40.25.png

配置

支持配置方式：

模块级配置：即在每个需要ZRouter跳转的模块目录下的hvigorfile.ts文件中单独配置；

截屏2025-08-19 09.42.06.png

// 2、初始化配置

// 1、导入
import { routerRegisterPlugin, PluginConfig } from 'router-register-plugin'

// 2、初始化配置
const config: PluginConfig = {
    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预览构建效率

其中_generated目录和route_map.json文件在编译阶段自动生成的，建议在git的.gitignore忽略掉这两个文件。

_generated
route_map.json

还有个关键点是，如果要跨模块跳转，还是需要导入到 'Oh-package.json5'

截屏2025-08-21 16.26.09.png

ZRouter的基本使用

下载安装

截屏2025-08-19 09.43.46.png

页面跳转

新建三个模块分别是harA、harB、hspC，三者之间没有依赖关系，entry模块依赖了这三个模块，通过ZRouter可以在四个模块间相互跳转，从而达到模块解耦效果。模块关系图如下图：

68747470733a2f2f696d672e7a34612e6e65742f696d616765732f323032352f30382f30352f6f686f732d7a726f757465722d312e706e67.png

1、在EntryAbility的onCreate()方法中初始化ZRouter，建议使用initialize()方法进行初始化，init()方法已弃用

截屏2025-08-19 09.44.47.png

  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    ZRouter.initialize((config) => {
      config.isLoggingEnabled = BuildProfile.DEBUG
      config.isHSPModuleDependent = true
      config.onDynamicLoadComplete = () => {
        console.log('完成所有模块加载')
      }
    })
  }

App 入口页面

截屏2025-08-19 09.27.10.png

将跳转地址放到统一文件中

截屏2025-08-19 09.46.15.png

跳转页面处理

截屏2025-08-19 09.47.00.png

自动生成的_generated

截屏2025-08-19 09.47.36.png

FAQ

@ZRoute等注解常量跨模块查找失败或者跳转报错100005

可以检查下以下几个地方：

检查所在模块_generated和route_map.json5文件是否有生成的路由信息，如果没有生成，检查模块下的hvigorfile.ts 是否添加编译插件配置，以及scanDirs是否配置待扫描的路径；
若有跨模块定义，检查常量类是否在模块的Index.ets文件导出；
检查模块间的dependencies依赖是否正确，是否有空格；
检查常量类文件是否是ets文件，目前是不支持ts文件。
以上都是正常的，可以清IDE缓存重启下。

没有生成_generated和route_map.json5文件

可以检查下以下几个地方：

模块下的hvigorfile.ts文件中是否配置路由扫描的信息
跳转页面是否使用@Route或@ZRoute注解

修改路由名称后跳转报错100005

在修改路由名称后跳转报错100005，检查发现route_map.json5文件确实是生效了，这时可以Clean Project项目重新编译运行。

路由转场动画

参考 https://gitee.com/common-apps/ZRouter/wikis/%E8%B7%AF%E7%94%B1%E8%BD%AC%E5%9C%BA%E5%8A%A8%E7%94%BB

ZRouter 使用 - 路由