HarmonyOS ArkUI Navigation组件完全指南从入门到精通本文基于 HarmonyOS NEXTAPI 23开发环境全面讲解 ArkUI Navigation 组件的使用方法涵盖页面导航、路由管理、生命周期、转场动画等核心知识帮助开发者构建现代化的导航架构。效果一、前言在 HarmonyOS 应用开发中页面导航是应用架构的骨架。ArkUI 提供了Navigation组件作为新一代导航方案替代了传统的router模块带来了更灵活的页面管理、更丰富的生命周期控制和更优雅的转场动画。本文将从零开始系统讲解 Navigation 组件的核心概念和实战用法。二、Navigation 导航架构2.1 三层架构Navigation 采用清晰的三层架构设计Navigation根容器 ├── NavBar导航栏标题、菜单、工具栏 ├── NavDestination子页面容器独立生命周期 └── NavPathStack页面栈管理器Navigation页面导航的根容器管理导航栏和内容区域NavDestination子页面的容器组件每个目标页面独立管理NavPathStack程序化控制页面栈支持 push、pop、replace 等操作2.2 导航模式模式触发条件说明单栏模式Stack屏幕宽度 600vp整页切换适合手机分栏模式Split屏幕宽度 600vp左侧导航 右侧内容适合平板三、基础用法3.1 最简 Navigation 示例EntryComponentstruct NavigationDemo{pathStack:NavPathStacknewNavPathStack();build(){Navigation(this.pathStack){// 首页内容NavBar 区域Column(){Text(首页).fontSize(28).fontWeight(FontWeight.Bold)Button(跳转到详情页).margin({top:20}).onClick((){// 通过 NavPathStack 推送新页面this.pathStack.pushPath({name:DetailPage,param:{id:1,title:文章标题}});})}.width(100%).height(100%).justifyContent(FlexAlign.Center)}.title(应用首页).navDestination(this.PageMap)}BuilderPageMap(name:string,param:Object){NavDestination(){DetailContent({param:param})}.title(详情页)}}3.2 配合路由表使用推荐在实际项目中推荐使用route_map.json配置路由表实现页面解耦步骤1在src/main/resources/base/profile/下创建route_map.json{routerMap:[{name:DetailPage,pageSourceFile:src/main/ets/pages/DetailPage.ets,buildFunction:DetailBuilder,data:{description:详情页面}}]}步骤2在目标页面文件中导出Builder函数// DetailPage.etsBuilderexportfunctionDetailBuilder(name:string,param:Object){DetailPage();}EntryComponentstruct DetailPage{build(){NavDestination(){Column(){Text(详情页面内容).fontSize(20)}.width(100%).height(100%)}.hideTitleBar(true)}}步骤3在module.json5中注册路由表{ module: { // ... pages: $profile:main_pages, routerMap: $profile:route_map } }步骤4使用pushPathByName跳转this.pathStack.pushPathByName(DetailPage,{id:1});四、NavPathStack 页面栈管理NavPathStack是 Navigation 的核心提供丰富的页面栈操作方法。4.1 常用操作方法EntryComponentstruct StackOperationDemo{pathStack:NavPathStacknewNavPathStack();build(){Navigation(this.pathStack){Column({space:16}){// 入栈推送新页面Button(Push 新页面).onClick((){this.pathStack.pushPath({name:SubPage,param:data});})// 入栈简写Button(Push by Name).onClick((){this.pathStack.pushPathByName(SubPage,null);})// 替换当前页面Button(Replace 当前页).onClick((){this.pathStack.replacePath({name:OtherPage});})// 出栈返回上一页Button(Pop 返回).onClick((){this.pathStack.pop();})// 出栈并返回结果Button(Pop with Result).onClick((){this.pathStack.pop({result:success});})// 返回到指定页面Button(Pop to Name).onClick((){this.pathStack.popToName(HomePage);})// 清空页面栈Button(Clear All).onClick((){this.pathStack.clear();})// 查询栈信息Button(Stack Info).onClick((){letsizethis.pathStack.size();letallNamesthis.pathStack.getAllPathName();console.info(栈大小:${size}, 页面:${JSON.stringify(allNames)});})}.width(100%).height(100%)}.navDestination(this.PageMap)}BuilderPageMap(){NavDestination(){Text(子页面)}}}4.2 方法速查表方法说明pushPath(info)入栈携带参数pushPathByName(name, param)按名称入栈replacePath(info)替换当前页面pop(param?)出栈可返回结果popToName(name)出栈到指定名称的页面popToIndex(index)出栈到指定索引clear()清空所有页面size()获取栈大小getAllPathName()获取所有页面名称getCurrentIndex()获取当前页面索引getParamByIndex(index)获取指定索引的参数五、NavDestination 生命周期NavDestination提供完整的页面生命周期回调是 Navigation 优于传统 router 的关键特性。5.1 生命周期回调BuilderexportfunctionLifecycleBuilder(name:string,param:Object){LifecyclePage();}EntryComponentstruct LifecyclePage{Statemessage:string页面初始化中...;build(){NavDestination(){Column(){Text(this.message).fontSize(18)}.width(100%).height(100%).justifyContent(FlexAlign.Center)}.onReady((ctx:NavDestinationContext){// 页面就绪可以获取 pathStack 和参数letparamctx.pathInfo.param;this.message就绪完成参数:${JSON.stringify(param)};}).onShown((){// 页面显示适合刷新数据或恢复动画this.message页面已显示;}).onHidden((){// 页面隐藏适合暂停动画或保存状态this.message页面已隐藏;}).onBackPressed((){// 返回键拦截返回 true 表示拦截默认行为console.info(返回键被按下);returnfalse;// 不拦截允许默认返回})}}5.2 生命周期顺序onReady → onShown → (用户操作) → onHidden → (重新显示) → onShown → ...回调触发时机典型用途onReady页面创建并加入导航树后初始化数据、获取参数onShown页面变为可见时刷新UI、恢复动画onHidden页面被遮挡时暂停任务、保存状态onBackPressed返回键按下时拦截返回、确认退出六、导航栏配置6.1 标题设置Navigation(this.pathStack){// 首页内容}.title(应用标题).titleMode(NavigationTitleMode.Mini)// 紧凑标题模式6.2 菜单配置Navigation(this.pathStack){// 首页内容}.menus([{value:search,icon:$r(app.media.ic_search),action:(){console.info(搜索被点击);}},{value:settings,icon:$r(app.media.ic_settings),action:(){console.info(设置被点击);}}])6.3 工具栏配置Navigation(this.pathStack){// 首页内容}.toolbar([{value:edit,icon:$r(app.media.ic_edit),action:(){}},{value:share,icon:$r(app.media.ic_share),action:(){}}])6.4 隐藏导航栏在闪屏页等场景中需要隐藏导航栏Navigation(this.pathStack){SplashContent()}.hideToolBar(true).hideNavBar(true)// 隐藏整个导航栏七、转场动画7.1 默认转场Navigation 默认提供滑动转场动画可以通过transition自定义NavDestination(){Column(){Text(自定义转场页面)}}.transition(TransitionEffect.OPACITY.animation({duration:300,curve:Curve.EaseOut}))7.2 常用转场效果// 淡入淡出TransitionEffect.OPACITY.animation({duration:300})// 左滑进入TransitionEffect.SLIDE_LEFT// 右滑进入TransitionEffect.SLIDE_RIGHT// 组合效果缩放 淡入TransitionEffect.asSequence([TransitionEffect.OPACITY.scale({scale:0.95}),TransitionEffect.OPACITY])八、实战示例闪屏页导航架构下面是一个典型的闪屏页 主页的导航架构示例// SplashPage.ets - 闪屏页入口import{HomePage}from./HomePage;BuilderexportfunctionSplashBuilder(name:string,param:Object){SplashPage();}EntryComponentstruct SplashPage{pageInfos:NavPathStacknewNavPathStack();StateisHideNavBar:booleanfalse;privatetimerId:number-1;aboutToAppear():void{// 3秒后自动跳转到主页this.timerIdsetTimeout((){this.isHideNavBartrue;this.pageInfos.pushPathByName(HomePage,null,false);},3000);}aboutToDisappear():void{if(this.timerId!-1){clearTimeout(this.timerId);}}// navDestination 构建器路由双重保障BuilderPageMap(name:string,param:Object){if(nameHomePage){HomePage()}}build(){Navigation(this.pageInfos){Column(){Image($r(app.media.splash_bg)).width(100%).height(100%).objectFit(ImageFit.Cover)}.width(100%).height(100%)}.hideToolBar(true).hideNavBar(this.isHideNavBar).backgroundColor(#020215).navDestination(this.PageMap)}}// HomePage.ets - 主页需 export 导出BuilderexportfunctionHomeBuilder(name:string,param:Object){HomePage();}EntryComponentexportstruct HomePage{build(){NavDestination(){Column(){Text(欢迎来到主页).fontSize(24).fontWeight(FontWeight.Bold).fontColor(#e2e8f0)}.width(100%).height(100%).justifyContent(FlexAlign.Center).linearGradient({angle:180,colors:[[#020215,0.0],[#06062a,0.5],[#080828,1.0]]})}.backgroundColor(#020215).hideTitleBar(true)}}架构要点闪屏页作为 Navigation 的根内容隐藏导航栏通过pushPathByName跳转到主页animated: false关闭动画主页使用NavDestination容器通过onReady获取 pathStack在aboutToDisappear中清理定时器防止内存泄漏双重路由保障同时使用route_map.jsonnavDestination构建器确保路由可靠解析Navigation 设置背景色.backgroundColor(#020215)防止系统默认背景色透出NavDestination 设置背景色.backgroundColor(#020215)覆盖默认黄色背景主页 struct 必须 export被闪屏页navDestination构建器直接导入引用九、最佳实践实践说明使用 route_map.json页面解耦便于维护和团队协作navDestination 双重保障同时配置 route_map.json 和 navDestination 构建器防止路由解析失败避免使用 router 模块router 已废弃新项目统一使用 NavigationNavDestination 单根组件每个 Builder 必须返回单个根组件NavDestination 设置背景色显式设置 backgroundColor防止系统默认黄色背景透出Navigation 设置背景色根容器也需设置背景色避免转场时露出默认底色目标页面 struct 加 export被 navDestination 构建器导入时必须导出传递轻量参数只传 ID 等轻量数据大数据在目标页加载清理定时器在aboutToDisappear中清理防止内存泄漏合理使用生命周期在onReady初始化onHidden暂停十、总结Navigation 是 HarmonyOS 推荐的导航方案提供了清晰的三层架构、强大的 NavPathStack 栈管理和丰富的生命周期控制。本文从基础用法到实战架构系统讲解了 Navigation 的核心知识点。关键要点回顾Navigation 是根容器NavDestination 是子页面容器NavPathStack 管理页面栈push、pop、replace、clear生命周期回调onReady、onShown、onHidden、onBackPressed使用 route_map.json navDestination 双重路由保障闪屏页场景hideNavBar pushPathByName 跳转Navigation 和 NavDestination 都需显式设置 backgroundColor被引用的页面 struct 必须加 export 关键字