掌握鸿蒙 Navigation 路由系统实现页面间流畅跳转一、前言页面路由是 App 的基础骨架决定了用户如何在不同页面间导航。HarmonyOS 提供了两套路由方案Router API轻量级路由适合简单跳转Navigation 组件功能强大的声明式导航支持路由栈管理、深层链接等本文将从基础到进阶全面覆盖徒步迹App 中的页面路由实现。二、Router API 基础Router 是系统提供的轻量路由 API适合页面数不多、路由结构简单的场景。2.1 引入模块import{router}fromkit.ArkUI;2.2 基本跳转// 1. pushUrl - 推入新页面可返回router.pushUrl({url:pages/RouteDetailPage,params:{// 传递参数routeId:123,routeName:香山徒步,},});// 2. replaceUrl - 替换当前页面不可返回router.replaceUrl({url:pages/LoginPage,});// 3. 返回上一页router.back();// 4. 返回指定页面router.back({url:pages/HomePage,});2.3 接收参数// 在目标页面中接收参数EntryComponentstruct RouteDetailPage{StaterouteId:number0;StaterouteName:string;aboutToAppear():void{// 通过 router.getParams() 获取参数constparamsrouter.getParams()asRecordstring,Object;if(params){this.routeIdparams[routeId]asnumber;this.routeNameparams[routeName]asstring;}}}三、Navigation 组件Navigation 是鸿蒙 NEXT 推荐的声明式导航方案功能更强大3.1 基本结构Navigation(){// 导航内容区域Column(){Text(首页内容)}}.title(徒步迹).mode(NavigationMode.Auto);// 自动适配单栏/双栏模式3.2 NavPathStack 路由栈NavPathStack 是 Navigation 的核心路由管理工具EntryComponentstruct MainPage{// 创建路由栈privatenavStack:NavPathStacknewNavPathStack();build(){Navigation(this.navStack){Column(){Button(查看路线详情).onClick((){// 推入新页面this.navStack.pushPath({name:RouteDetailPage,// 路由名称param:{// 参数routeId:1,routeName:香山徒步,},});});Button(记录轨迹).onClick((){this.navStack.pushPathByName(TrackingPage,null);});}}.title(徒步迹).navDestination(this.PageMap);// 注册页面映射}// 页面映射BuilderPageMap(name:string,param:Object){if(nameRouteDetailPage){RouteDetailPage({routeId:param[routeId]asnumber});}elseif(nameTrackingPage){TrackingPage();}}}3.3 路由栈操作// 1. 推入页面navStack.pushPath({name:ProfilePage,param:{userId:1}});navStack.pushPathByName(SettingsPage,null);// 2. 替换当前页面navStack.replacePath({name:LoginPage});navStack.replacePathByName(RegisterPage,{phone:13800138000});// 3. 返回上一页navStack.pop();// 返回上一页navStack.popToName(HomePage);// 返回到指定页面navStack.popToIndex(0);// 返回到根页面// 4. 清除所有路由navStack.clear();// 5. 获取路由栈信息letpathInfonavStack.getPathByName(HomePage);letindexnavStack.getIndexByName(HomePage);letsizenavStack.size();// 路由栈大小四、页面配置所有需要路由跳转的页面必须在 module.json5 中配置// module.json5 的 pages 字段 { module: { pages: $profile:main_pages, // ... } }// resources/base/profile/main_pages.json { src: [ pages/SplashPage, pages/LoginPage, pages/RegisterPage, pages/HomePage, pages/RouteListPage, pages/RouteDetailPage, pages/TrackingPage, pages/TrackHistoryPage, pages/HealthDataPage, pages/TeamListPage, pages/TeamDetailPage, pages/PhotoGalleryPage, pages/RoadbookListPage, pages/RoadbookDetailPage, pages/ProfilePage, pages/SettingsPage, pages/AboutPage ] }五、实战徒步迹导航结构5.1 整体路由设计SplashPage (启动页) └── LoginPage (登录) └── HomePage (首页) ├── RouteListPage → RouteDetailPage ├── TrackingPage ├── TeamListPage → TeamDetailPage ├── PhotoGalleryPage ├── RoadbookListPage → RoadbookDetailPage ├── HealthDataPage ├── TrackHistoryPage ├── ProfilePage │ ├── SettingsPage │ └── AboutPage └── (通过底部Tab导航)5.2 首页 Tab 切换实现// HomePage.ets - 带Tab导航的首页EntryComponentstruct HomePage{StatecurrentTab:number0;privatetabs:string[][首页,路线,记录,团队,我的];build(){Column(){// 内容区域if(this.currentTab0){this.HomeContent();}// 底部 TabBarRow(){ForEach(this.tabs,(tab:string,index:number){Column(){Text(tab).fontSize(12).fontColor(this.currentTabindex?$r(app.color.primary_color):$r(app.color.text_secondary));}.layoutWeight(1).padding(8).onClick((){this.currentTabindex;// 切换到其他Tab时跳转到对应页面if(index1)router.pushUrl({url:pages/RouteListPage});elseif(index2)router.pushUrl({url:pages/TrackingPage});elseif(index3)router.pushUrl({url:pages/TeamListPage});elseif(index4)router.pushUrl({url:pages/ProfilePage});});},(tab:string)tab);}.width(100%).height(56).backgroundColor(Color.White);}.width(100%).height(100%);}BuilderHomeContent(){Scroll(){// 首页内容...}}}5.3 页面间参数传递最佳实践// 从路线列表页跳转到详情页// RouteListPage.etsrouter.pushUrl({url:pages/RouteDetailPage,params:{routeId:1,source:RouteListPage,},});// RouteDetailPage.ets - 接收参数aboutToAppear():void{constparamsrouter.getParams()asRecordstring,Object;if(params){this.routeIdparams[routeId]asnumber;this.sourceparams[source]asstring;}}六、路由动画ArkUI 支持页面切换动画的自定义// 自定义转场动画router.pushUrl({url:pages/RouteDetailPage,params:{routeId:123},},router.RouterMode.Single,(err){if(!err){// 跳转成功}});// 页面内使用 animateTo 控制动画animateTo({duration:300,curve:Curve.Friction},(){// 状态变化触发 UI 更新this.isVisibletrue;});七、常见问题7.1 页面跳转无反应检查 main_pages.json 中是否注册了该页面路径。7.2 参数传递丢失确保参数类型为Recordstring, Object复杂对象建议先序列化。// 传递复杂对象前先序列化constserializedJSON.stringify(complexObject);router.pushUrl({url:pages/RouteDetailPage,params:{routeData:serialized},});// 接收端反序列化constdataJSON.parse(params[routeData]asstring);7.3 跨模块路由// 跨 HAP 模块路由router.pushUrl({url:bundle:com.hiking.feature/ets/pages/FeaturePage,});八、总结本文全面介绍了鸿蒙系统的页面路由方案从简单的 Router API 到强大的 Navigation 组件再到徒步迹的完整导航结构设计。良好的路由设计是 App 架构的基础。下一篇文章将学习资源管理与多主题适配让徒步迹支持多种视觉风格。下一篇预告鸿蒙原生开发手记徒步迹 - 资源管理与多主题适配如有疑问欢迎留言交流。