ZRouter是基于鸿蒙Navigation系统路由表和Hvigor插件实现的动态路由方案，以解决模块间的耦合与通信问题

## 介绍 ZRouter是一款轻量级的动态路由框架，基于Navigation系统路由表和Hvigor插件实现的方案，可以解决多个业务模块（HAR/HSP）之间解耦和通信问题，从而实现业务复用和功能扩展。主要特性： - 对Navigation简化使用，封装一系列简单易用的API，支持链式调用，无需再关注路由表的配置，对Navigation组件保持着零侵入零耦合； - 注解参数支持使用静态常量，可跨模块定义； - 支持多个拦截器(支持优先级和中断拦截)和全局拦截器，可实现页面跳转和显示、埋点、登录等拦截处理； - 支持服务路由，可在相互独立的Har/Hsp模块间通信； - 支持组件的生命周期管理，以及跨多级页面参数回传接收； - 支持自定义URL路径跳转，可通过拦截URL路径来跳转原生不同页面； - 支持第三方Navigation的使用本库API； - 支持启动模式、混淆、嵌套Navigation； - 未来计划：支持转场动画、NavDestination代码模版化选项。 > ZRouter侧重于路由跳转与模块解耦，以及组件化通信；对Navigation组件没有任何耦合，不做任何的限制把自主权交给开发者。 **使用十分简单，没有繁琐的配置，两行代码就可以完成页面的跳转**，如下: <center> [](https://www.z4a.net/image/yUNrzw) </center> ZRouter已上架录入到[华为鸿蒙生态伙伴组件专区](https://developer.huawei.com/consumer/cn/market/landing/component)  ## router-register-plugin插件的使用 ### 下载安装 在项目根目录的hvigor目录的hvigor-config.json5文件中配置安装 ``` "dependencies": { // "router-register-plugin":"file:../plugins/router-register-plugin-1.0.2.tgz" "router-register-plugin":"1.0.7" }, ```  [](https://www.npmjs.com/package/router-register-plugin) 最后记得Sync Now或重新build让插件安装生效。 或者使用hvigorw命令行工具执行任一命令，命令行工具会自动执行安装构建依赖。 ``` hvigorw --sync ``` ### 初始配置 在每个模块中的hvigorfile.ts文件导入router-register-plugin插件模块，如下： ``` // 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, // 查看节点信息 isAutoDeleteHistoryFiles: true // 删除无用编译产物 } export default { // 3、添加插件 plugins:[routerRegisterPlugin(config)] } ``` 常用的配置字段： - scanDirs：扫描的目录，建议是页面目录，这样可以更精准扫描目标文件，如果不设置，默认是扫描src/main/ets目录 - logEnabled：日志记录开关。 - viewNodeInfo：查看节点信息的开关，只有logEnabled和viewNodeInfo同时开启才会生效 - isAutoDeleteHistoryFiles：是否删除无用编译产物。 PluginConfig配置对象还有其他属性，但不建议使用，使用默认值即可。 > 上面所有路径都是相对模块的src目录而言的，是相对路径。最后记得Sync Now或重新build让配置生效。 其中`_generated`目录和`route_map.json`文件在编译阶段自动生成的，建议在git的`.gitignore`忽略掉这两个文件。 ```gitignore _generated route_map.json ``` ## ZRouter的基本使用 ### 下载安装 在每个har/hsp模块中，通过ohpm工具下载安装库： ``` ohpm install @hzw/zrouter ``` ### 页面跳转 新建三个模块分别是harA、harB、hspC，三者之间没有依赖关系，entry模块依赖了这三个模块，通过ZRouter可以在四个模块间相互跳转，从而达到模块解耦效果。模块关系图如下图： <center>  </center> 1、在EntryAbility的onCreate()方法中初始化ZRouter，**建议使用initialize()方法进行初始化，init()方法已弃用** ``` onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { // 如果项目中存在hsp模块则传入true // ZRouter.init(true) ZRouter.initialize((config) => { config.isLoggingEnabled = BuildProfile.DEBUG config.isHSPModuleDependent = true }) } ``` 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) => { // 跳转页面 ZRouter.push("harAMainPage") }) Button('toHarBMainPage').onClick((event: ClickEvent) => { ZRouter.push("harBMainPage") }) Button('toHspCIndex').onClick((event: ClickEvent) => { ZRouter.push("hspCIndex") }) Button('tohspCPage1').onClick((event: ClickEvent) => { ZRouter.push("hspCPage1") }) } } .title('Main') .height('100%') .width('100%') } } ``` 通过ZRouter的pushXX()方法进行页面跳转，参数是@Route装饰器上的name属性值。或者用ZRouter的getNavStack()方法来执行页面跳转。 3、在子页的结构体上使用自定义@Route装饰器描述当前页面，其中name属性是必填的，页面跳转需要用到name值，建议使用驼峰式命名，还有另外三个可选属性分别是： - description：页面描述，没有功能作用； - needLogin：如果页面需要登录，可以将值设置为true，然后在拦截器中做页面重定向到登录页； - extra：额外的值可以通过该属性设置 > @Route和@Service注解的name属性值是支持使用常量，具体使用在下面有介绍 代码如下： ``` @Route({ name: 'hspCPage1', needLogin:true ,extra: 'hsp'}) @Component export struct Page1 { @State message: string = 'Hello World'; build() { NavDestination(){ Column({space:12}){ Button('toHarAPage1').onClick((event: ClickEvent) => { ZRouter.push("harAPage1") }) } } .title('hspCPage1') .width('100%') .height('100%') } } ``` NavDestination是子页面的根容器，不需要在main_pages文件中注册页面路径。 **建议通过ZRouter.getInstance()方式来操作路由的跳转与关闭，使用会更灵活，之前的ZRouter的静态方法依然保留着。** ```typescript ZRouter.getInstance() .setParam("root data") .setLunchMode(LaunchMode.STANDARD) // 启动模式 .enableCrossPageParamReturn() // 跨页面参数返回 .setAnimate(false) .setPopListener((r) => { LogUtil.log("index result: ", r.data ," from: ", r.from); }) .navigation("harAPage3") ``` ### 拦截器 ZRouter支持多个拦截器和全局拦截器，在拦截器中可以做页面跳转的拦截，比如登录拦截，404拦截、埋点、自定义URL路径跳转等。 #### 全局拦截器 全局拦截器提供两种使用方式： - 直接函数回调时的方式； - 类实现接口的方式（建议使用，�