@hadss/hmrouter-plugin 1.2.3-rc.0 → 1.2.3-rc.2

package/README.md

@@ -23,7 +23,7 @@ HMRouter编译插件是一个基于hvigor的编译插件，用于：
 ```json5
 {
   "dependencies": {
-    "@hadss/hmrouter-plugin": "^1.2.3-rc.0"  // 使用最新版本
+    "@hadss/hmrouter-plugin": "^1.2.3-rc.2"  // 使用最新版本
   },
   // ...其余配置
 }
@@ -75,6 +75,9 @@ export default {
   // 是否自动配置混淆规则，默认为false
   "autoObfuscation": false,
   
+  // 是否开启增量编译，默认值根据条件判断，满足条件时默认true
+  "incremental": true,
+  
   // 默认模板文件，不配置时使用插件内置模板
   "defaultPageTemplate": "./templates/defaultTemplate.ejs",
   
@@ -105,6 +108,7 @@ export default {
 | 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为模版路径，可以实现不同的代码使用不同的模版来生成                                                                                                           |
+| incremental         | boolean | 否    | 是否开启增量编译，DevEco Studio >= 6.0.2 release版本生效，当未配置defaultPageTemplate和customPageTemplate时默认为true；当已配置自定义模板或者默认模板之后默认为false，该情况下如需开启增量编译需要主动设置为true                        |
 
 ### 配置文件读取规则
 
@@ -116,6 +120,78 @@ export default {
 > 
 > 1.0.0-rc.9 版本开始，支持自定义模版配置`customPageTemplate`
 
+## 增量编译规则
+在 HMRouterPlugin 1.2.3-rc.2 版本之前，编译时默认会每次重新生成路由页面以及路由配置，即使代码没有任何改动也会触发全量生成，这会导致 hvigor 的 CompileArkTS 基础任务无法正常执行增量编译，从而增加不必要的编译耗时。
+
+为解决这个问题，在早期版本中，开发者有时会通过设置 `saveGeneratedFile` 为 true 来保留生成的路由文件，以确保 CompileArkTS 任务可以走增量编译流程。然而，这种方式会将生成的代码文件直接写入 `src/main` 目录中，造成源码目录被"入侵"的问题，破坏了源码目录的整洁性。
+
+从 HMRouterPlugin 1.2.3-rc.2 版本开始，引入了增量编译能力，可以有效解决上述问题，在不影响 CompileArkTS 增量编译的前提下避免入侵源码目录。
+
+HMRouterPlugin增量编译生效条件：
+1. HMRouterPlugin版本 >= 1.2.3-rc.2版本；
+2. DevEco Studio版本 >= 6.0.2 release；
+3. 工程配置了自定义模板customPageTemplate，或者默认模版defaultPageTemplate的情形下，需要主动设置`incremental: true`；未设置自定义模板或默认模板时，满足前面条件时，`incremental`默认为`true`；
+4. 项目内配置的hvigor增量编译未被关闭，即`hvigor-config.json5`文件内`execution.incremental`未主动设置为`false`。
+
+### 增量编译开关对生成文件路径的影响
+
+当`incremental`设置为 `true` 时（启用增量编译）：
+
+- **生成的页面构建器文件路径**: `build/hmrouter/ets/` 目录下
+- **生成的路由映射文件路径**: `build/hmrouter/resources/base/profile/hm_router_map.json`
+- **合并后的路由映射文件路径**: `build/hmrouter/resources/rawfile/hm_router_map.json`
+- **混淆规则文件路径**: `build/hmrouter/hmrouter-obfuscation-rules.txt`
+- **消费者混淆规则文件路径**: `build/hmrouter/hmrouter-consumer-rules.txt`
+
+当`incremental`设置为 `false` 时（禁用增量编译）：
+> 源码目录下的文件是否留存受`saveGeneratedFile`配置影响，默认为`false`；在编译之后路由文件会被删除，需要查看编译之后路由文件需主动配置为`true`。
+- **生成的页面构建器文件路径**: `src/main/ets/generated/` 目录下（或配置的 `builderDir` 目录）
+- **生成的路由映射文件路径**: `src/main/resources/base/profile/hm_router_map.json`
+- **合并后的路由映射文件路径**: `src/main/resources/rawfile/hm_router_map.json`
+- **混淆规则文件路径**: `hmrouter-obfuscation-rules.txt`
+- **消费者混淆规则文件路径**: `hmrouter-consumer-rules.txt`
+
+### 增量编译路径规则详解
+
+1. **启用增量编译 (incremental=true)**：
+   - 生成的文件位于 `build/hmrouter` 目录下，这是一个隔离的构建输出目录
+   - 避免了对源代码目录的污染，不会修改 `src` 目录下的文件
+   - hvigor 可以更精确地追踪文件依赖关系，仅在必要时重新生成文件
+   - 适用于 DevEco Studio 6.0.2 release 及以上版本的增量编译优化
+
+2. **禁用增量编译 (incremental=false)**：
+   - 生成的文件直接放置在源代码目录中，如 `src/main/ets/generated`
+   - 传统模式，适用于旧版本的 DevEco Studio
+   - 编译过程中可能会导致不必要的全量重建
+
+### saveGeneratedFile 对生成文件的控制
+
+`saveGeneratedFile` 配置项用于控制是否保留插件自动生成的代码文件，其行为在增量和非增量模式下有所不同：
+
+#### 在增量编译模式 (incremental=true) 下：
+
+- **saveGeneratedFile=true**：
+  - 生成的文件会保留在 `build/hmrouter` 目录中
+  - 便于查看和调试生成的代码
+  - 生成的文件不会被清理，会在每次构建时更新
+  
+- **saveGeneratedFile=false**（默认）：
+  - 生成的文件仍位于 `build/hmrouter` 目录
+  - 构建结束后**不会**清理`build/hmrouter`目录下的文件，但会清理`incremental=false`,`saveGeneratedFile=true`配置下生成的文件
+
+#### 在非增量编译模式 (incremental=false) 下：
+
+- **saveGeneratedFile=true**：
+  - 生成的页面构建器文件会保留在源码目录中，便于查看和调试
+  - 混淆规则文件会保留在项目模块根目录
+
+- **saveGeneratedFile=false**（默认）：
+  - 生成的文件会在构建过程结束后被清理
+  - 不会在源代码目录中留下任何中间文件
+  - 保持源代码目录的整洁
+
+启用`incremental`增量编译后，不仅能够显著提高编译速度，还能够保持源代码目录的整洁，因为生成的文件都在隔离的 `build` 目录中。
+
 ## 自定义模板使用
 
 在 `HMRouterPlugin` 中，EJS模板用于生成动态页面或组件，可以在模板文件中使用 EJS 的语法
@@ -439,6 +515,14 @@ hvigor 5.7.3及以上
 > ```
 
 ## 更新日志
+### 1.2.3-rc.2 (2026.02.06)
+
+- [新增增量编译配置开关](#增量编译规则)
+- [修复插件解析路由常量是通过`export *`导出，生成路由表格式不正确问题](https://gitcode.com/openharmony-sig/ohrouter/issues/278)
+
+### 1.2.3-rc.1 (2026.01.15)
+
+- [修复插件编译报错路由常量找不到问题](https://gitcode.com/openharmony-sig/ohrouter/issues/207)
 
 ### 1.2.3-rc.0 (2025.12.11)
 

package/dist/HMRouterPluginManager.d.ts

@@ -9,4 +9,5 @@ export declare class HMRouterPluginManager {
     static getInstance(): HMRouterPluginManager;
     registerPlugin(node: HvigorNode, pluginId: string, options: PluginParam): void;
     addModuleNode(node: HvigorNode, isIgnored: boolean): void;
+    private initializeArkAnalyzer;
 }

package/dist/HMRouterPluginManager.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HMRouterPluginManager = void 0;
 const hvigor_1 = require("@ohos/hvigor");
+const hvigor_ohos_plugin_1 = require("@ohos/hvigor-ohos-plugin");
 const PluginError_1 = require("./hmrouter_extension/error/PluginError");
 const HMRouterExtension_1 = require("./hmrouter_extension/HMRouterExtension");
 const framework_1 = require("./framework");
@@ -13,6 +14,7 @@ class HMRouterPluginManager {
         framework_1.Logger.info('', 'HMRouterPlugin starting...');
         (0, framework_1.registerPluginExtension)(new HMRouterExtension_1.HMRouterDefaultExtension());
         hvigor_1.hvigor.nodesEvaluated(() => {
+            this.initializeArkAnalyzer();
             this.moduleNodes.forEach((node) => {
                 if (this.controllerMap.has(node.getNodeName())) {
                     return;
@@ -29,6 +31,7 @@ class HMRouterPluginManager {
             this.controllerMap.forEach((controller) => {
                 controller.complete();
             });
+            framework_1.ArkAnalyzerUtil.clear();
             HMRouterPluginManager.instance = null;
             framework_1.PluginStore.destroy();
             framework_1.ExtensionManager.destroy();
@@ -73,6 +76,18 @@ class HMRouterPluginManager {
             this.nodeIgnored.add(node.getNodeName());
         }
     }
+    initializeArkAnalyzer() {
+        if (this.moduleNodes.length === 0) {
+            return;
+        }
+        const firstNode = this.moduleNodes[0];
+        const appContext = firstNode.getParentNode()?.getContext(hvigor_ohos_plugin_1.OhosPluginId.OHOS_APP_PLUGIN);
+        if (appContext) {
+            const projectPath = appContext.getProjectPath();
+            framework_1.Logger.info('', `Initializing ArkAnalyzer for project: ${projectPath}`);
+            framework_1.ArkAnalyzerUtil.initialize(projectPath);
+        }
+    }
 }
 exports.HMRouterPluginManager = HMRouterPluginManager;
 HMRouterPluginManager.instance = null;

package/dist/Index.js

@@ -49,7 +49,7 @@ function harPlugin(options = {}) {
 exports.harPlugin = harPlugin;
 function modulePlugin(options = {}) {
     return {
-        pluginId: constants_1.PluginConstants.HAP_PLUGIN_ID,
+        pluginId: constants_1.PluginConstants.PLUGIN_ID,
         apply(node) {
             node.getAllPluginIds().forEach((pluginId) => {
                 HMRouterPluginManager_1.HMRouterPluginManager.getInstance().registerPlugin(node, pluginId, options);
@@ -60,7 +60,7 @@ function modulePlugin(options = {}) {
 exports.modulePlugin = modulePlugin;
 function appPlugin(options) {
     return {
-        pluginId: constants_1.PluginConstants.HAP_PLUGIN_ID,
+        pluginId: constants_1.PluginConstants.APP_PLUGIN_ID,
         apply(node) {
             if (!options) {
                 throw new Error('No options provided');

package/dist/framework/constants/TaskConstants.d.ts

@@ -2,7 +2,10 @@ export declare class TaskConstants {
     static readonly PRE_BUILD = "@PreBuild";
     static readonly PROCESS_ROUTER_MAP = "@ProcessRouterMap";
     static readonly PROCESS_RESOURCE = "@ProcessResource";
-    static readonly PLUGIN_TASK = "@HMRouterPluginTask";
+    static readonly ANNOTATION_ANALYSIS_TASK = "@HMRouterAnnotationAnalysisTask";
+    static readonly CODE_GENERATION_TASK = "@HMRouterCodeGenerationTask";
+    static readonly BUILD_ROUTER_MAP_TASK = "@HMRouterBuildRouterMapTask";
+    static readonly CONFIG_UPDATE_TASK = "@HMRouterConfigUpdateTask";
     static readonly COPY_ROUTER_MAP_TASK = "@HMRouterCopyRouterMapToRawFileTask";
     static readonly GENERATE_OBFUSCATION_TASK = "@HMRouterGenerateObfuscationFileTask";
     static readonly DEFAULT_SOURCE_ROOT = "./src/main";

package/dist/framework/constants/TaskConstants.js

@@ -7,7 +7,10 @@ exports.TaskConstants = TaskConstants;
 TaskConstants.PRE_BUILD = '@PreBuild';
 TaskConstants.PROCESS_ROUTER_MAP = '@ProcessRouterMap';
 TaskConstants.PROCESS_RESOURCE = '@ProcessResource';
-TaskConstants.PLUGIN_TASK = '@HMRouterPluginTask';
+TaskConstants.ANNOTATION_ANALYSIS_TASK = '@HMRouterAnnotationAnalysisTask';
+TaskConstants.CODE_GENERATION_TASK = '@HMRouterCodeGenerationTask';
+TaskConstants.BUILD_ROUTER_MAP_TASK = '@HMRouterBuildRouterMapTask';
+TaskConstants.CONFIG_UPDATE_TASK = '@HMRouterConfigUpdateTask';
 TaskConstants.COPY_ROUTER_MAP_TASK = '@HMRouterCopyRouterMapToRawFileTask';
 TaskConstants.GENERATE_OBFUSCATION_TASK = '@HMRouterGenerateObfuscationFileTask';
 TaskConstants.DEFAULT_SOURCE_ROOT = './src/main';

package/dist/framework/core/PluginExecutionController.d.ts

@@ -1,6 +1,7 @@
 import { HvigorNode } from '@ohos/hvigor';
 import { OhosModuleContext } from '@ohos/hvigor-ohos-plugin/src/plugin/context/plugin-context';
 import { PluginExtension } from '../extension';
+import { HMRouterResult } from '../../hmrouter_extension/model';
 export declare class PluginExecutionController {
     private readonly node;
     private readonly moduleContext;
@@ -14,7 +15,11 @@ export declare class PluginExecutionController {
     private registerHvigorTasks;
     private filterScanFilesForTarget;
     private getAbsoluteSourceRoots;
-    private registerMainPluginTask;
+    getAnalyzeRouterResults(): HMRouterResult[];
+    getRouterTemplatePaths(routers: HMRouterResult[]): Set<string>;
+    private registerCodeGenerationTask;
+    private registerBuildRouterMapFile;
+    private registerConfigUpdateTask;
     private registerObfuscationTask;
     private registerCopyRouterMapTask;
     private getTaskName;

package/dist/framework/core/PluginExecutionController.js

@@ -6,6 +6,7 @@ const TaskStage_1 = require("./TaskStage");
 const constants_1 = require("../constants");
 const extension_1 = require("../extension");
 const utils_1 = require("../utils");
+const constants_2 = require("../../hmrouter_extension/constants");
 class PluginExecutionController {
     constructor(node, moduleContext, moduleIgnored, moduleExtensions) {
         this.node = node;
@@ -29,8 +30,14 @@ class PluginExecutionController {
     registerHvigorTasks() {
         this.moduleContext.targets((target) => {
             const targetName = target.getTargetName();
-            this.registerMainPluginTask(target);
+            this.taskManager.context.currentTarget = target;
+            const filtered = this.filterScanFilesForTarget(targetName);
+            this.baseContext.scanFiles = filtered;
+            this.taskManager.executeStage(TaskStage_1.TaskStage.AFTER_ANNOTATION_ANALYSIS);
+            this.registerCodeGenerationTask(targetName);
             this.registerObfuscationTask(targetName);
+            this.registerBuildRouterMapFile(targetName);
+            this.registerConfigUpdateTask(targetName);
             if ((0, utils_1.isHapModule)(this.node) || (0, utils_1.isHspModule)(this.node)) {
                 this.registerCopyRouterMapTask(target);
             }
@@ -65,20 +72,72 @@ class PluginExecutionController {
             return normalizedPath.endsWith(utils_1.PluginFileUtil.sep) ? normalizedPath : normalizedPath + utils_1.PluginFileUtil.sep;
         });
     }
-    registerMainPluginTask(target) {
-        const targetName = target.getTargetName();
+    getAnalyzeRouterResults() {
+        const results = [];
+        this.baseContext.getAnalyzeResults().forEach((result) => {
+            if (result.annotation === constants_2.AnnotationConstants.ROUTER_ANNOTATION) {
+                results.push(result);
+            }
+        });
+        return results;
+    }
+    getRouterTemplatePaths(routers) {
+        const pluginPath = utils_1.PluginFileUtil.pathResolve(__dirname, constants_2.FilePathConstants.PARENT_DELIMITER.repeat(3));
+        const customTemplates = new Set();
+        routers.forEach((result) => {
+            if (result.templatePath?.indexOf(pluginPath) === -1) {
+                customTemplates.add(result.templatePath);
+            }
+        });
+        return customTemplates;
+    }
+    registerCodeGenerationTask(targetName) {
         this.node.registerTask({
-            name: this.getTaskName(targetName, constants_1.TaskConstants.PLUGIN_TASK),
-            run: () => {
-                this.taskManager.context.currentTarget = target;
-                const filtered = this.filterScanFilesForTarget(targetName);
-                this.baseContext.scanFiles = filtered;
-                this.taskManager.executeStage(TaskStage_1.TaskStage.AFTER_ANNOTATION_ANALYSIS);
+            name: this.getTaskName(targetName, constants_1.TaskConstants.CODE_GENERATION_TASK),
+            run: (taskContext) => {
                 this.taskManager.executeStage(TaskStage_1.TaskStage.AFTER_CODE_GENERATION);
+            },
+            input: (input) => {
+                const results = this.getAnalyzeRouterResults();
+                const config = this.baseContext.config;
+                const propertyVal = JSON.stringify(results) + JSON.stringify(config);
+                input.property('analyzeResults', propertyVal);
+                input.files(Array.from(this.getRouterTemplatePaths(results)));
+            },
+            output: (output) => {
+                const builderDir = this.baseContext.config.getBuilderDir();
+                output.file(builderDir);
+            },
+            dependencies: [],
+            postDependencies: [this.getTaskName(targetName, constants_1.TaskConstants.PRE_BUILD)],
+        });
+    }
+    registerBuildRouterMapFile(targetName) {
+        this.node.registerTask({
+            name: this.getTaskName(targetName, constants_1.TaskConstants.BUILD_ROUTER_MAP_TASK),
+            run: () => {
                 this.taskManager.executeStage(TaskStage_1.TaskStage.AFTER_ROUTER_MAP_BUILDING);
+            },
+            input: (input) => {
+                const config = this.baseContext.config;
+                input.property('routerMap', JSON.stringify(this.baseContext.routerMap) + JSON.stringify(config));
+                input.files(Array.from(this.getRouterTemplatePaths(this.getAnalyzeRouterResults())));
+            },
+            output: (output) => {
+                const builderDir = this.baseContext.config.getRouterMapDir();
+                output.file(builderDir);
+            },
+            dependencies: [this.getTaskName(targetName, constants_1.TaskConstants.CODE_GENERATION_TASK)],
+            postDependencies: [this.getTaskName(targetName, constants_1.TaskConstants.PRE_BUILD)],
+        });
+    }
+    registerConfigUpdateTask(targetName) {
+        this.node.registerTask({
+            name: this.getTaskName(targetName, constants_1.TaskConstants.CONFIG_UPDATE_TASK),
+            run: () => {
                 this.taskManager.executeStage(TaskStage_1.TaskStage.AFTER_CONFIG_UPDATE);
             },
-            dependencies: [],
+            dependencies: [this.getTaskName(targetName, constants_1.TaskConstants.BUILD_ROUTER_MAP_TASK)],
             postDependencies: [this.getTaskName(targetName, constants_1.TaskConstants.PRE_BUILD)],
         });
     }
@@ -88,7 +147,7 @@ class PluginExecutionController {
             run: () => {
                 this.taskManager.executeStage(TaskStage_1.TaskStage.AFTER_OBFUSCATION_PROCESS);
             },
-            dependencies: [this.getTaskName(targetName, constants_1.TaskConstants.PLUGIN_TASK)],
+            dependencies: [this.getTaskName(targetName, constants_1.TaskConstants.CODE_GENERATION_TASK)],
             postDependencies: [this.getTaskName(targetName, constants_1.TaskConstants.PRE_BUILD)],
         });
     }

package/dist/framework/core/TaskManager.d.ts

@@ -1,12 +1,28 @@
+import { HMRouterExtensionContext } from '../../hmrouter_extension/HMRouterExtensionContext';
 import { ExtensionContext, PluginExtension } from '../extension';
 import { TaskStage } from './TaskStage';
 export declare class TaskManager {
     private extensionManager;
     private readonly moduleExtensions;
     context: ExtensionContext;
+    routerContext: HMRouterExtensionContext;
     constructor(context: ExtensionContext, moduleExtensions?: PluginExtension[]);
     executeStage(stage: TaskStage): void;
     private executeAnnotationAnalysis;
     private getExtensions;
     private validateTemplateData;
+    private generateRouterFilePath;
+    private buildRouterMap;
+    private useAnnotationConfig;
+    private buildRouterTemplatePath;
+    private matchedPath;
+    private readExistingRouterMap;
+    private determineTemplatePath;
+    private determineTemplateType;
+    private detectLibraryVersion;
+    private detectLibraryVersion2;
+    private extractHMRouterVersion;
+    private getLibraryPossiblePaths;
+    private parseVersion;
+    private compareVersions;
 }