# HMRouter

**Repository Path**: kymjs/hmrouter

## Basic Information

- **Project Name**: HMRouter
- **Description**: HMRouter作为应用内页面跳转场景解决方案，聚焦应用内ArkUI页面的跳转逻辑。
HMRouter底层对系统Navigation进行封装，集成了Navigation、NavDestination、NavPathStack的系统能力，提供了可复用的路由拦截、页面生命周期、自定义转场动画，并且在传参、额外的生命周期、服务型路由方面对系统能力进行了扩展。
帮助开发者更好的进行模块间解耦。
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 51
- **Created**: 2025-03-21
- **Last Updated**: 2025-03-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HMRouter

HMRouter作为应用内页面跳转场景解决方案，聚焦解决应用内ArkUI页面的跳转逻辑。

HMRouter底层对系统Navigation进行封装，集成了Navigation、NavDestination、NavPathStack的系统能力，提供了可复用的路由拦截、页面生命周期、自定义转场动画，并且在跳转传参、额外的生命周期、服务型路由方面对系统能力进行了扩展。

目的是让开发者在开发过程中无需关注Navigation、NavDestination容器组件的相关细节及模板代码，屏蔽跳转时的判断逻辑，降低拦截器、自定义转场动画实现复杂度，更好的进行模块间解耦。

## 特性

- 基于注解声明路由信息
- **注解参数支持使用字符串常量定义**
- **页面路径支持正则匹配**
- 支持Har、Hsp、Hap
- 支持Navigation路由栈嵌套
- 支持服务型路由
- **跳转时支持URL参数自动解析**
- 支持路由拦截器（包含全局拦截、单页面拦截、跳转时一次性拦截）
- 支持生命周期回调（包含全局生命周期、单页面生命周期、NavBar生命周期）
- 内置转场动画（普通页面、Dialog），可配置方向、透明度、缩放，支持交互式转场动画，同时支持配置某个页面的转场动画、跳转时的一次性动画
- **提供更多高阶转场动画，包括一镜到底等**（需依赖`@hadss/hmrouter-transitions`）
- 支持配置自定义页面模版，可以更灵活的生成页面文件
- 支持Dialog、单例类型页面
- **支持混淆白名单自动配置**

## 依赖系统版本

SDK: Ohos_sdk_public 5.0.0.71 (API 12 Release)

## 项目版本信息

当前最新版本

| 名称                                                                                                   | 说明             | 类型   | 版本号         | 发布状态 |
|------------------------------------------------------------------------------------------------------|----------------|------|-------------|------|
| [@hadss/hmrouter](https://ohpm.openharmony.cn/#/cn/detail/@hadss%2Fhmrouter)                         | 路由框架           | 运行时库 | 1.0.0-rc.11 | 已发布  |
| [@hadss/hmrouter-transitions](https://ohpm.openharmony.cn/#/cn/detail/@hadss%2Fhmrouter-transitions) | 高阶转场动画库，依赖路由框架 | 运行时库 | 1.0.0-rc.11 | 已发布  |
| [@hadss/hmrouter-plugin](https://www.npmjs.com/package/@hadss/hmrouter-plugin)                       | 编译插件           | 编译插件 | 1.0.0-rc.11 | 已发布  |

> 受准出流程的影响，版本发布到中心仓时间较长，在未发布时需要使用文件安装方式使用

### 使用ohpm安装依赖

```shell
ohpm install @hadss/hmrouter
ohpm install @hadss/hmrouter-transitions
```

### 使用文件安装

SDK、编译插件可以在代码仓的`artifacts`文件夹获取，拷贝到工程目录的`libs`文件夹

修改`oh-package.json5`

```json5
{
  "dependencies": {
    "@hadss/hmrouter": "file: ../libs/HMRouterLibrary-${version}.har",
    "@hadss/hmrouter-transitions": "file: ../libs/HMRouterTransitions-${version}.har"
  }
}
```

修改工程的`hvigor/hvigor-config.json`文件

```json5
{
  "dependencies": {
    "@hadss/hmrouter-plugin": "file: ../libs/hadss-hmrouter-plugin-${version}.tgz"
    // 使用npm仓版本号
  }
}
```

## HMRouter路由框架使用说明

[查看详情](HMRouterLibrary/README.md)

## HMRouterPlugin编译插件使用说明

[查看详情](HMRouterPlugin/README.md)

## HMRouterTransitions高阶转场动画使用说明

[查看详情](HMRouterTransitions/README.md)

## 自定义模版使用说明

[查看详情](docs/CustomTemplate.md)

## 自定义转场动画使用说明

[查看详情](docs/CustomTransition.md)

## 应用内ArkUI页面跳转场景解决方案

[查看详情](docs/Scene.md)

## Sample介绍

本项目包含[Sample示例代码](https://gitee.com/harmonyos_samples/HMRouter)，通过购物App展示`HMRouter`在页面跳转场景中的使用

## 更多示例

[查看详情](HMRouterExamples)

## FAQ

[查看详情](docs/FAQ.md)

## 原理介绍

[查看详情](https://developer.huawei.com/consumer/cn/forum/topic/0207153170697988820?fid=0109140870620153026)

## 贡献代码

使用过程中发现任何问题都可以提 [Issue](https://gitee.com/hadss/hmrouter/issues) ，当然，也非常欢迎发 [PullRequest](https://gitee.com/hadss/hmrouter/pulls) 共建。

## 开源协议

本项目基于 [Apache License 2.0](LICENSE) ，请自由地享受和参与开源。