README.md · 钟睿/AppRouterProject

![输入图片说明](D1389CBB-4FFB-44a4-A6B1-3A0B6A2B5DF1.png)
# AppRouter
## 简介
AppRouter通过Navigation+hvigor插件实现的动态路由方案，便于项目各模块之间的页面跳转

## 下载安装
```text
ohpm install @zhongrui/app_router
```
### 或者[下载har](https://gitee.com/zhongrui_developer/AppRouterProject/raw/dev/lib/AppRouter.har)
<br/>

#### 该路由方案实现的效果：
entry模块依赖A模块(Har)、B模块(Har)、C模块(Hsp)，ABC三个模块互相不依赖，可实现这4个模块之间互相进行页面跳转(达到解耦的效果)

比如： 
1. entry模块页面跳转至->entry模块、A模块、B模块、C模块页面

A模块页面跳转至->entry模块、A模块、B模块、C模块页面

. . .
2. 提供拦截器，在跳转某个页面时，可以根据业务需求在页面跳转前拦截(如果跳转某个不存在的组件，拦截器不会触发，避免处理无效逻辑)
3. 根据注解参数可配置跳转目标页面前是否需要验证登录状态，在未登录的情况下，跳转目标页面前会执行登录操作
4. 根据注解参数可配置在步骤3执行登录操作之后，是否继续执行登录前的页面跳转动作
5. App启动时可以配置不用加载所有模块的路由表数据（相对启动时加载所有路由表数据，不加载可以避免增加启动耗时问题)，在页面跳转时会动态加载，然后加入缓存中，下次跳转直接读缓存

## 首先展示跳转逻辑与目标页面定义方式
1. 这是封装之后具体使用时Navigation根视图和页面跳转代码
```typescript
@Entry
@Component
struct Index {
  @Builder
  getBuilder(path: string) {
    //此处写法固定，不会随着组件数量增加而增加额外逻辑
    AppRouter.getBuilderByPath(path)?.builder(path as Object)
  }
  build() {
    //Navigation这里记得传入AppRouter.getRootStack()，否则跳转不生效
    Navigation(AppRouter.getRootStack()) {
         
      Button("跳转目标页面").onClick(() => {
         
        //1：通过路由跳转目标页面
        AppRouter.push("entry/target")
         
      })
         
    }.hideTitleBar(true)
    .navDestination(this.getBuilder)
  }
}
```
2. 定义目标页面的代码(不用@Entry修饰，不用在main_pages.json文件里配置组件路径)

**重点注意：1：组件需要export  2:组件名需要和文件名保持一致**
```typescript
import { RouterPath } from '@zhongrui/app_router/Index';
//此处path只能用字面量，不能用变量或者外部类定义的常量
@RouterPath({ path: "entry/target"})
@Component
export struct Target {
  build() {
    NavDestination() {
      Text("目标页面")
    }.hideTitleBar(true)
    .onAppear(()=>{
      //组件挂载时触发
    })
    .onDisAppear(()=>{
      //组件卸载时触发
    })
    .onShown(()=>{
      //页面显示时触发,相当于@Entry修饰的组件onPageShow()
    })
    .onHidden(()=>{
      //页面隐藏时触发,相当于@Entry修饰的组件onPageHide()
    })
    .onBackPressed(()=>{
      //如果返回true,则会拦截返回键
      return false
    })
  }
}

```

## 配置教程
如果不想看详细说明，只想知道项目使用时的简单配置->[简单配置](https://gitee.com/zhongrui_developer/AppRouterProject/blob/master/README_simple.md)

### 1. 依赖app_router库
在每个模块的oh-package.json5配置
```json
{  
   "dependencies": {
   //配置完记得点击右上角的Install Now
   "@zhongrui/app_router": "^1.0.4"
  }
}
```

### 2. 打开entry类型模块内的build-profile.json5文件
在节点buildOption->arkOptions->runtimeOnly->packages字段下添加所有被entry模块依赖且使用动态路由的模块名
```json
{
  "buildOption": {
    "arkOptions": {
      "runtimeOnly": {
        "packages": [
           //按照实际情况添加entry模块依赖的所有模块名
          "HarA",
          "HspB"
        ]
      }
    }
  }
}
```
### 3. 在项目工程hvigor目录中的hvigor-config.json5文件中配置

[**查看app_router_hvigor_plugin版本号**](https://gitee.com/zhongrui_developer/AppRouterProject/blob/master/hvigor_plugin/AppRouterPlugin/version_name.md)
```text
{
  "dependencies": {
    //1：配置安装插件(配置完记得点击右上角的Install Now)
    "app_router_hvigor_plugin": "版本号"
  }
}
```
或者 [点击下载插件包](https://gitee.com/zhongrui_developer/AppRouterProject/raw/master/hvigor_plugin_lib/app_router_hvigor_plugin-1.0.8.tgz)
```text
{
  "dependencies": {
    //1：配置安装插件(配置完记得点击右上角的Install Now)
    "app_router_hvigor_plugin": "file:../插件包目录",
  }
}
```
 
### 4. 配置各个模块的hvigorfile.ts文件(不是项目工程根目录下的hvigorfile.ts)
只需要复制两处代码，其他地方不要复制，防止出错
```text
//entry类型
import { hapTasks } from '@ohos/hvigor-ohos-plugin';
//非entry类型
import { harTasks } from '@ohos/hvigor-ohos-plugin';

//1：导入插件包和配置类(直接复制该行代码)
import { AppRouterPlugin } from "app_router_hvigor_plugin"

export default {
  system: hapTasks,//entry类型：hapTasks， 非entry类型：harTasks
  
  //2：注册插件AppRouterPlugin()(直接复制AppRouterPlugin方法块)
  plugins: [AppRouterPlugin({
    //3:(重点注意)entry类型的模块传true，非entry类型传false
    "isEntry": true,
    "routerDependencyName":"@zhongrui/app_router",
    //扫描配置@RouterPath装饰器的组件所在的具体路径，可以加快编译速度,不配置scanPackagePath参数，默认路径为："src/main/ets"
    "scanPackagePath": ["src/main/ets"]
  })]
}

```

##### 参数说明AppRouterPlugin()
```text
{
    // 当前module是否是entry类型
    isEntry: false,
    // 当前module需要扫描的包路径(建议配置使用@RouterPath装饰器的组件所在的具体路径，可以加快编译速度)，不设置默认扫描模块下面所有文件目录
    // 如果配置["src/main/ets/xxx/view", "src/main/ets/xxx/pages"]，则会扫描该路径内的所有文件
    scanPackagePath: [],
    // 当前module需要扫描的文件夹名称，比如["pages","page","view"],则会扫描模块src/main/ets内的所有pages，page，view目录以及子目录的文件
    scanPackageName: [],
    // 当前module不需要扫描的路径或者文件
    ignorePath: [],
    
    //以下全是默认配置，一般不用特意修改
    // 路由注解名称
    annotation: "RouterPath",
    // 是否开启调试模式，true:开启编译阶段输出日志
    debug: false,
    // 当前module自动生成注册组件方法的文件路径
    generatePath: "src/main/ets/_generated",
    // 当前module自动生成注册组件方法的文件名字
    generateName: "AutoRouterBuilder.ets",
    // 当前module自动生成路由表的文件名字
    generateMapName: "AutoRouterMap.ets",
    //被Entry模块依赖时设置的别名,例如："@test/harA": "file:../HarA",此时需要设置entryDependencyName:"@test/harA"
    entryDependencyName?: string,

//import { AppRouter } from '@zhongrui/app_router/Index',
    //依赖的路由模块名称
    routerDependencyName: "@zhongrui/app_router",
    //路由名称
    routerClassName: "AppRouter",
}
```

## 使用说明(配置完成后，记得build一下项目)
### 1.初始化
entry模块oh-package.json5文件依赖的module名称必须在初始化时传入

比如entry模块依赖了HarA，HarB，HspC三个模块，

那么AppRouter.init初始化的第一个参数就是：["HarA","B","@ohos/HspC"]

如果被依赖设置的别名和模块名不一致，比如："B": "file:../HarB"，

则需要在HarB模块的hvigorfile.ts文件AppRouterPlugin()中设置参数entryDependencyName:B
```json
{
   "dependencies": {
      //别名和模块名一致
      "HarA": "file:../HarA",
      //别名和模块名不一致
      "B": "file:../HarB",
      //别名和模块名不一致
      "@ohos/HspC": "file:../HspC"
   }
}
```
```typescript
//固定写法，第一个参数记得根据项目依赖情况设置，其他参数直接复制即可
 AppRouter.init(["HarA","B","@ohos/HspC"], {
   entryMapList: () => getEntryRouterMap(),
   entryBuilder: (group: string, name: string) => {BuildRegister(group, name)},
   debug: false,
   isMultiPacket: true,
   initAllMap:false
 })
```

```text
//参数说明
{
   //entry模块的路由表信息(因为entry类型的module无法动态import自己，模块内一般都是用的相对路径，所以需要主动处理路由表相关逻辑)
   entryMapList: () => getEntryRouterMap(),
   
   //entry模块注册WrappedBuilder逻辑，理由同上
   entryBuilder: (group: string, name: string) => {BuildRegister(group, name)},
   
   //是否打开调试模式
   debug: false
   
   //启动app时是否初始化所有模块的路由map表数据，设置为false不会影响启动时间，页面跳转时会动态加载路由表
   initAllMap: false
   
   //是否是多hap或者工程存在hsp模块，如果项目中存在其他Hap模块或者Hsp模块依赖动态路由库，则设置为true
   isMultiPacket: true
}
```

### 注解说明
@RouterPath({path:"xxx/xxx",des:"组件描述",needLogin:false,autoExecute:false})

1. path参数：代表页面路径，通过路由进行跳转时AppRouter.push(path)传入的参数必须一致才能生效

格式为group/name组合，也可以不设置group，只设置name，比如  path:"home",如果项目页面很多，建议使用group/name格式

2. des:方便开发人员维护，增加的一个组件描述字段，没有实际作用

3. needLogin:跳转到该页面是否需要登录(默认为false)，如果设置为true,

需要配合AppRouter.setLoginCheckListener()使用，下方有对该方法有说明

4. autoExecute：配合needLogin参数使用(默认为false)，如果needLogin和autoExecute都设置为true,那么登录成功之后继续执行登录前的页面跳转逻辑

需要配合AppRouter.setLoginCheckListener()使用，下方有对该方法有说明

### 2.api使用
```typescript
//是否存在路由页面
AppRouter.existBuilder(path).then((result) => {
   //result true:存在，false:不存在
})

//获取NavPathStack，在Navigation根视图设置
let navPathStack:NavPathStack=AppRouter.getRootStack()
        
//页面跳转使用方式和官方api一致
//跳转目标页面
AppRouter.push("entry/main", param, true)
        
//跳转目标页面并设置回传监听
AppRouter.pushForResult("entry/main", param, (result, prePagePath, prePageParam) =>
   //上个页面退出时，使用popAndResult回传
   result:回传的参数
   prePagePath:上一个页面的path
   prePageParam:上一个页面获取的参数
}, true)
        
//返回
AppRouter.pop(true)
        
//返回并回传结果
AppRouter.popAndResult(param, true)
        
//页面替换
AppRouter.replace("entry/main", param, true)
        
//也可以获取跟视图的NavPathStack执行对应的方法
let navPathStack: NavPathStack = AppRouter.getRootStack()
navPathStack...此处省略所有官方api

//如果在Navigation视图内部又嵌套使用了Navigation，通过getStack()获取NavPathStack
AppRouter.getStack("key")
        
//添加拦截器
AppRouter.addInterceptor("key", (path, param, isContinue: () => void) => {
   //如果需要通过接口返回的数据来判断是否需要拦截，可以先返回true拦截掉，等接口响应之后，再调用isContinue() 继续执行之前的页面跳转操作
   path:页面路径
   param:跳转页面的参数
   isContinue:是否继续执行拦截前的页面跳转逻辑
   //返回true拦截页面跳转
   return true
})
        
//移除拦截器
AppRouter.removeInterceptor("key")
        
//监听登录状态
AppRouter.setLoginCheckListener(() => {
   //true:已经登录状态，false:未登录
   return true
})
        
//通知登录操作
AppRouter.setLoginListener((result: (loginSuccess: boolean) => void) => {
   //执行登录操作后，通过result(true) 通知登录成功,
   result(true)
})
```

#### 参考资料
[动态路由Sample](https://gitee.com/harmonyos-cases/cases/tree/master/CommonAppDevelopment/common/routermodule)

#### 开源协议
本项目基于 [MIT license](https://gitee.com/zhongrui_developer/AppRouterProject/blob/master/LICENSE) ，请自由地享受和参与开源。

钟睿/AppRouterProject

简介

发行版

贡献者

语言

近期动态

钟睿/AppRouterProject .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

语言

近期动态

搜索帮助

钟睿/AppRouterProject