企业官网建设流程全解析

056 — 模块化路由设计：RouterMap 枚举驱动的导航解耦

简介

在多模块工程中，页面导航是一个易于被忽视但却影响深远的架构决策。如果每个页面直接引用目标页面的路径字符串，一旦路径变更（如模块重构、包名修改），所有引用方都需要同步修改，维护成本极高。MoneyTrack 通过RouterMap枚举将 17 个路由目标集中管理，结合DialogMap管理对话框路由，并通过RouterModule封装类统一封装跳转逻辑，实现了页面间的完全解耦。

核心知识点

1. 路由跳转完整流程

使用 mermaid 图可以清晰地展示一次路由跳转的完整流程：

通过 RouterMap 枚举的中间层，源页面与目标页面的物理路径完全解耦——源页面只感知语义化的枚举名，不感知路径字符串。

2. 路由集中管理

将所有可跳转页面的路径定义为枚举值，每个枚举项对应一个页面 URL：

• 集中管理使得路径变更只需修改枚举定义，所有使用者自动生效。
• 枚举值具有语义化，一眼看出跳转目标。
• 配合 TypeScript，跳转参数也能做到类型安全。

3. RouterMap 枚举类型安全的具体实现

在基础版本之上，通过泛型约束实现参数的类型安全：

// 定义路由参数的类型映射exportinterfaceRouteParams{[RouterMap.BILL_LIST]:{categoryId?:string;startDate?:string};[RouterMap.BILL_DETAIL]:{billId:string};[RouterMap.ADD_BILL]:{prefillCategory?:string};[RouterMap.ASSET_DETAIL]:{assetId:string};[RouterMap.STATISTICS]:{year?:number;month?:number};[RouterMap.SETTINGS]:Record<string,never>;[RouterMap.LOGIN]:{redirect?:string};// ... 其他路由参数类型}// 类型安全的路由封装exportclassRouterModule{staticnavigateTo<TextendsRouterMap>(target:T,params?:RouteParams[T]){router.pushUrl({url:target,params});}}

这种设计下，RouterModule.navigateTo(RouterMap.BILL_DETAIL, { billId: '123' })是类型安全的——参数对象的字段和类型由泛型约束自动推导。如果传递了错误的参数名或类型，编译阶段就会报错。

4. 模块间路由解耦

模块间解耦的核心是"依赖倒置"：

• feature 模块不直接引用其他 feature 模块的页面。
• 所有路由通过 RouterMap 枚举间接引用，枚举定义在 common 层。
• feature 模块只需依赖 common 层，不依赖其他 feature。

5. NavPathStack 与 router API 的对比

鸿蒙提供了两种主要的导航方式，它们的对比如下：

在 MoneyTrack 中，跨模块的页面跳转统一使用 router API 配合 RouterMap 枚举；而在同一 feature 内部的页面导航（如账单列表页 → 账单详情页），则使用 NavPathStack 获得更好的动画控制和栈管理能力。

6. 路由参数的类型安全

除了路由目标的类型安全，路由参数本身也需要关注：

• 必选参数：如账单详情需要billId，在类型定义中标记为必填。
• 可选参数：如列表页的筛选条件可以传也可以不传。
• 参数校验：在目标页面的onPageShow或aboutToAppear中对参数进行校验，缺失必选参数时给出友好提示或跳转回退。

// 目标页面参数校验aboutToAppear(){constparams=router.getParams()asRouteParams[RouterMap.BILL_DETAIL];if(!params?.billId){console.error('缺少必选参数 billId');router.back();return;}this.billId=params.billId;}

7. 路由守卫和拦截器

在需要统一处理登录校验、权限检查等场景时，可以使用路由守卫：

exportclassRouterGuard{// 需要登录才能访问的路由列表privatestaticauthRequiredRoutes:RouterMap[]=[RouterMap.SETTINGS,RouterMap.MEMBERSHIP,RouterMap.FEEDBACK,];staticcanNavigate(target:RouterMap):boolean{if(this.authRequiredRoutes.includes(target)&&!AuthService.isLoggedIn()){// 未登录，跳转到登录页RouterModule.navigateTo(RouterMap.LOGIN,{redirect:target});returnfalse;}returntrue;}}// 在 RouterModule 中集成守卫exportclassRouterModule{staticnavigateTo<TextendsRouterMap>(target:T,params?:RouteParams[T]){if(!RouterGuard.canNavigate(target))return;router.pushUrl({url:target,params});}}

8. DialogMap 对话框路由

对话框也可以像页面一样管理：

• DialogMap 枚举管理所有对话框路由（确认框、选择框、输入框等）。
• 通过统一的 Dialog 管理器打开/关闭对话框。

项目代码案例

文件路径：lib_router/RouterMap.ets

exportenumRouterMap{INDEX='pages/Index',BILL_LIST='pages/BillList',BILL_DETAIL='pages/BillDetail',ADD_BILL='pages/AddBill',ASSET_LIST='pages/AssetList',ASSET_DETAIL='pages/AssetDetail',ADD_ASSET='pages/AddAsset',STATISTICS='pages/Statistics',SETTINGS='pages/Settings',LOGIN='pages/Login',MEMBERSHIP='pages/Membership',FEEDBACK='pages/Feedback',// ... 共 17 个路由目标}exportenumDialogMap{CONFIRM_DELETE='dialog/ConfirmDelete',DATE_PICKER='dialog/DatePicker',CATEGORY_PICKER='dialog/CategoryPicker',}

RouterModule 封装：

exportclassRouterModule{staticnavigateTo(target:RouterMap,params?:Record<string,Object>){router.pushUrl({url:target,params});}}

通过 RouterMap + RouterModule + RouterGuard 的组合，MoneyTrack 实现了路由的集中管理、类型安全、守卫拦截三大目标。任意页面都只需调用RouterModule.navigateTo(RouterMap.BILL_LIST)即可跳转，完全不感知目标页面的具体路径和所在模块。

推荐参考文档

• 路由解耦设计模式
• router.pushUrl API 参考
• Navigation + NavPathStack 导航文档