鸿蒙5.0实战案例：基于自定义注解和代码生成实现路由框架

往期推文全新看点（文中附带全新鸿蒙5.0全栈学习笔录）

✏️ 鸿蒙（HarmonyOS）北向开发知识点记录~

✏️ 鸿蒙（OpenHarmony）南向开发保姆级知识点汇总~

✏️ 鸿蒙应用开发与鸿蒙系统开发哪个更有前景？

✏️ 嵌入式开发适不适合做鸿蒙南向开发？看完这篇你就了解了~

✏️ 对于大前端开发来说，转鸿蒙开发究竟是福还是祸？

✏️ 鸿蒙岗位需求突增！移动端、PC端、IoT到底该怎么选？

✏️ 记录一场鸿蒙开发岗位面试经历~

✏️ 持续更新中……

---

场景描述

在应用开发中无论是出于工程组织效率还是开发体验的考虑，开发者都需要对项目进行模块间解耦，此时需要构建一套用于模块间组件跳转、数据通信的路由框架。

业界常见的实现方式是在编译期生成路由表。

1. 实现原理及流程

• 在编译期通过扫描并解析ets文件中的自定义注解来生成路由表和组件注册类
• Har中的rawfile文件在Hap编译时会打包在Hap中，通过这一机制来实现路由表的合并
• 自定义组件通过wrapBuilder封装来实现动态获取
• 通过NavDestination的Builder机制来获取wrapBuilder封装后的自定义组件

2. 使用ArkTS自定义装饰器来代替注解的定义

由于TS语言特性，当前只能使用自定义装饰器

使用@AppRouter装饰器来定义路由信息

// 定义空的装饰器
export function AppRouter(param:AppRouterParam) {return Object;
}export interface AppRouterParam{uri:string;
}

自定义组件增加路由定义

@AppRouter({ uri: "app://login" })
@Component
export struct LoginView {build(){//...}
}

3. 实现动态路由模块

定义路由表（该文件为自动生成的路由表）

{"routerMap": [{"name": "app://login",   /* uri定义  */"pageModule": "loginModule",  /* 模块名  */"pageSourceFile": "src/main/ets/generated/RouterBuilder.ets",  /* Builder文件  */"registerFunction": "LoginViewRegister"  /* 组件注册函数  */}]
}

应用启动时，在EntryAbility.onCreate中加载路由表

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {DynamicRouter.init({libPrefix: "@app", mapPath: "routerMap"}, this.context);
}

---

export class DynamicRouter {// 路由初始化配置static config: RouterConfig;// 路由表static routerMap: Map<string, RouterInfo> = new Map();// 管理需要动态导入的模块，key是模块名，value是WrappedBuilder对象，动态调用创建页面的接口static builderMap: Map<string, WrappedBuilder<Object[]>> = new Map();// 路由栈static navPathStack: NavPathStack = new NavPathStack();// 通过数组实现自定义栈的管理static routerStack: Array<RouterInfo> = new Array();static referrer: string[] = [];public static init(config: RouterConfig, context: Context) {DynamicRouter.config = config;DynamicRouter.routerStack.push(HOME_PAGE)RouterLoader.load(config.mapPath, DynamicRouter.routerMap, context)}//...
}

路由表存放在src/main/resources/rawfile目录中，通过ResourceManager进行读取

export namespace RouterLoader {export function load(dir: string, routerMap: Map<string, RouterInfo>, context: Context) {const rm: resourceManager.ResourceManager = context.resourceManager;try {rm.getRawFileList(dir).then((value: Array<string>) => {let decoder: util.TextDecoder = util.TextDecoder.create('utf-8', {fatal: false, ignoreBOM: true})value.forEach(fileName => {let fileBytes: Uint8Array = rm.getRawFileContentSync(`${dir}/${fileName}`)let retStr = decoder.decodeWithStream(fileBytes)let routerMapModel: RouterMapModel = JSON.parse(retStr) as RouterMapModelloadRouterMap(routerMapModel, routerMap)})}).catch((error: BusinessError) => {//...});} catch (error) {//...}}
}

根据URI跳转页面时，通过动态import并执行路由表中定义的registerFunction方法来实现动态注册组件

Button("跳转").onClick(()=>{DynamicRouter.pushUri("app://settings")})

---

export class DynamicRouter {//...public static pushUri(uri: string, param?: Object, onPop?: (data: PopInfo) => void): void {if (!DynamicRouter.routerMap.has(uri)) {return;}let routerInfo: RouterInfo = DynamicRouter.routerMap.get(uri)!;if (!DynamicRouter.builderMap.has(uri)) {// 动态加载模块import(`${DynamicRouter.config.libPrefix}/${routerInfo.pageModule}`).then((module: ESObject) => {module[routerInfo.registerFunction!](routerInfo)   // 进行组件注册，实际执行了下文中的LoginViewRegister方法DynamicRouter.navPathStack.pushDestination({ name: uri, onPop: onPop, param: param });DynamicRouter.pushRouterStack(routerInfo);}).catch((error: BusinessError) => {console.error(`promise import module failed, error code: ${error.code}, message: ${error.message}.`);});} else {DynamicRouter.navPathStack.pushDestination({ name: uri, onPop: onPop, param: param });DynamicRouter.pushRouterStack(routerInfo);}}
}

组件注册实际执行的方法为LoginViewRegister（该文件为自动生成的模版代码）

// auto-generated RouterBuilder.ets
import { DynamicRouter, RouterInfo } from '@app/dynamicRouter/Index'
import { LoginView } from '../components/LoginView'@Builder
function LoginViewBuilder() {LoginView()
}export function LoginViewRegister(routerInfo: RouterInfo) {DynamicRouter.registerRouterPage(routerInfo, wrapBuilder(LoginViewBuilder))
}

通过wrapBuilder将自定义组件保存在组件表

export class DynamicRouter {//...// 通过URI注册builderpublic static registerRouterPage(routerInfo: RouterInfo, wrapBuilder: WrappedBuilder<Object[]>): void {const builderName: string = routerInfo.name;if (!DynamicRouter.builderMap.has(builderName)) {DynamicRouter.registerBuilder(builderName, wrapBuilder);}}private static registerBuilder(builderName: string, builder: WrappedBuilder<Object[]>): void {DynamicRouter.builderMap.set(builderName, builder);}// 通过URI获取builderpublic static getBuilder(builderName: string): WrappedBuilder<Object[]> {const builder = DynamicRouter.builderMap.get(builderName);return builder as WrappedBuilder<Object[]>;}
}

首页Navigation通过组件表获取自定义组件Builder

@Entry
@Component
struct Index {build() {Navigation(DynamicRouter.getNavPathStack()) {//...}.navDestination(this.PageMap).hideTitleBar(true)}@BuilderPageMap(name: string, param?: ESObject) {NavDestination() {DynamicRouter.getBuilder(name).builder(param);}}}

4. 实现路由表生成插件

新建插件目录etsPlugin，建议创建在HarmonyOS工程目录之外

mkdir etsPlugin
cd etsPlugin

创建npm项目

npm init

安装依赖

npm i --save-dev @types/node @ohos/hvigor @ohos/hvigor-ohos-plugin
npm i typescript handlebars

初始化typescript配置

./node_modules/.bin/tsc --init

修改tsconfig.json

{"compilerOptions": {"target": "es2021",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */"module": "commonjs",                                /* Specify what module code is generated. */"strict": true,                                      /* Enable all strict type-checking options. */"esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */"forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */"skipLibCheck": true,                                 /* Skip type checking all .d.ts files. */"sourceMap": true,"outDir": "./lib",},"include": [".eslintrc.js", "src/**/*"],"exclude": ["node_modules", "lib/**/*"],
}

创建插件文件src/index.ts

export function etsGeneratorPlugin(pluginConfig: PluginConfig): HvigorPlugin {return {pluginId: PLUGIN_ID,apply(node: HvigorNode) {pluginConfig.moduleName = node.getNodeName();pluginConfig.modulePath = node.getNodePath();pluginExec(pluginConfig);},};
}

修改package.json

{//..."main": "lib/index.js","scripts": {"test": "echo \"Error: no test specified\" && exit 1","dev": "tsc && node lib/index.js","build": "tsc"},//...
}

插件实现流程

• 通过扫描自定义组件的ets文件，解析语法树，拿到注解里定义的路由信息
• 生成路由表、组件注册类，同时更新Index.ets

定义插件配置

const config: PluginConfig = {builderFileName: "RouterBuilder.ets",  // 生成的组件注册类文件名builderDir: "src/main/ets/generated",  // 代码生成路径routerMapDir: "src/main/resources/rawfile/routerMap",  // 路由表生成路径scanDir: "src/main/ets/components",  // 自定义组件扫描路径annotation: "AppRouter",  // 路由注解viewKeyword: "struct",  // 自定义组件关键字builderTpl: "viewBuilder.tpl",  // 组件注册类模版文件
};

插件核心代码：

function pluginExec(config: PluginConfig) {// 读取指定自定义组件目录下的文件const scanPath = `${config.modulePath}/${config.scanDir}`;const files: string[] = readdirSync(scanPath);files.forEach((fileName) => {// 对每个文件进行解析const sourcePath = `${scanPath}/${fileName}`;const importPath = path.relative(`${config.modulePath}/${config.builderDir}`, sourcePath).replaceAll("\\", "/").replaceAll(".ets", "");// 执行语法树解析器const analyzer = new EtsAnalyzer(config, sourcePath);analyzer.start();// 保存解析结果console.log(JSON.stringify(analyzer.analyzeResult));console.log(importPath);templateModel.viewList.push({viewName: analyzer.analyzeResult.viewName,importPath: importPath,});routerMap.routerMap.push({name: analyzer.analyzeResult.uri,pageModule: config.moduleName,pageSourceFile: `${config.builderDir}/${config.builderFileName}`,registerFunction: `${analyzer.analyzeResult.viewName}Register`,});});// 生成组件注册类generateBuilder(templateModel, config);// 生成路由表generateRouterMap(routerMap, config);// 更新Index文件generateIndex(config);
}

语法树解析流程

• 遍历语法树节点，找到自定义注解@AppRouter
• 读取URI的值
• 通过识别struct关键字来读取自定义组件类名
• 其他节点可以忽略

核心代码：

export class EtsAnalyzer {sourcePath: string;pluginConfig: PluginConfig;analyzeResult: AnalyzeResult = new AnalyzeResult();keywordPos: number = 0;constructor(pluginConfig: PluginConfig, sourcePath: string) {this.pluginConfig = pluginConfig;this.sourcePath = sourcePath;}start() {const sourceCode = readFileSync(this.sourcePath, "utf-8");// 创建ts语法解析器const sourceFile = ts.createSourceFile(this.sourcePath,sourceCode,ts.ScriptTarget.ES2021,false);// 遍历语法节点ts.forEachChild(sourceFile, (node: ts.Node) => {this.resolveNode(node);});}// 根据节点类型进行解析resolveNode(node: ts.Node): NodeInfo | undefined {switch (node.kind) {case ts.SyntaxKind.ImportDeclaration: {this.resolveImportDeclaration(node);break;}case ts.SyntaxKind.MissingDeclaration: {this.resolveMissDeclaration(node);break;}case ts.SyntaxKind.Decorator: {this.resolveDecorator(node);break;}case ts.SyntaxKind.CallExpression: {this.resolveCallExpression(node);break;}case ts.SyntaxKind.ExpressionStatement: {this.resolveExpression(node);break;}case ts.SyntaxKind.Identifier: {return this.resolveIdentifier(node);}case ts.SyntaxKind.StringLiteral: {return this.resolveStringLiteral(node);}case ts.SyntaxKind.PropertyAssignment: {return this.resolvePropertyAssignment(node);}}}resolveImportDeclaration(node: ts.Node) {let ImportDeclaration = node as ts.ImportDeclaration;}resolveMissDeclaration(node: ts.Node) {node.forEachChild((cnode) => {this.resolveNode(cnode);});}resolveDecorator(node: ts.Node) {let decorator = node as ts.Decorator;this.resolveNode(decorator.expression);}resolveIdentifier(node: ts.Node): NodeInfo {let identifier = node as ts.Identifier;let info = new NodeInfo();info.value = identifier.escapedText.toString();return info;}resolveCallExpression(node: ts.Node) {let args = node as ts.CallExpression;let identifier = this.resolveNode(args.expression);this.parseRouterConfig(args.arguments, identifier);}resolveExpression(node: ts.Node) {let args = node as ts.ExpressionStatement;let identifier = this.resolveNode(args.expression);if (identifier?.value === this.pluginConfig.viewKeyword) {this.keywordPos = args.end;}if (this.keywordPos === args.pos) {this.analyzeResult.viewName = identifier?.value;}}resolveStringLiteral(node: ts.Node): NodeInfo {let stringLiteral = node as ts.StringLiteral;let info = new NodeInfo();info.value = stringLiteral.text;return info;}resolvePropertyAssignment(node: ts.Node): NodeInfo {let propertyAssignment = node as ts.PropertyAssignment;let propertyName = this.resolveNode(propertyAssignment.name)?.value;let propertyValue = this.resolveNode(propertyAssignment.initializer)?.value;let info = new NodeInfo();info.value = { key: propertyName, value: propertyValue };return info;}}

使用模版引擎生成组件注册类

使用Handlebars生成组件注册类

const template = Handlebars.compile(tpl);
const output = template({ viewList: templateModel.viewList });

模版文件viewBuilder.tpl示例：

// auto-generated RouterBuilder.ets
import { DynamicRouter, RouterInfo } from '@app/dynamicRouter/Index'
{{#each viewList}}
import { {{viewName}} } from '{{importPath}}'
{{/each}}{{#each viewList}}
@Builder
function {{viewName}}Builder() {{{viewName}}()
}export function {{viewName}}Register(routerInfo: RouterInfo) {DynamicRouter.registerRouterPage(routerInfo, wrapBuilder({{viewName}}Builder))
}{{/each}}

生成的RouterBuilder.ets代码示例：

// auto-generated RouterBuilder.ets
import { DynamicRouter, RouterInfo } from '@app/dynamicRouter/Index'
import { LoginView } from '../components/LoginView'@Builder
function LoginViewBuilder() {LoginView()
}export function LoginViewRegister(routerInfo: RouterInfo) {DynamicRouter.registerRouterPage(routerInfo, wrapBuilder(LoginViewBuilder))
}

将路由表和组件注册类写入文件

• 路由表保存在rawfile目录
• 组件注册类保存在ets代码目录
• 更新模块导出文件Index.ets

核心代码：

function generateBuilder(templateModel: TemplateModel, config: PluginConfig) {console.log(JSON.stringify(templateModel));const builderPath = path.resolve(__dirname, `../${config.builderTpl}`);const tpl = readFileSync(builderPath, { encoding: "utf8" });const template = Handlebars.compile(tpl);const output = template({ viewList: templateModel.viewList });console.log(output);const routerBuilderDir = `${config.modulePath}/${config.builderDir}`;if (!existsSync(routerBuilderDir)) {mkdirSync(routerBuilderDir, { recursive: true });}writeFileSync(`${routerBuilderDir}/${config.builderFileName}`, output, {encoding: "utf8",});
}function generateRouterMap(routerMap: RouterMap, config: PluginConfig) {const jsonOutput = JSON.stringify(routerMap, null, 2);console.log(jsonOutput);const routerMapDir = `${config.modulePath}/${config.routerMapDir}`;if (!existsSync(routerMapDir)) {mkdirSync(routerMapDir, { recursive: true });}writeFileSync(`${routerMapDir}/${config.moduleName}.json`, jsonOutput, {encoding: "utf8",});
}function generateIndex(config: PluginConfig) {const indexPath = `${config.modulePath}/Index.ets`;const indexContent = readFileSync(indexPath, { encoding: "utf8" });const indexArr = indexContent.split("\n").filter((value) => !value.includes(config.builderDir!));indexArr.push(`export * from './${config.builderDir}/${config.builderFileName?.replace(".ets","")}'`);writeFileSync(indexPath, indexArr.join("\n"), {encoding: "utf8",});
}

5. 在应用中使用

修改项目的hvigor/hvigor-config.json文件，导入路由表插件

{"hvigorVersion": "4.2.0","dependencies": {"@ohos/hvigor-ohos-plugin": "4.2.0","@app/ets-generator" : "file:../../etsPlugin"   // 插件目录的本地相对路径，或者使用npm仓版本号},//...
}

修改loginModule模块的hvigorfile.ts文件(loginModule/hvigorfile.ts)，加载插件

import { harTasks } from '@ohos/hvigor-ohos-plugin';
import {PluginConfig,etsGeneratorPlugin} from '@app/ets-generator'const config: PluginConfig = {builderFileName: "RouterBuilder.ets",builderDir: "src/main/ets/generated",routerMapDir: "src/main/resources/rawfile/routerMap",scanDir: "src/main/ets/components",annotation: "AppRouter",viewKeyword: "struct",builderTpl: "viewBuilder.tpl",
}export default {system: harTasks,  /* Built-in plugin of Hvigor. It cannot be modified. */plugins:[etsGeneratorPlugin(config)]         /* Custom plugin to extend the functionality of Hvigor. */
}

在loginModule模块的oh-package.json5中引入动态路由模块依赖

{"name": "loginmodule","version": "1.0.0","description": "Please describe the basic information.","main": "Index.ets","author": "","license": "Apache-2.0","dependencies": {"@app/dynamicRouter": "file:../routerModule"}
}

在loginModule模块的自定义组件中使用@AppRouter定义路由信息

@AppRouter({ uri: "app://login" })
@Component
export struct LoginView {build(){//...}
}

在entry中的oh-package.json5中引入依赖

{"name": "entry","version": "1.0.0","description": "Please describe the basic information.","main": "","author": "","license": "","dependencies": {"@app/loginModule": "file:../loginModule","@app/commonModule": "file:../commonModule","@app/dynamicRouter": "file:../routerModule"}
}

在entry中的build-profile.json5中配置动态import

{"apiType": "stageMode","buildOption": {"arkOptions": {"runtimeOnly": {"packages": ["@app/loginModule",  // 仅用于使用变量动态import其他模块名场景，静态import或常量动态import无需配置。"@app/commonModule"  // 仅用于使用变量动态import其他模块名场景，静态import或常量动态import无需配置。]}}},//...
}

在entry中的EntryAbility.onCreate中初始化路由组件

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {DynamicRouter.init({libPrefix: "@app", mapPath: "routerMap"}, this.context);
}

组件内使用pushUri进行跳转

Button("立即登录", { buttonStyle: ButtonStyleMode.TEXTUAL }).onClick(() => {DynamicRouter.pushUri("app://login")}).id("button")

在entry模块执行Run/Debug，即可在编译时自动生成路由表配置并打包运行。