@hadss/hmrouter-plugin 1.0.0-rc.9 → 1.1.1-alpha.0

package/README.md

@@ -1,84 +1,150 @@
-## 编译插件配置
+# HMRouterPlugin
 
-1.修改项目的`hvigor/hvigor-config.json`文件，加入路由编译插件
+HMRouter路由框架编译插件，需要配合[HMRouter](https://ohpm.openharmony.cn/#/cn/detail/@hadss%2Fhmrouter)使用
+
+## 插件简介
+
+HMRouter编译插件是一个基于hvigor的编译插件，用于：
+
+1. 扫描代码中的`@HMRouter`、`@HMInterceptor`、`@HMLifecycle`、`@HMAnimator`、`@HMService`等注解
+2. 生成路由表和NavDestination页面代码
+3. 生成混淆规则
+4. 支持自定义模板
+5. 编译时自定义扩展
+
+## 插件安装与配置
+
+### 工程级配置
+
+在工程的`hvigor/hvigor-config.json`文件中添加路由编译插件：
 
 ```json5
 {
   "dependencies": {
-    "@hadss/hmrouter-plugin": "^1.0.0-rc.9" // 使用npm仓版本号
+    "@hadss/hmrouter-plugin": "^1.1.0-beta.0"  // 使用最新版本
   },
-  // ...其他配置
+  // ...其余配置
 }
 ```
 
-2.在模块中引入路由编译插件，修改`hvigorfile.ts`
+### 模块级配置
+
+在使用HMRouter的模块中引入路由编译插件，修改`hvigorfile.ts`：
+
+```extendtypescript
+// entry/hvigorfile.ts  entry模块的hvigorfile.ts
+import { hapTasks } from '@ohos/hvigor-ohos-plugin';
+import { hapPlugin } from '@hadss/hmrouter-plugin';
+
+export default {
+  system: hapTasks,
+  plugins: [hapPlugin()] // 使用HMRouter标签的模块均需要配置，与模块类型保持一致
+}
+
+// libHar/hvigorfile.ts  libHar模块的hvigorfile.ts
+import { harTasks } from '@ohos/hvigor-ohos-plugin';
+import { harPlugin } from '@hadss/hmrouter-plugin';
 
-```typescript
-import { hapTasks } from "@ohos/hvigor-ohos-plugin";
-import { hapPlugin } from "@hadss/hmrouter-plugin";
+export default {
+  system: harTasks,
+  plugins:[harPlugin()]  // 使用HMRouter标签的模块均需要配置，与模块类型保持一致
+}
+
+// libHsp/hvigorfile.ts  libHsp模块的hvigorfile.ts
+import { hspTasks } from '@ohos/hvigor-ohos-plugin';
+import { hspPlugin } from '@hadss/hmrouter-plugin';
 
 export default {
-    system: hapTasks,
-    plugins: [hapPlugin()], // 使用HMRouter框架中标签的模块均需要配置，与模块类型保持一致
-};
+  system: hspTasks,
+  plugins: [hspPlugin()]  // 使用HMRouter标签的模块均需要配置，与模块类型保持一致
+}
 ```
 
-> 请使用与模块类型一致的插件方法，如果模块是 Har 则使用`harPlugin()`, 模块是 Hsp 则使用`hspPlugin()`
+> 注意：模块类型与插件类型必须匹配：
+> - Har模块使用`harPlugin()`
+> - Hsp模块使用`hspPlugin()`
+> - Hap模块使用`hapPlugin()`
+
+## 配置文件详解
 
-3.项目根目录或者模块目录创建路由编译插件配置文件`hmrouter_config.json`（推荐）
+在项目根目录或模块目录创建`hmrouter_config.json`文件，配置插件行为：
 
 ```json5
 {
-  // 如果不配置则扫描src/main/ets目录，对代码进行全量扫描，如果配置则数组不能为空，建议配置指定目录可缩短编译耗时
+  // 扫描目录配置，如果不配置则扫描src/main/ets目录
   "scanDir": [
     "src/main/ets/components",
     "src/main/ets/interceptors"
   ],
-  // 默认为false，调试排除错误时可以改成true，不删除编译产物
+  
+  // 是否保留生成文件，默认为false
   "saveGeneratedFile": false,
-  // 默认为false，不自动配置混淆规则，只会生成hmrouter_obfuscation_rules.txt文件帮助开发者配置混淆文件；如果设置为true，会自动配置混淆规则，并删除hmrouter_obfuscation_rules.txt文件
+  
+  // 是否自动配置混淆规则，默认为false
   "autoObfuscation": false,
+  
   // 默认模板文件，不配置时使用插件内置模板
   "defaultPageTemplate": "./templates/defaultTemplate.ejs",
+  
   // 特殊页面模版文件，匹配原则支持文件通配符
   "customPageTemplate": [
     {
-      "srcPath": ["**/component/Home/**/*.ets"],
-      "templatePath": "./templates/home_shopping_template.ejs"
-    },
-    {
-      "srcPath": ["**/common/**/*.ets"],
-      "templatePath": "./templates/common_template.ejs"
+      "srcPath": [
+        "**/component/Home/**/*.ets"
+      ],
+      "templatePath": "templates/home_shopping_template.ejs"
     },
     {
-      "srcPath": ["**/live/**/*.ets"],
-      "templatePath": "./templates/live_template.ejs"
+      "srcPath": [
+        "**/live/**/*.ets"
+      ],
+      "templatePath": "templates/live_template.ejs"
     }
   ]
 }
 ```
 
-### hmrouter_config.json 配置
+### 配置选项说明
+
+| 配置项                | 类型      | 是否必填 | 说明                                                                                                                                     |
+|---------------------|---------|------|----------------------------------------------------------------------------------------------------------------------------------------|
+| 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为模版路径，可以实现不同的代码使用不同的模版来生成                                                                          |
 
-`hmrouter_config.json`文件用于配置该插件在编译期的行为
+### 配置文件读取规则
 
 > 配置文件读取规则为 模块 > 工程 > 默认
-> 优先使用本模块内的配置，如果没有配置，则找模块目录的上级目录(最多找三层目录，找到则停止)，若找不到则使用默认配置
+> 
+> 优先使用本模块内的配置，如果没有配置，则使用工程根目录配置，若都找不到则使用默认配置
 
 > 1.0.0-rc.6 版本开始，支持混淆配置`autoObfuscation`
+> 
 > 1.0.0-rc.9 版本开始，支持自定义模版配置`customPageTemplate`
 
-| 配置项                 | 类型      | 是否必填 | 说明                                                                                                                                     |
-|---------------------|---------|------|----------------------------------------------------------------------------------------------------------------------------------------|
-| scanDir             | array   | 否    | 指定扫描当前模块路径，默认值为`src/main/ets`                                                                                                          |
-| saveGeneratedFile   | boolean | 否    | 默认为 false，不保留插件自动生成的代码，如果需要保留，需要设置为 true                                                                                               |
-| autoObfuscation     | boolean | 否    | 默认为 false，不自动配置混淆规则，只会生成`hmrouter_obfuscation_rules.txt`文件帮助开发者配置混淆规则；如果设置为 true，会自动配置混淆规则，并在编译完成后删除`hmrouter_obfuscation_rules.txt`文件 |
-| defaultPageTemplate | string  | 否    | 默认模版路径，相对于hmrouter_config.json文件，例如：`./templates/defaultTemplate.ejs`                                                                  |
-| customPageTemplate  | object  | 否    | srcPath为匹配的代码文件路径，支持通配符，templatePath为模版路径，可以实现不同的代码使用不同的模版来生成                                                                          |
+## 多模块配置
+
+在多模块项目中，每个使用HMRouter的模块都需要配置插件。 
+
+### 方式一：每个模块单独配置
+
+在每个模块的根目录下创建`hmrouter_config.json`文件，分别配置。
+
+### 方式二：共享配置
+
+在项目根目录创建`hmrouter_config.json`文件，所有模块共享配置。
+
+如果需要为不同模块指定不同的配置，可以在模块根目录创建`hmrouter_config.json`文件，覆盖共享配置。
+
+> 注意：当前多模块配置时不会做字段合并，即模块配置会直接覆盖工程配置
 
 ## 自定义模板使用
 
-在 `HMRouterPlugin` 中，EJS模板用于生成动态页面或组件，你可以在模板文件中使用 EJS 的语法
+在 `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)
 
@@ -110,30 +176,79 @@ export struct <%= componentName %>Generated {
 
 ### 默认模板介绍
 
-插件默认会根据如下模板来生成`NavDestination`页面代码，如有自定义模板的需求，建议先阅读内置模板的介绍在做更改，书写自定义模板时建议在内置模板基础上添加代码，删除内置模板相关代码可能会导致**编译失败、生命周期生效、转场动画失效等问题**。
+插件默认模板根据HMRouter版本不同有两种实现：
+
+#### 1.1.0及以上版本
 
-**默认模版`viewBuilder.ejs`：**
+1.1.0及以上版本使用`NavDestinationHelper`类来处理页面生命周期和手势动画：
 
 ```ejs
-import { <%= componentName %> } from '<%= importPath %>'
-import { TemplateService, TranslateOption, ScaleOption, OpacityOption } from '@hadss/hmrouter'
+// 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 = '<%= pageUrl %>'
+  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)
   }
@@ -158,6 +273,9 @@ export struct <%= componentName %>Generated {
       .onActionEnd((event: GestureEvent) =>{
         TemplateService.interactiveFinish(this.navigationId, this.ndId, event)
       })
+      .onActionCancel(() =>{
+        TemplateService.interactiveCancel(this.navigationId, this.ndId)
+      })
     )
     .translate(this.translateOption)
     .scale(this.scaleOption)
@@ -197,6 +315,23 @@ export struct <%= componentName %>Generated {
 }
 ```
 
+### 版本差异说明
+
+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。
+
 ### 模板变量
 
 | 属性                | 描述              |
@@ -205,44 +340,49 @@ export struct <%= componentName %>Generated {
 | importPath        | 原组件的导入路径        |
 | componentName     | 原组件名            |
 | dialog            | 是否dialog页面      |
-| generatorViewName | 生成的文件名          |
-
-### TemplateService内置模版方法
-
-该类中封装了一系列在模板中需要用到的注册、初始化、事件回调接口
-
-| 接口                         | 参数                                                                                                                                                  | 返回值  | 接口描述                  |
-|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|------|-----------------------|
-| static aboutToAppear       | navigationId: string,pageUrl: string, dialog: boolean, translateOption: TranslateOption,   scaleOption: ScaleOption,   opacityOption: OpacityOption | void | 注册接口，用于模板代码中注册动画与生命周期 |
-| static aboutToDisappear    | navigationId: string, pageUrl: string, ndId: string                                                                                                 | void | 销毁，用户销毁一个页面的动画与生命周期实例 |
-| static onDisAppear         | navigationId: string, pageUrl: string, navId: string                                                                                                | void | NavDestination生命周期    |
-| static onAppear            | navigationId: string, pageUrl: string, navId: string                                                                                                | void | NavDestination生命周期    |
-| static onShown             | navigationId: string, pageUrl: string, navId: string                                                                                                | void | NavDestination生命周期    |
-| static onHidden            | navigationId: string, pageUrl: string, navId: string                                                                                                | void | NavDestination生命周期    |
-| static onWillAppear        | navigationId: string, pageUrl: string                                                                                                               | void | NavDestination生命周期    |
-| static onWillDisappear     | navigationId: string, pageUrl: string, navId: string                                                                                                | void | NavDestination生命周期    |
-| static onWillShow          | navigationId: string, pageUrl: string, navId: string                                                                                                | void | NavDestination生命周期    |
-| static onWillHide          | navigationId: string, pageUrl: string, navId: string                                                                                                | void | NavDestination生命周期    |
-| static onReady             | navigationId: string, pageUrl: string, navContext: NavDestinationContext                                                                            | void | NavDestination生命周期    |
-| static onBackPressed       | navigationId: string, pageUrl: string, navId: string                                                                                                | void | NavDestination生命周期    |
-| static interactiveStart    | navigationId: string, ndId: string, event: GestureEvent                                                                                             | void | 手势转场动画触发              |
-| static interactiveFinish   | navigationId: string, ndId: string, event: GestureEvent                                                                                             | void | 手势转场动画更新              |
-| static interactiveProgress | navigationId: string, ndId: string, event: GestureEvent                                                                                             | void | 手势转场动画结束              |
-
-## 依赖版本
-
-最低版本
+
+### 文件通配符说明
+
+- `*`：匹配任意数量的字符，不包括目录分隔符
+- `**`：匹配任意数量的字符，包括目录分隔符
+- `?`：匹配单个字符
+- `[abc]`：匹配方括号中的任意一个字符
+- `[a-z]`：匹配a到z范围内的任意一个字符
+- `{a,b,c}`：匹配花括号中的任意一个模式
+- `!`：否定模式，排除匹配的文件
+
+### 匹配优先级
+
+- customPageTemplate > defaultPageTemplate > 库中携带的模板
+- 如遇到customPageTemplate中的多个srcPath都能匹配上，优先取前面的模板文件
+
+## 插件自定义扩展
+
+见[插件扩展指南](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
-HarmonyOS NEXT Developer Beta5版本及以上
 DevEco Studio 5.0.3.700及以上
 hvigor 5.5.1及以上
 ```
 
-**推荐使用**
+**推荐使用**：
 
 ```text
-HarmonyOS NEXT Beta1版本及以上
 DevEco Studio 5.0.3.800及以上
 hvigor 5.7.3及以上
 ```
@@ -253,6 +393,49 @@ hvigor 5.7.3及以上
 > [HMRouterPlugin] Your DevEco Studio version less than 5.0.3.800, may cause remote hsp dependencies get failed
 > ```
 
-## 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)

package/dist/HMRouterAnalyzer.d.ts

@@ -3,6 +3,29 @@ import { HMRouterPluginConfig } from './HMRouterPluginConfig';
 export declare class AnalyzerController {
     private analyzeResult;
     analyzeFile(sourceFilePath: string, config: HMRouterPluginConfig): void;
-    parsePageUrl(): void;
+    parseConstants(): void;
+    private parsePropertyValue;
     getAnalyzeResultSet(): Set<AnalyzerResultLike>;
+    clearAnalyzeResultSet(): void;
+}
+export declare class AnalyzerService {
+    private readonly sourceFilePath;
+    private sourceFile;
+    private config;
+    private analyzerResultSet;
+    private importMap;
+    constructor(sourceFilePath: string, config: HMRouterPluginConfig);
+    start(): void;
+    getResult(): Set<AnalyzerResultLike>;
+    private analyzeImport;
+    private analyzeRouter;
+    private parseFileByLineOrder;
+    private analyzeComponent;
+    private addToResultSet;
+    private parseDecorator;
+    private parseDecoratorArguments;
+    private parseIdentifierPropertyValue;
+    private parsePrimitiveValue;
+    private getVariableFilePath;
+    private getOtherModuleVariableFilePath;
 }