HarmonyOS ArkUI Navigation 导航组件从入门到实战完整指南本文全面介绍 HarmonyOS ArkUI 中 Navigation 导航组件的架构设计、核心 API、路由配置和页面生命周期管理并通过完整示例演示实际开发流程帮助开发者构建规范的页面导航体系。效果一、前言在 HarmonyOS 应用开发中页面导航是连接各个功能模块的桥梁。传统开发中使用router模块进行页面跳转但随着应用复杂度提升router在路由管理、参数传递、生命周期控制、转场动画等方面的局限性日益明显。Navigation是 ArkUI 推出的新一代导航框架它提供了声明式的导航架构集成了页面栈管理、路由注册、生命周期回调、转场动画等能力是当前官方推荐的标准导航方案。重要提示router模块已被标记为废弃新项目应直接使用 Navigation。二、Navigation 架构概览Navigation 采用三层架构Navigation根容器 ├── NavBar导航栏标题、菜单、工具栏 ├── NavDestination子页面容器各自独立生命周期 └── NavPathStack管理页面栈状态和转场2.1 核心组件职责组件职责Navigation导航根容器管理导航栏和页面展示区域NavDestination子页面容器每个目标页面使用 NavDestination 包裹NavPathStack页面栈管理器控制 push/pop/replace 等操作2.2 导航模式模式适用场景说明Stack屏幕宽度 600vp整页替换类似手机页面跳转Split屏幕宽度 600vp左侧导航栏 右侧内容区类似平板双栏Auto自适应系统根据屏幕宽度自动切换三、基础用法3.1 最简单的导航结构EntryComponentstruct AppEntry{Provide(navStack)pathStack:NavPathStacknewNavPathStack();build(){Navigation(this.pathStack){// NavBar 内容首页Column(){Text(首页).fontSize(24).fontWeight(FontWeight.Bold)Button(前往详情).onClick((){this.pathStack.pushPath({name:DetailPage,param:{id:1}});})}.width(100%).height(100%).justifyContent(FlexAlign.Center)}.title(应用标题).navDestination(this.pageBuilder)}BuilderpageBuilder(name:string,param:Object){NavDestination(){DetailPage()}}}3.2 NavPathStack 页面栈操作NavPathStack是导航的核心控制器常用操作如下// 压入新页面推荐支持路由参数this.pathStack.pushPath({name:DetailPage,param:data});// 按名称压入简化写法this.pathStack.pushPathByName(DetailPage,paramData);// 弹出当前页面this.pathStack.pop();// 弹出并传回结果this.pathStack.pop({result:操作成功});// 替换当前页面this.pathStack.replacePath({name:OtherPage,param:data});// 弹出到指定页面this.pathStack.popToName(HomePage);// 弹出到指定索引this.pathStack.popToIndex(0);// 清空页面栈this.pathStack.clear();// 获取栈大小this.pathStack.getSize();// 获取当前索引this.pathStack.getCurrentIndex();3.3 NavPathStack 方法速查表方法说明pushPath(info)压入目标页面可携带参数pushPathByName(name, param)按名称压入简化写法pop(param?)弹出当前页可传回结果popToName(name)弹出到指定名称的页面popToIndex(index)弹出到指定索引的页面replacePath(info)替换当前页面clear()清空页面栈getAllPathName()获取栈中所有页面名称getParamByIndex(index)获取指定索引的参数getCurrentIndex()获取当前页面索引getSize()获取页面栈大小四、路由配置4.1 静态路由route_map.json在src/main/resources/base/profile/下创建route_map.json{routerMap:[{name:HomePage,pageSourceFile:src/main/ets/pages/HomePage.ets,buildFunction:HomePageBuilder},{name:DetailPage,pageSourceFile:src/main/ets/pages/DetailPage.ets,buildFunction:DetailPageBuilder}]}4.2 页面注册在每个页面文件中导出Builder函数// HomePage.etsBuilderexportfunctionHomePageBuilder(){HomePage();}EntryComponentstruct HomePage{build(){NavDestination(){Text(首页内容)}}}4.3 module.json5 配置{ module: { // ... pages: $profile:main_pages, routerMap: $profile:route_map } }4.4 配置应用启动页面应用的启动页面由EntryAbility.ets中的windowStage.loadContent()决定而非main_pages.json中的页面顺序。// entry/src/main/ets/entryability/EntryAbility.etsonWindowStageCreate(windowStage:window.WindowStage):void{// 修改此处参数即可切换启动页面windowStage.loadContent(pages/MovieFilterPage,(err){if(err.code){hilog.error(DOMAIN,testTag,Failed to load the content. Cause: %{public}s,JSON.stringify(err));return;}hilog.info(DOMAIN,testTag,Succeeded in loading the content.);});}常见误区仅修改main_pages.json中的页面顺序并不能改变启动页面。main_pages.json仅用于页面路由注册真正决定启动页面的是EntryAbility.ets中loadContent的路径参数。五、页面生命周期NavDestination 提供完整的生命周期回调5.1 生命周期回调NavDestination(){Column(){Text(页面内容)}}.onReady((ctx:NavDestinationContext){// 页面创建并准备好时调用// 可通过 ctx.pathInfo.param 获取传入参数constparamctx.pathInfo.param;}).onShown((){// 页面变为可见时调用}).onHidden((){// 页面变为不可见时调用}).onBackPressed((){// 返回键按下时调用// 返回 true 拦截默认返回false 允许默认返回returnfalse;})5.2 生命周期顺序页面首次进入onReady → onShown 页面被覆盖push新页面onHidden 页面重新显示pop回来onShown 页面即将销毁onHidden → 销毁 返回键按下onBackPressed六、参数传递6.1 传递简单数据// 传递this.pathStack.pushPath({name:DetailPage,param:Hello World});// 接收在 NavDestination 的 onReady 中.onReady((ctx:NavDestinationContext){constmessagectx.pathInfo.paramasstring;})6.2 传递复杂对象interfaceProductInfo{id:string;name:string;price:number;}// 传递this.pathStack.pushPath({name:ProductDetail,param:{id:p001,name:示例商品,price:99.9}asProductInfo});// 接收.onReady((ctx:NavDestinationContext){constproductctx.pathInfo.paramasProductInfo;})6.3 最佳实践传递 ID按需加载// 推荐传递 ID在目标页面按需加载完整数据this.pathStack.pushPath({name:ProductDetail,param:productId// 只传 ID});// 避免传递整个大对象this.pathStack.pushPath({name:ProductDetail,param:largeProductObject// 不推荐});七、Navigation 配置7.1 标题栏Navigation(this.pathStack){// ...}.title(页面标题).titleMode(NavigationTitleMode.Mini)// 紧凑标题.titleSubtitle({title:主标题,subtitle:副标题})7.2 隐藏标题栏和工具栏Navigation(this.pathStack){// ...}.hideTitleBar(true).hideToolBar(true)7.3 菜单按钮Navigation(this.pathStack){// ...}.menus([{value:搜索,icon:$r(app.media.search),action:(){/* 搜索逻辑 */}},{value:设置,icon:$r(app.media.settings),action:(){/* 设置逻辑 */}}])八、转场动画8.1 默认转场Navigation 提供默认的滑动转场效果。8.2 自定义转场NavDestination(){Column(){Text(新页面)}}.transition(TransitionEffect.OPACITY.animation({duration:300,curve:Curve.EaseInOut}))8.3 常用转场效果// 左滑进入TransitionEffect.SLIDE_LEFT.animation({duration:300})// 淡入TransitionEffect.OPACITY.animation({duration:200})// 组合效果TransitionEffect.asSequence([TransitionEffect.OPACITY.scale({scale:0.95}),TransitionEffect.OPACITY])九、完整示例多页面导航应用// 首页 BuilderexportfunctionHomeBuilder(){HomePage();}EntryComponentV2struct HomePage{Provider(appNavStack)pathStack:NavPathStacknewNavPathStack();build(){Navigation(this.pathStack){Column({space:16}){Text(导航示例).fontSize(26).fontWeight(FontWeight.Bold)Button(商品列表).width(200).onClick((){this.pathStack.pushPath({name:ProductList,param:{category:electronics}});})Button(关于页面).width(200).onClick((){this.pathStack.pushPathByName(About,null);})}.width(100%).height(100%).justifyContent(FlexAlign.Center)}.title(首页).navDestination(this.routeBuilder)}BuilderrouteBuilder(name:string,param:Object){NavDestination(){if(nameProductList){ProductListPage()}elseif(nameAbout){AboutPage()}}}}// 商品列表页 BuilderexportfunctionProductListBuilder(){ProductListPage();}ComponentV2struct ProductListPage{Localproducts:string[][手机,电脑,平板,耳机];build(){Column({space:12}){Text(商品列表).fontSize(20).fontWeight(FontWeight.Bold)ForEach(this.products,(product:string){Row(){Text(product).fontSize(16)Blank()Text().fontSize(16).fontColor(#CCCCCC)}.width(100%).padding(16).backgroundColor(#FAFAFA).borderRadius(8)},(product:string)product)}.padding(20).width(100%).height(100%)}}// 关于页 BuilderexportfunctionAboutBuilder(){AboutPage();}ComponentV2struct AboutPage{build(){Column(){Text(关于).fontSize(20).fontWeight(FontWeight.Bold)Text(Navigation 导航示例应用 v1.0).fontSize(14).fontColor(#666666).margin({top:12})}.justifyContent(FlexAlign.Center).width(100%).height(100%)}}十、Navigation vs router 对比特性Navigationrouter已废弃架构模式声明式组件化命令式URL 跳转页面栈管理NavPathStack 内置需手动管理参数传递支持任意对象仅支持序列化数据生命周期onReady/onShown/onHidden仅 onPageShow/onPageHide转场动画丰富且可自定义有限响应式适配自动支持分栏模式不支持V2 状态管理完全兼容需额外适配官方推荐推荐废弃十一、常见问题Q1NavDestination 中如何获取 NavPathStack// 方式一通过 Provide/Consume 共享Provide(navStack)pathStack:NavPathStacknewNavPathStack();// 方式二V2 中使用 Provider/ConsumerProvider(navStack)pathStack:NavPathStacknewNavPathStack();// 子页面获取Consumer(navStack)pathStack:NavPathStacknewNavPathStack();Q2如何拦截返回键NavDestination(){// 页面内容}.onBackPressed((){// 执行自定义逻辑如保存数据、确认退出if(this.hasUnsavedChanges){this.showConfirmDialog();returntrue;// 拦截默认返回}returnfalse;// 允许默认返回})Q3如何在子页面中操作页面栈ComponentV2struct ChildPage{Consumer(navStack)pathStack:NavPathStacknewNavPathStack();build(){NavDestination(){Button(返回首页).onClick((){this.pathStack.clear();// 清空栈回到首页})Button(返回上一页).onClick((){this.pathStack.pop();})}}}十二、最佳实践新项目直接使用 Navigation不要使用已废弃的router模块。通过Provide/Provider共享 NavPathStack确保所有页面都能访问导航控制器。传递 ID 而非完整对象减少内存占用目标页面按需加载。使用route_map.json注册路由便于维护和管理。启动页面由EntryAbility.ets决定修改windowStage.loadContent()的参数而非main_pages.json顺序。在onBackPressed中处理返回逻辑如表单保存确认、数据清理等。配合 V2 状态管理使用ComponentV2Local/Param提供更现代的开发体验。隐藏不需要的标题栏使用hideTitleBar(true)自定义页面头部。十三、总结Navigation 是 HarmonyOS 应用的推荐导航方案它通过Navigation根容器 NavDestination子页面 NavPathStack栈管理的三层架构提供了声明式、可维护、高性能的页面导航能力。掌握 NavPathStack 的栈操作、NavDestination 的生命周期回调和 route_map.json 的路由配置即可构建出规范、流畅的多页面应用。参考文档Navigation