@hadss/hmrouter-plugin/README.md

HMRouter Compiler Plugin

# HMRouterPlugin

HMRouter路由框架编译插件，需要配合[HMRouter](https://ohpm.openharmony.cn/#/cn/detail/@hadss%2Fhmrouter)使用

## 插件简介

HMRouter编译插件是一个基于hvigor的编译插件，用于：

1. 扫描代码中的`@HMRouter`、`@HMInterceptor`、`@HMLifecycle`、`@HMAnimator`、`@HMService`等注解
2. 生成路由表和NavDestination页面代码
3. **自动生成混淆规则**
4. **支持自定义模板**，开发者可以自定义特殊页面的生成
5. **支持插件扩展**，开发者可以在HMRouterPlugin的编译中进行自定义解析

## 插件安装与配置

### 工程级配置

在工程的`hvigor/hvigor-config.json`文件中添加路由编译插件：

```json5
{
  "dependencies": {
    "@hadss/hmrouter-plugin": "^1.2.0-beta.0"  // 使用最新版本
  },
  // ...其余配置
}
```

修改工程根目录下的`hvigorfile.ts`，使用路由编译插件

```typescript
// 工程根目录/hvigorfile.ts
import { appTasks } from '@ohos/hvigor-ohos-plugin';
import { appPlugin } from "@hadss/hmrouter-plugin";

export default {
  system: appTasks,
  plugins: [appPlugin({ ignoreModuleNames: [ /** 不需要扫描的模块 **/ ] })]
};
```

### 模块级配置

在使用HMRouter的模块中单独配置路由编译插件，修改模块目录下的`hvigorfile.ts`：

```typescript
// entry/hvigorfile.ts  entry模块的hvigorfile.ts
import { hapTasks } from '@ohos/hvigor-ohos-plugin';
import { modulePlugin } from '@hadss/hmrouter-plugin';

export default {
  system: hapTasks,
  plugins: [modulePlugin()] // 使用HMRouter标签的模块均需要配置，与模块类型保持一致
}
```

## 配置文件详解

在项目根目录或模块目录创建`hmrouter_config.json`文件，配置插件行为：

```json5
{
  // 扫描目录配置，如果不配置则扫描src/main/ets目录
  "scanDir": [
    "src/main/ets/components",
    "src/main/ets/interceptors"
  ],
  
  // 是否保留生成文件，默认为false
  "saveGeneratedFile": false,
  
  // 是否自动配置混淆规则，默认为false
  "autoObfuscation": false,
  
  // 默认模板文件，不配置时使用插件内置模板
  "defaultPageTemplate": "./templates/defaultTemplate.ejs",
  
  // 特殊页面模版文件，匹配原则支持文件通配符
  "customPageTemplate": [
    {
      "srcPath": [
        "**/component/Home/**/*.ets"
      ],
      "templatePath": "templates/home_shopping_template.ejs"
    },
    {
      "srcPath": [
        "**/live/**/*.ets"
      ],
      "templatePath": "templates/live_template.ejs"
    }
  ]
}
```

### 配置选项说明

| 配置项                 | 类型      | 是否必填 | 说明                                                                                                                                                                      |
|---------------------|---------|------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| scanDir             | array   | 否    | 指定扫描当前模块路径，默认值为`src/main/ets`                                                                                                                                           |
| saveGeneratedFile   | boolean | 否    | 默认为 false，不保留插件自动生成的代码，如果需要保留，需要设置为 true                                                                                                                                |
| autoObfuscation     | boolean | 否    | 默认为 false，不自动配置混淆规则，只会生成`hmrouter_obfuscation_rules.txt`文件帮助开发者配置混淆规则；如果设置为 true，会自动配置混淆规则，并在编译完成后删除`hmrouter_obfuscation_rules.txt`文件，详细说明请参考[混淆配置](Obfuscation.md)文档。 |
| defaultPageTemplate | string  | 否    | 默认模版路径，相对于hmrouter_config.json文件，例如：`./templates/defaultTemplate.ejs`                                                                                                   |
| customPageTemplate  | object  | 否    | srcPath为匹配的代码文件路径，支持通配符，templatePath为模版路径，可以实现不同的代码使用不同的模版来生成                                                                                                           |

### 配置文件读取规则

> 配置文件会自动合并，读取优先级为 模块 > 工程 > 默认
> 
> 优先使用本模块内的配置，如果没有配置，则使用工程根目录配置，若都找不到则使用默认配置

> 1.0.0-rc.6 版本开始，支持混淆配置`autoObfuscation`
> 
> 1.0.0-rc.9 版本开始，支持自定义模版配置`customPageTemplate`

## 自定义模板使用

在 `HMRouterPlugin` 中，EJS模板用于生成动态页面或组件，可以在模板文件中使用 EJS 的语法

[自定义模板使用场景](https://gitcode.com/openharmony-sig/ohrouter/blob/master/docs/Scene.md#%E8%87%AA%E5%AE%9A%E4%B9%89%E6%A8%A1%E6%9D%BF)

> EJS语法可阅读参考[官网链接](https://github.com/mde/ejs)

**模板文件示例：**

```ejs
import { <%= componentName %> } from '<%= importPath %>'

@Builder
export function <%= componentName %>Builder(name: string, param: Object) {
  <%= componentName %>Generated()
}

@Component
export struct <%= componentName %>Generated {
  private pageUrl: string = '<%= pageUrl %>'

  build() {
    NavDestination() {
      <%= componentName %>()
    }
    <% if(dialog){ %>.mode(NavDestinationMode.DIALOG)<% } %>
    .hideTitleBar(true)
  }
}
```

> 模板文件中至少需要包含`NavDestination`组件代码和相对应的`build`函数，缺少会导致编译失败或者页面白屏，插件中会内置一套默认模板，其中包含了**页面展示、生命周期注册、转场动画注册**

### 默认模板介绍

插件默认模板根据HMRouter版本不同有两种实现：

#### 1.1.0及以上版本

1.1.0及以上版本使用`NavDestinationHelper`类来处理页面生命周期和手势动画：

```ejs
// auto-generated <%= componentName %>Builder.ets by HMRouter
import <%if(isDefaultExport) {%> <%= componentName %> <% } else {%> { <%= componentName %> } <% } %> from '<%= importPath %>'
import { NavDestinationHelper } from '@hadss/hmrouter';

@Builder
export function <%= componentName %>Builder(name: string, param: Object) {
  <%= componentName %>Generated()
}

export const <%= componentName %>BuilderWrapBuilder = wrapBuilder(<%= componentName %>Builder)

@Component
export struct <%= componentName %>Generated {
  private helper: NavDestinationHelper = new NavDestinationHelper(this);

  build() {
    NavDestination() {
      <%= componentName %>()
    }
    <% if(dialog){ %>.mode(NavDestinationMode.DIALOG)<% } %>
    .hideTitleBar(true)
    .attributeModifier(this.helper.modifier)
    .gestureModifier(this.helper.gestureModifier)
    .onWillAppear(()=>{this.helper.onWillAppear()})
    .onAppear(() => {this.helper.onAppear()})
    .onWillShow(()=>{this.helper.onWillAppear()})
    .onShown(()=>{this.helper.onShown()})
    .onWillHide(()=>{this.helper.onWillHide()})
    .onHidden(()=>{this.helper.onHidden()})
    .onWillDisappear(()=>{this.helper.onWillDisappear()})
    .onDisAppear(()=>{this.helper.onDisAppear()})
    .onReady((ctx)=>{this.helper.onReady(ctx)})
    .onBackPressed(()=> this.helper.onBackPressed())
  }
}
```

#### 1.0.0版本

1.0.0版本使用`TemplateService`类来处理页面生命周期和动画：

```ejs
// auto-generated <%= componentName %>Builder.ets by HMRouter
import <%if(isDefaultExport) {%> <%= componentName %> <% } else {%> { <%= componentName %> } <% } %> from '<%= importPath %>'
import { TemplateService, TranslateOption, ScaleOption, OpacityOption, HMRouterMgr } from '@hadss/hmrouter'

@Builder
export function <%= componentName %>Builder(name: string, param: Object) {
  <%= componentName %>Generated()
}

export const <%= componentName %>BuilderWrapBuilder = wrapBuilder(<%= componentName %>Builder)

@Component
export struct <%= componentName %>Generated {
  @State translateOption: TranslateOption = new TranslateOption()
  @State scaleOption: ScaleOption = new ScaleOption()
  @State opacityOption: OpacityOption = new OpacityOption()
  private pageUrl: string = ''
  private ndId: string = ''
  private navigationId: string = ''

  aboutToAppear(): void {
    this.navigationId = this.queryNavigationInfo()!.navigationId;
    const allPathName = HMRouterMgr.getPathStack(this.navigationId)?.getAllPathName();
    this.pageUrl = allPathName ? allPathName[allPathName.length - 1] : '';
    TemplateService.aboutToAppear(this.navigationId, this.pageUrl, <%= dialog %>,
      this.translateOption, this.scaleOption, this.opacityOption)
  }

  aboutToDisappear(): void {
    TemplateService.aboutToDisappear(this.navigationId, this.pageUrl, this.ndId)
  }

  build() {
    NavDestination() {
      <%= componentName %>()
    }
    <% if(dialog){ %>.mode(NavDestinationMode.DIALOG)<% } %>
    .hideTitleBar(true)
    .gesture(PanGesture()
      .onActionStart((event: GestureEvent) => {
        TemplateService.interactiveStart(this.navigationId, this.ndId, event)
      })
      .onActionUpdate((event: GestureEvent) =>{
        TemplateService.interactiveProgress(this.navigationId, this.ndId, event)
      })
      .onActionEnd((event: GestureEvent) =>{
        TemplateService.interactiveFinish(this.navigationId, this.ndId, event)
      })
      .onActionCancel(() =>{
        TemplateService.interactiveCancel(this.navigationId, this.ndId)
      })
    )
    .translate(this.translateOption)
    .scale(this.scaleOption)
    .opacity(this.opacityOption.opacity)
    .onAppear(() => {
      TemplateService.onAppear(this.navigationId, this.pageUrl, this.ndId)
    })
    .onDisAppear(() => {
      TemplateService.onDisAppear(this.navigationId, this.pageUrl, this.ndId)
    })
    .onShown(() => {
      TemplateService.onShown(this.navigationId, this.pageUrl, this.ndId)
    })
    .onHidden(() => {
      TemplateService.onHidden(this.navigationId, this.pageUrl, this.ndId)
    })
    .onWillAppear(() => {
      TemplateService.onWillAppear(this.navigationId, this.pageUrl)
    })
    .onWillDisappear(() => {
      TemplateService.onWillDisappear(this.navigationId, this.pageUrl, this.ndId)
    })
    .onWillShow(() => {
      TemplateService.onWillShow(this.navigationId, this.pageUrl, this.ndId)
    })
    .onWillHide(() => {
      TemplateService.onWillHide(this.navigationId, this.pageUrl, this.ndId)
    })
    .onReady((navContext: NavDestinationContext) => {
      this.ndId = navContext.navDestinationId!
      TemplateService.onReady(this.navigationId, this.pageUrl, navContext)
    })
    .onBackPressed(() => {
      return TemplateService.onBackPressed(this.navigationId, this.pageUrl, this.ndId)
    })
  }
}
```

### 版本差异说明

1. **NavDestinationHelper vs TemplateService**：
   - 1.1.0版本中，`TemplateService`被`NavDestinationHelper`类替代
   - `NavDestinationHelper`采用实例化方式使用，而`TemplateService`则采用静态方法调用
   - `NavDestinationHelper`通过`modifier`和`gestureModifier`简化了动画和手势处理

2. **生命周期处理**：
   - 1.1.0版本使用更简洁的代理模式处理生命周期回调
   - 1.0.0版本需要手动调用每个静态方法并传递参数

3. **动画处理**：
   - 1.1.0版本通过`attributeModifier`和`gestureModifier`处理动画
   - 1.0.0版本需要手动管理`TranslateOption`、`ScaleOption`和`OpacityOption`

> 注意：自定义模板时，请确保使用的API版本与HMRouter版本匹配。1.1.0及以上版本应使用NavDestinationHelper，1.0.0版本应使用TemplateService。

### 模板变量

| 属性                | 描述              |
|-------------------|-----------------|
| pageUrl           | 标签中配置的pageUrl的值 |
| importPath        | 原组件的导入路径        |
| componentName     | 原组件名            |
| dialog            | 是否dialog页面      |

### 文件通配符说明

- `*`：匹配任意数量的字符，不包括目录分隔符
- `**`：匹配任意数量的字符，包括目录分隔符
- `?`：匹配单个字符
- `[abc]`：匹配方括号中的任意一个字符
- `[a-z]`：匹配a到z范围内的任意一个字符
- `{a,b,c}`：匹配花括号中的任意一个模式
- `!`：否定模式，排除匹配的文件

### 匹配优先级

- customPageTemplate > defaultPageTemplate > 库中携带的模板
- 如遇到customPageTemplate中的多个srcPath都能匹配上，优先取前面的模板文件

## 插件扩展

HMRouterPlugin提供了完善的扩展机制，允许开发者在插件执行的不同阶段注入自定义逻辑。通过继承`PluginExtension`抽象类并实现特定方法来扩展功能。

### 编写扩展类

创建一个继承自`PluginExtension`的类，并实现需要的生命周期方法：

```typescript
// MyCustomExtension.ts
import { PluginExtension, ExtensionContext } from '@hadss/hmrouter-plugin';
import { SourceFile } from 'ts-morph';

export class MyCustomExtension extends PluginExtension {
  // 可选：扩展名称，主要用于调试日志
  get name(): string {
    return 'MyCustomExtension';
  }
  
  // hmrouter_extension初始化阶段后执行
  afterInitialize(context: ExtensionContext): void {
    console.log('Extension initialization');
    // 初始化设置逻辑
  }
  
  // 注解分析阶段后执行
  afterAnnotationAnalysis(sourceFile: SourceFile, filePath: string, context: ExtensionContext): void {
    // 在源文件上执行分析逻辑
    console.log(`Analyzing file: ${filePath}`);
    // 可以提取信息并添加到上下文
    const results = [
      // 分析结果...
    ];
    
    // 将结果添加到上下文
    context.addAnalyzeResults(results);
  }
  
  // 代码生成阶段后执行
  afterCodeGeneration(context: ExtensionContext): void {
    // 自定义代码生成逻辑
    console.log('Custom code generation');
  }
  
  // 其它阶段方法...
  // afterRouterMapBuilding
  // afterConfigUpdate
  // afterObfuscationProcess
  // afterResourceProcess
  // afterCompletion
}
```

> 如需要进行自定义解析，请将`ts-morph`加入到`hvigor-config.json`依赖中

### 注册扩展
```typescript
import { appTasks } from '@ohos/hvigor-ohos-plugin';
import { registerPluginExtension } from '@hadss/hmrouter-plugin';
import { MyCustomExtension } from './MyCustomExtension';
import { appPlugin } from "@hadss/hmrouter-plugin";

// 注册扩展实例
registerPluginExtension(new MyCustomExtension());

export default {
  system: appTasks,
  plugins: [appPlugin({ ignoreModuleNames: [] })]
};
```

> 更多使用介绍请访问[插件扩展](https://gitcode.com/openharmony-sig/ohrouter/blob/master/docs/PluginExtension.md)

## 编译产物

HMRouter编译插件生成的文件包括：

1. **路由表文件**：`src/main/resources/base/profile/hm_router_map.json`，包含所有页面的路由信息
2. **rawfile资源文件**：`src/main/resources/rawfile/hm_router_map.json`, 包含所有页面的路由信息与本次编译中包含是hsp模块包名信息
3. **页面代码文件**：`src/main/ets/generated/HM{PageName}{Hash}.ets`，为每个页面生成的NavDestination包装代码, 命名格式为`HM + 组件名 + pageUrl的hash值`
4. **混淆规则文件**：`hmrouter_obfuscation_rules.txt`，包含需要保留的类名

在`hmrouter_config.json`中设置`saveGeneratedFile: true`可保留所有编译产物

## 系统版本要求

最低版本：

```text
DevEco Studio 5.0.3.700及以上
hvigor 5.5.1及以上
```

**推荐使用**：

```text
DevEco Studio 5.0.3.800及以上
hvigor 5.7.3及以上
```

> 低于DevEco Studio 5.0.3.800(hvigor 5.7.3)可能会导致远程的 HSP 中定义的 HMRouter 标签与路由表失效，会有如下 WARN 日志
>
> ```
> [HMRouterPlugin] Your DevEco Studio version less than 5.0.3.800, may cause remote hsp dependencies get failed
> ```

## 更新日志

### 1.2.0-beta.1 (2025.07.29)

- 修复相同组件名称冲突的问题
- 修复默认模版的问题
- 修复ohosTest编译错误
- 修复oh-package.json5含注解的编译错误
- 修复自动混淆问题

### 1.2.0-beta.0 (2025.06.17)

- 新增插件扩展能力
- 修复了路由表生成与hvigor编译流程冲突的问题

### 1.1.0-beta.0 (2025.04.11)

- 更新了自定义模版，支持原生组件接入

### 1.0.0-rc.9 (2024.10.09)

- 支持自定义页面模版配置`customPageTemplate`

### 1.0.0-rc.6 (2024.09.27)

- 新增自动混淆配置参数`autoObfuscation`，开启可以自动配置HMRouter混淆白名单

## 常见问题

### 编译失败，提示重复的routerMap对象名称

```
hvigorERROR: Duplicate 'routerMap' object names detected.
     
* Try the following:
> Change the 'routerMap' object names listed below under routerMap in the respective router configuration files. Make sure the names are unique across the current module and the modules on which it depends.
{"home":["BootView"]}
```

解决方案：
1. 检查是否有多个页面使用了相同的pageUrl
2. 升级DevEco Studio版本，已知Build Version: 5.0.3.600版本会偶现该问题
3. 清理项目并重新编译

### 编译成功但找不到生成的文件

解决方案：
1. 在`hmrouter_config.json`中设置`saveGeneratedFile: true`，保留生成文件
2. 检查生成的文件是否正确，通常位于`src/main/ets/generated`目录
3. 确认编译插件配置正确，每个使用HMRouter的模块都需要配置对应的插件

### 多target问题

出现编译报错`The "to" argument must be of type string. Received undefined`

解决方案：
1. 确保一个`target`对应一个`product`，不要出现多余的`target`定义
2. 不要有一个模块中多个`target`给一个`product`的情况
3. 遵循官方说明：同一个module的不同target不能打包到同一个product中

## 使用建议

1. **指定扫描目录**：配置`scanDir`，减少编译时间
2. **开发阶段保留生成文件**：设置`saveGeneratedFile: true`，方便排查问题
3. **启用自动混淆配置**：设置`autoObfuscation: true`，自动处理混淆规则
4. **使用自定义模板**：根据项目需求，自定义页面模板
5. **模块类型与插件类型匹配**：确保使用正确的插件类型
6. **定期清理生成文件**：在发布前，设置`saveGeneratedFile: false`，清理生成文件
7. **注意版本兼容性**：确保自定义模板与HMRouter版本匹配

## HMRouter路由框架使用

详见[@hadss/hmrouter](https://ohpm.openharmony.cn/#/cn/detail/@hadss%2Fhmrouter)