ZRouter 动态路由框架

徐建国

发布于 2025-01-10 12:16:25

9900

代码可运行

文章被收录于专栏：个人路线个人路线

运行总次数：0

代码可运行

介绍

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

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

使用十分简单，没有繁琐的配置，两行代码就可以完成页面的跳转，如下:

ZRouter 已上架录入到华为鸿蒙生态伙伴组件专区[1]

router-register-plugin 编译插件

下载安装

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

  "dependencies": {
//    "router-register-plugin":"file:../plugins/router-register-plugin-1.0.2.tgz"
    "router-register-plugin":"1.3.0"
  },

最后记得 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 // 删除无用编译产物
    lifecycleObserverAttributeName: 'xxx' // 可选，设置全局的生命周期实现类在组件上的属性名，默认值是lifecycleObserver

}
export default {
    // 3、添加插件
    plugins:[routerRegisterPlugin(config)]
}

常用的配置字段：

scanDirs：扫描的目录，建议设置可更精准、更快扫描生成文件，如果不设置，默认是扫描 src/main/ets 目录
logEnabled：日志记录开关。
viewNodeInfo：查看节点信息的开关，只有 logEnabled 和 viewNodeInfo 同时开启才会生效
isAutoDeleteHistoryFiles：是否删除无用编译产物；
lifecycleObserverAttributeName：设置全局的生命周期实现类在组件上的属性名，默认值是 lifecycleObserver，若要设置单个页面的名称，可在@ZRoute 注解中的 loAttributeName 属性上设置。

PluginConfig 配置对象还有其他属性，但不建议使用，使用默认值即可。

上面所有路径都是相对模块的 src 目录而言的，是相对路径。最后记得 Sync Now 或重新 build 让配置生效。

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

_generated
route_map.json

ZRouter 的基本使用

下载安装

在每个 har/hsp 模块中，通过 ohpm 工具下载安装库：

ohpm install @hzw/zrouter

页面跳转

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

6a594e11394c60d93983297a1e5322db.png

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()方法中完成初始化

export class AppAbilityStage extends AbilityStage{
  onCreate(): void {
    // 应用HAP首次加载时触发，可以在此执行该Module的初始化操作（例如资源预加载、线程创建等）。
    // 在module.json5配置文件中，通过配置 srcEntry 参数来指定模块对应的代码路径，以作为HAP加载的入口。
    // 初始化路由
    ZRouter.initialize((config) => {
      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) => {
        // 跳转页面
          ZRouter.push("harAMainPage")
        })
      }
    }
    .title('Main')
    .height('100%')
    .width('100%')
  }
}

通过 ZRouter 的 pushXX()方法进行页面跳转，参数是@Route 装饰器上的 name 属性值。或者用 ZRouter 的 getNavStack()方法来执行页面跳转。

3、在 NavDestination 子页的使用自定义@Route 或@ZRoute 注解描述当前页面，其中 name 属性是必填的，页面跳转需要用到 name 值，建议使用驼峰式命名，还有另外三个可选属性分别是：

description：页面描述，没有功能作用；
needLogin：如果页面需要登录，可以将值设置为 true，然后在拦截器中做页面重定向到登录页；
extra：额外的值可以通过该属性设置

@Route/@Service/@ZAttribute/@ZLifecycle 等自定义注解上的 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%')

  }
}

建议通过 ZRouter.getInstance()方式来操作路由的跳转与关闭，使用会更灵活简洁，之前的 ZRouter 的静态方法依然保留着，在 1.2.0 版本起将标记为过期状态了。

 ZRouter.getInstance()
  .setParam("root data")
  .setLunchMode(LaunchMode.STANDARD) // 启动模式
  .enableCrossPageParamReturn() // 跨页面参数返回
  .setAnimate(true)
  .setPopListener((r) => {
    LogUtil.log("index result: ", r.data ," from: ", r.from);
  })
  .navigation("harAPage3")

拦截器

ZRouter 支持多个拦截器和全局拦截器，在拦截器中可以做页面跳转的拦截，比如登录拦截，404 拦截、埋点、自定义 URL 路径跳转等。

全局拦截器

全局拦截器提供两种使用方式：

直接函数回调时的方式；
类实现接口的方式（建议使用，功能更全面），支持字面量对象和 new 创建的对象。

函数回调的方式，代码示例：

@Entry
@Component
struct Index {
  aboutToAppear(): void {
    ZRouter.setGlobalInterceptor((info) => {
      if (info.notRegistered) {
        return
      }
      let isLogin = AppStorage.get<Boolean>("isLogin")
      if (info.needLogin && !isLogin) {
        let param = ZRouter.getParamByName(info.data?.name ?? "")
        ZRouter.redirectForResult2("LoginPage", param, (data) => {
            if (data.result) {
              // 登录成功
              promptAction.showToast({ message: `登录成功` })
              return true // 返回true 则继续跳转登录前的页面
            }
            return false
          })
      }
    })

  }

}

类实现接口的方式，代码示例：

export class GlobalNavigateInterceptor implements  IGlobalNavigateInterceptor{
  onRootWillShow?: ((fromContext: NavDestinationContext) => void) | undefined = (fromContext) => {
    console.log("IInterceptor Global onRootWillShow: ", fromContext.pathInfo.name)
  }
  onPageWillShow?: ((fromContext: NavDestinationContext, toContext: NavDestinationContext) => void) | undefined = (from ,to)=>{
    console.log("IInterceptor Global onPageWillShow: ", from, to.pathInfo.name, to.pathInfo.param)
  }

  onNavigate?: ((context: InterceptorInfo) => void) | undefined = (info)=>{
    if (info.notRegistered) return
    console.log("IInterceptor Global onNavigate: ", info.name)

    let isLogin = AppStorage.get<boolean>("isLogin")
    if (info.isNeedLogin && !isLogin) {
      let param = info.param
      ZRouter.redirectForResult2<boolean>("LoginPage", param, (data) => {
        if (data.data) {
          // 登录成功
          promptAction.showToast({ message: `登录成功` })
          return true // 返回true 则继续跳转登录前的页面
        }
        return false
      })
    }

  }
}

// 添加拦截器
ZRouter.setGlobalInterceptor(new GlobalNavigateInterceptor())

info.notRegistered()方法判断当前页面是否注册，如果没有注册，将使用 ZRouter.redirect() 方法来重定向到 404 页面；通过 ZRouter.redirectForResult() 方法来重定向到登录页面，这个方法接受一个回调函数，该回调函数会在用户登录成功或失败后被调用，在回调函数内部，使用 data.result 判断是否登录，如果登录成功了给回调函数 return true 来指示继续执行登录前的页面跳转。如果登录失败，或者用户取消登录，回调函数将返回 false，表示不跳转。

登录页面代码示例：

@Route({ name: 'LoginPage'})
@Component
export struct LoginPage{

  build() {
    NavDestination(){
       Column({space:15}){
         Button('登录成功').onClick((event: ClickEvent) => {
            // 模拟登录
           AppStorage.setOrCreate<boolean>('isLogin', true)
           ZRouter.finishWithResult<boolean>(true)
         })
       }
       .width('100%')
       .height('100%')
    }
      .width('100%')
      .height('100%')
      .title('LoginPage')
  }
}

在登录成功后通过 ZRouter.finishWithResult()方法携带数据关闭页面，会将状态传递给 redirectForResult2()方法的回调函数。

上面是全局拦截器，每个跳转都会触发，如果需要添加多个拦截器，则可以使用 setInterceptor()方法。

自定义拦截器

自定义拦截器，首先实现接口 IInterceptor，然后使用 setInterceptor()方法注册拦截器，，代码示例如下：

export interface IInterceptor {
  process: ProcessCallback;
  // 优先级，数字越大优先级越高
  priority: number;
}
export type ProcessCallback = (context: InterceptorInfo) => InterceptorInfoOrNull;

在 IInterceptor 的 process()方法中进行页面跳转的拦截，process()方法返回 null 会中断后面的拦截器逻辑，返回 context 则继续执行后面的拦截器逻辑。

代码示例：

aboutToAppear(): void {
  ZRouter.setInterceptor(new UrlInterceptor())
}

export class UrlInterceptor implements IInterceptor {
  // 设置拦截器优先级，数值越大则优先执行
  priority: number = 10000;
  process: (context: InterceptorInfo) => InterceptorInfoOrNull = (context) => {
    return context
  }
}

关于其他 API 的使用请参考 demo。

NavDestination 页面模板化

在介绍基本使用的流程中，我们知道每个页面都需要通过 NavDestination 来包裹，这样会造成代码的冗余，因此可通过 ZRouter 的模板化能力将 NavDestination 层去除。

具体使用见详细文档[2]

自定义 URL 路径跳转

在项目中一般会设计一套统一的 URL 路径跳转规范，通过 URL 路径跳转到不同原生页面。比如下面的 URL 路径：

hzw://hello?id=69&name=harAPage3

获取 URL 路径上的 name 参数进行跳转原生页面，可以设置一个拦截器来拦截 URL 路径跳转。代码示例：

跳转：

Button('https://www.baidu.com?id=66&name=hspCIndex').onClick((event: ClickEvent) => {
       ZRouter.getInstance()
         .navigation("https://www.baidu.com?id=66&name=hspCIndex")
    })

Button('hzw://hello?id=69&name=harAPage3').onClick((event: ClickEvent) => {
  ZRouter.getInstance()
    .navigation("hzw://hello?id=69&name=harAPage3")
})

拦截器：

export class UrlInterceptor implements IInterceptor {
  // 设置拦截器优先级，数值越大则优先执行
  priority: number = 10000;
  process: (context: InterceptorInfo) => InterceptorInfoOrNull = (context) => {
    console.log("IInterceptor process: ", this.priority , context.name)
    // 自定义URL路径是没有注册的
    if (context.notRegistered) {
      // 如果是URL路径跳转
      if (this.isLink(context.name)) {
        // 拦截到URL路径跳转，进行处理
        const map = this.parseQueryString(context.name)
        const name = map.get('name')
        if (name) {
          // 跳转原生页面
          ZRouter.getInstance()
            .setParam(map.get("id"))
            .navigation(name)
        }
      } else {
        ZRouter.getInstance().redirect("PageNotFound2")
      }
      return null // 返回null则拦截掉
    }
    return context
  };

   isLink(str: string): boolean {
    const linkRegex = /^(hzw:\/\/|http:\/\/|https:\/\/|www\.).+/;
    return linkRegex.test(str);
  }


  parseQueryString(queryString: string) {
    let params = new HashMap<string, string>();
    let queryStringWithoutQuestionMark = queryString.split('?')[1];
    if (queryStringWithoutQuestionMark) {
      let keyValues = queryStringWithoutQuestionMark.split('&');
      keyValues.forEach((keyValue) => {
        let pair = keyValue.split('=');
        let key = decodeURIComponent(pair[0]);
        let value = decodeURIComponent(pair[1]);
        params.set(key, value)
      })
    }
    return params;
  }

}

注解上使用静态常量，可跨模块定义

router-register-plugin 插件 1.0.7 版本起，@Route 与@Service 注解的 name 属性可使用静态常量，方便统一管理路由名称；静态常量支持当前模块或跨模块定义，常量的定义模版如下：

export class RouterConstants {
  public static readonly URL_TEST_PAGE: string = "url_test";
  public static readonly HARA_MAIN_PAGE :string = "harAMainPage"
}

如果路由常量在一个公共模块定义，建议在模块的 Index.ets 文件导出，另外 RouterConstants 的文件必须是.ets 后缀，不支持 ts 后缀文件。具体可参考案例[3]

服务路由-模块间通信

服务路由主要用于实现模块之间的通信，模块间是相互独立且不直接依赖于彼此。

1.0.9 版本开始支持，具体使用可见详情文档[4] 或者参考 demo

生命周期函数管理

ZRouter 的组件生命周期管理能力，主要有两个特点：

不影响你原有的生命周期业务逻辑，对 NavDestination 页面保持着零侵入性，整合了组件通用生命周期函数和 NavDestination 生命周期函数
可以让任何一个类具备有与组件的生命周期能力；

具体使用见详细文档[5]

路由转场动画

从 1.1.1 版本起内置了转场动画（平移、旋转、渐变、缩放、高斯模糊），也支持自定义转场动画；具体使用见详细文档[6]

第三方 Navigation 实例使用本库的 API

如果第三方 Navigation 实例使用本库的 API，需要将第三方 Navigation 的 NavPathStack 实例注册到 ZRouter 中，代码示例：

  aboutToAppear(): void {
    // 在合适的时机注册导航栈
    // let s = ZRouter.getNavStackByName(NAV_STACK_NAME)
    ZRouter.registerNavStack(NAV_STACK_NAME, this.stack)
  }

  aboutToDisappear(): void {
    ZRouter.unregisterNavStack(NAV_STACK_NAME)
  }

上面是模拟代码，具体注册的时机需要根据实际情况来定。NAV_STACK_NAME 是一个自定义常量，用于标识导航栈的名称。

页面跳转：

  Column({ space: 15 }) {
      Text(this.msg)
      Button("harAMainPage").onClick((event: ClickEvent) => {
        ZRouter.getInstance(NAV_STACK_NAME)
          .setAnimate(true)
          .setPopListener((v) => {
            this.msg = v.data?.toString() + ' ' + v.from?.toString()
          })
          .navigation("harAMainPage")
      })
    }

把标识导航栈的名称 NAV_STACK_NAME，入参到 ZRouter.getInstance()方法中，就可使用 ZRouter 的 API。

在 ArkUI-X 项目上的使用

router-register 插件在 ArkUI-X 项目的配置有所不同，需要使用者自己手动修改下 hvigorfile.ts 文件，详细见ArkuiX-ZRouter[7]，或者issues IB35F5[8]

混淆

生产环境需要在每个模块的 obfuscation-rules.txt 文件添加混淆配置：

-keep-file-name
_generated
ZR*

工作原理

路由注册流程代码是由插件在编译阶段自动化生成，其原理是不难的，通过 Hvigor 插件扫描指定目录的 ets 文件，递归解析 ets 文件的语法树节点，查找解析注解上的参数，然后将这些信息通过模板引擎生成对应的代码逻辑。

与 Java 注解处理器原理是类似的

ZRouter 库是对 NavPathStack 对进行高度封装的，包括了页面跳转、自定义拦截器、服务路由、生命周期回调、转场动画、NavDestination 模板化等功能，提供了更简洁易用的 API，其中部分思想参考了 Android ARouter[9]路由框架。

编译插件的基本流程图：

接口列表

查看详细文档[10]

FQA

查看详细文档[11]

源码

gitcode：https://gitcode.com/nutpi/ZRouter
gitee：https://gitee.com/common-apps/ZRouter
github：https://github.com/751496032/ZRouter[12]

关于坚果派

最初我们以鸿蒙为基石，不断向同级诸如 ArkUI-X、仓颉，以及同类诸如蓝河、欧拉等扩展，如今在不断努力和尝试下，我们平台已具备了各类产品的优秀开发团队及支持运营的万粉团队。专注于分享的技术包括 HarmonyOS/OpenHarmony、仓颉、ArkUI-X、AI、BlueOS 操作系统。团队成员主要聚集在北京，上海，南京，深圳，广州，苏州、长沙、宁夏等地，目前已为华为、vivo、腾讯、亚马逊以及三方技术社区提供各类咨询 200+。累计粉丝 100+w，孵化开发者 10w+，高校 20+、企业 10+。自研应用 14 款，三方库 70 个，鸿蒙原生应用课程 500+。持续助力鸿蒙仓颉等生态繁荣发展。

三方库列表：https://docs.qq.com/sheet/DYnl1dUxhV21JTWNl?tab=BB08J2

参考资料

[1]

华为鸿蒙生态伙伴组件专区: https://gitee.com/link?target=https%3A%2F%2Fdeveloper.huawei.com%2Fconsumer%2Fcn%2Fmarket%2Flanding%2Fcomponent

[2]

详细文档: https://gitee.com/common-apps/ZRouter/wikis/NavDestination页面模板化能力

[3]

具体可参考案例: https://gitee.com/common-apps/ZRouter/tree/master/library/common

[4]

详情文档: https://gitee.com/common-apps/ZRouter/wikis/服务路由—模块间通信

[5]

详细文档: https://gitee.com/common-apps/ZRouter/wikis/生命周期管理能力

[6]

详细文档: https://gitee.com/common-apps/ZRouter/wikis/路由转场动画

[7]

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

[8]

issues IB35F5: https://gitee.com/common-apps/ZRouter/issues/IB35F5

[9]

ARouter: https://gitee.com/link?target=https%3A%2F%2Fgithub.com%2Falibaba%2FARouter

[10]

查看详细文档: https://gitee.com/common-apps/ZRouter/wikis/接口列表?sort_id=13047549

[11]

查看详细文档: https://gitee.com/common-apps/ZRouter/wikis/FQA

[12]

https://github.com/751496032/ZRouter: https://gitee.com/link?target=https%3A%2F%2Fgithub.com%2F751496032%2FZRouter

本文参与腾讯云自媒体同步曝光计划，分享自微信公众号。

原始发表：2025-01-10，如有侵权请联系 cloudcommunity@tencent.com 删除

函数

框架

路由

生命周期

本文分享自大前端之旅微信公众号，前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

登录后参与评论

0 条评论

热度