HarmonyOS掌上记账APP开发实践第56篇:模块化路由设计：RouterMap 枚举驱动的导航解耦

056 — 模块化路由设计RouterMap 枚举驱动的导航解耦简介在多模块工程中页面导航是一个易于被忽视但却影响深远的架构决策。如果每个页面直接引用目标页面的路径字符串一旦路径变更如模块重构、包名修改所有引用方都需要同步修改维护成本极高。MoneyTrack 通过RouterMap枚举将 17 个路由目标集中管理结合DialogMap管理对话框路由并通过RouterModule封装类统一封装跳转逻辑实现了页面间的完全解耦。核心知识点1. 路由跳转完整流程使用 mermaid 图可以清晰地展示一次路由跳转的完整流程目标页面RouterMapRouterModule源页面目标页面RouterMapRouterModule源页面调用 navigateTo(RouterMap.BILL_LIST)解析枚举值获取路径字符串返回 pages/BillList构造路由参数对象router.pushUrl({ url, params })返回执行结果通过 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]:Recordstring,never;[RouterMap.LOGIN]:{redirect?:string};// ... 其他路由参数类型}// 类型安全的路由封装exportclassRouterModule{staticnavigateToTextendsRouterMap(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 的对比鸿蒙提供了两种主要的导航方式它们的对比如下特性router API (pushUrl)NavPathStack使用方式全局函数调用Navigation 组件的栈管理页面栈控制基础 push/replace/back完整栈操作支持 popToIndex/popToName参数传递params 对象泛型参数类型更安全页面间动画不支持自定义支持自定义转场动画适用场景简单跳转、跨模块导航复杂导航结构、Tab 页内导航在 MoneyTrack 中跨模块的页面跳转统一使用 router API 配合 RouterMap 枚举而在同一 feature 内部的页面导航如账单列表页 → 账单详情页则使用 NavPathStack 获得更好的动画控制和栈管理能力。6. 路由参数的类型安全除了路由目标的类型安全路由参数本身也需要关注必选参数如账单详情需要billId在类型定义中标记为必填。可选参数如列表页的筛选条件可以传也可以不传。参数校验在目标页面的onPageShow或aboutToAppear中对参数进行校验缺失必选参数时给出友好提示或跳转回退。// 目标页面参数校验aboutToAppear(){constparamsrouter.getParams()asRouteParams[RouterMap.BILL_DETAIL];if(!params?.billId){console.error(缺少必选参数 billId);router.back();return;}this.billIdparams.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{staticnavigateToTextendsRouterMap(target:T,params?:RouteParams[T]){if(!RouterGuard.canNavigate(target))return;router.pushUrl({url:target,params});}}8. DialogMap 对话框路由对话框也可以像页面一样管理DialogMap 枚举管理所有对话框路由确认框、选择框、输入框等。通过统一的 Dialog 管理器打开/关闭对话框。项目代码案例文件路径lib_router/RouterMap.etsexportenumRouterMap{INDEXpages/Index,BILL_LISTpages/BillList,BILL_DETAILpages/BillDetail,ADD_BILLpages/AddBill,ASSET_LISTpages/AssetList,ASSET_DETAILpages/AssetDetail,ADD_ASSETpages/AddAsset,STATISTICSpages/Statistics,SETTINGSpages/Settings,LOGINpages/Login,MEMBERSHIPpages/Membership,FEEDBACKpages/Feedback,// ... 共 17 个路由目标}exportenumDialogMap{CONFIRM_DELETEdialog/ConfirmDelete,DATE_PICKERdialog/DatePicker,CATEGORY_PICKERdialog/CategoryPicker,}RouterModule 封装exportclassRouterModule{staticnavigateTo(target:RouterMap,params?:Recordstring,Object){router.pushUrl({url:target,params});}}通过 RouterMap RouterModule RouterGuard 的组合MoneyTrack 实现了路由的集中管理、类型安全、守卫拦截三大目标。任意页面都只需调用RouterModule.navigateTo(RouterMap.BILL_LIST)即可跳转完全不感知目标页面的具体路径和所在模块。推荐参考文档路由解耦设计模式router.pushUrl API 参考Navigation NavPathStack 导航文档