鸿蒙开发 Navigation 路由教程：从入门到实战

文章目录一、引言二、Navigation 核心概念2.1 核心组成三、实战登录页 → 个人中心3.1 创建项目文件结构3.2 配置路由映射表router_map.json3.3 在 module.json5 中添加 routerMap 配置3.4 登录页Index.ets3.5 个人中心页ProfilePage.ets四、拦截器五、注意事项与最佳实践5.1 前置条件5.2 页面结构规范5.3 显示模式5.4 标题栏与菜单5.6 页面生命周期5.7 返回处理5.8 拦截器六、总结一、引言在 HarmonyOS 应用开发中页面路由是构建多页面应用的核心能力。Navigation组件作为官方推荐的路由容器不仅提供了强大的页面栈管理能力还支持单栏、分栏和自适应三种显示模式能够轻松适配手机、平板、折叠屏等多种设备形态。本文将从一个完整的登录跳转个人中心示例出发带你掌握Navigation的核心概念、配置步骤和实战技巧。二、Navigation 核心概念Navigation是 HarmonyOS 提供的路由容器组件支持单栏Stack、分栏Split和自适应Auto三种显示模式适用于模块内和跨模块的页面路由切换。与传统的Router路由相比Navigation支持更丰富的转场动效、多端部署能力和更灵活的栈操作推荐将Navigation作为应用的顶层根容器。2.1 核心组成NavPathStack管理页面栈的控制器提供push、pop、replace、clear等操作方法。NavDestination子页面的根容器每个跳转的目标页面必须包裹在NavDestination中。.navDestination()属性用于设置页面路由映射表将页面名称字符串与Builder构建函数关联。三、实战登录页 → 个人中心以下示例演示了从登录页跳转到个人中心页面的完整流程。登录页使用Navigation作为根容器点击登录按钮后通过pushPathByName跳转到个人中心并将用户名作为参数传递。3.1 创建项目文件结构src/main/ets/ ├── pages/ │ ├── Index.ets // 登录页Entry 入口 │ └── ProfilePage.ets // 个人中心页目标页面 └── resources/base/profile/ └── router_map.json // 路由映射表3.2 配置路由映射表router_map.json在resources/base/profile/目录下创建router_map.json文件注册所有需要跳转的页面{routerMap:[{name:profile,pageSourceFile:src/main/ets/pages/ProfilePage.ets,buildFunction:buildProfilePage}]}3.3 在 module.json5 中添加 routerMap 配置打开src/main/module.json5文件在对应模块的配置中添加routerMap字段{pages:$profile:main_pages,routerMap:$profile:router_map,requestPermissions:[]}3.4 登录页Index.ets登录页作为应用入口使用Navigation作为根容器包含账号、密码输入框和登录按钮。import{buildProfilePage}from./ProfilePage2;interfaceIUserInfo{userName:string}EntryComponentstruct Index{privatepageStack:NavPathStacknewNavPathStack();Stateusername:stringadmin;Statepassword:string123456;build(){Navigation(this.pageStack){Column({space:16}){TextInput({text:this.username!!,placeholder:账号}).type(InputType.USER_NAME)TextInput({text:this.password,placeholder:密码}).type(InputType.Password).showPasswordIcon(true)Button(登录).width(80%).enabled(this.username.length0this.password.length0).onClick((){// 跳转到个人中心并传递用户名constparam:IUserInfo{userName:this.username}this.pageStack.pushPathByName(profile,param);})}.padding(16)}.title(登录)// 设置页面标题.titleMode(NavigationTitleMode.Full)// 设置页面标题栏显示模式.navDestination(this.pageMap)}BuilderpageMap(name:string,param:object){if(nameprofile){buildProfilePage(paramasRecordstring,Object);}}}运行效果3.5 个人中心页ProfilePage.ets目标页面根组件必须是NavDestination并通过Builder导出一个构建函数函数名与router_map.json中配置的buildFunction完全一致。interfaceIParams{userName:string}// 注意页面根组件必须是 NavDestinationComponentstruct ProfilePage{privatepageInfos:NavPathStack{}asNavPathStack;privateuserName:string默认用户;build(){NavDestination(){Column({space:20}){Text(个人中心).fontSize(24).fontWeight(FontWeight.Bold)Text(用户名this.userName).fontSize(18)Button(返回登录页).width(80%).onClick((){// 返回上一页this.pageInfos.pop();})}.padding(16).width(100%).height(100%)}.title(个人中心)// 设置页面标题.hideTitleBar(false)// 设置是否隐藏标题栏.onReady((context:NavDestinationContext){// 当NavDestination即将构建子组件之前会触发此回调 参数context中包含 NavDestination 上下文信息this.pageInfoscontext.pathStack// 当前 NavDestination 所处的导航控制器constparamscontext.pathInfo.paramasIParams;// context.pathInfo 路由页面信息this.userNameparams.userName})}}// 必须导出 Builder 函数名称与 router_map.json 中的 buildFunction 一致BuilderexportfunctionbuildProfilePage(param:Recordstring,Object):void{ProfilePage()}运行效果四、拦截器Navigation组件提供的setInterception方法是 HarmonyOS 实现页面跳转拦截的核心能力。它可以拦截页面跳转过程中的关键节点让开发者能够在页面路由时执行统一的逻辑例如登录鉴权、权限校验、埋点统计等。该方法接收一个NavigationInterception对象包含以下三个回调willShow页面跳转前的回调允许操作栈在当前跳转中生效。拦截的页面会被创建。didShow页面跳转后回调。modeChangeNavigation单双栏显示状态发生变更时触发该回调。interception页面跳转前的回调允许操作栈在当前跳转中生效。拦截的页面不会被创建。以下代码演示如何在跳转到“收藏页面”前检查用户是否已登录若未登录则拦截并重定向到登录页面。EntryComponentstruct Index{// 使用 AppStorage 管理登录状态方便跨页面共享StorageLink(isLogged)isLogged:booleanfalse;// 创建导航栈privatenavPathStack:NavPathStacknewNavPathStack();aboutToAppear():void{// 注册路由拦截this.navPathStack.setInterception({willShow:(from:NavDestinationContext|navBar,to:NavDestinationContext|navBar,operation:NavigationOperation,animated:boolean){// 只拦截 push 操作operation 1if(operationNavigationOperation.PUSH){consttargettoasNavDestinationContext;// 判断目标页面名是否为需要登录的页面if(target.pathInfo?.nameCollectionPage!this.isLogged){// 移除当前 push 的页面取消跳转target.pathStack.pop();// 替换路径到登录页this.navPathStack.replacePathByName(LoginPage,{redirect:CollectionPage});}}}});}build(){Navigation(this.navPathStack){Column({space:20}){Button(跳转收藏页).width(80%).onClick((){this.navPathStack.pushPathByName(CollectionPage,null);});Button(跳转登录页).width(80%).onClick((){this.navPathStack.pushPathByName(LoginPage,null);});}.width(100%).height(100%)}.title(首页).navBarWidth(100%).navDestination(this.buildDestinations)}// 路由表构建BuilderbuildDestinations(name:string,param:object){if(nameCollectionPage){CollectionPage();}elseif(nameLoginPage){LoginPage({param});}}}// 收藏页面需要登录Componentstruct CollectionPage{build(){NavDestination(){Text(收藏页面 - 已登录).fontSize(20)}}}// 登录页面Componentstruct LoginPage{StorageLink(isLogged)isLogged:booleanfalse;privateparam?:object;privatenavPathStack{}asNavPathStack;build(){NavDestination(){Column({space:20}){Text(登录页面).fontSize(20)Button(登录).width(80%).onClick((){// 登录成功后更新状态this.isLoggedtrue;// 跳转回原来想去的页面if((this.paramasRecordstring,string)?.redirectCollectionPage){this.navPathStack.replacePathByName(CollectionPage,null);}else{this.navPathStack.pop();}});}.width(100%).height(100%)}.onReady((context:NavDestinationContext){this.navPathStackcontext.pathStack})}}运行效果代码要点说明状态管理使用StorageLink(isLogged)将登录状态存入AppStorage确保各页面可共享且同步变化。拦截判断在willShow回调中通过operation NavigationOperation.PUSH只拦截新页面的压栈避免影响返回操作再根据目标页面名称CollectionPage和登录状态决定是否放行。拦截动作未登录时先调用pop()移除当前跳转目标再通过replacePathByName跳转到登录页并携带redirect参数告知登录后返回原目标。登录后跳转登录页点击登录按钮后更新isLogged状态并根据redirect参数决定恢复跳转到收藏页或直接返回。注意事项拦截器需要在aboutToAppear中尽早注册确保所有跳转均能被拦截。避免在拦截逻辑中再次触发拦截防止死循环例如拦截到登录页时登录页自身不应再触发相同拦截。如果使用多个NavPathStack需为每个栈独立设置拦截器。五、注意事项与最佳实践5.1 前置条件必须在项目中创建router_map.json并注册所有跳转页面同时在module.json5中添加routerMap配置否则页面无法正常跳转。5.2 页面结构规范目标页面的根组件必须是NavDestination且需使用Builder导出一个构建函数函数名与router_map.json中配置的buildFunction完全一致。5.3 显示模式推荐使用Auto模式默认系统会根据组件宽度自动切换单栏/分栏便于多端适配。分栏模式在宽度 ≥ 600vp 时生效平板、折叠屏等场景。5.4 标题栏与菜单titleMode支持Mini滚动时折叠和Full始终显示完整标题栏。菜单栏使用数组方式时竖屏最多显示 3 个图标横屏最多显示 5 个超出需使用CustomBuilder自定义。5.6 页面生命周期NavDestination支持onPageShow、onPageHide、onBackPress等页面事件可在其中处理数据刷新或状态保存。5.7 返回处理推荐使用NavPathStack的pop()方法返回上一页也可通过popToName、popToIndex实现精准返回。如需在返回时传递数据可使用pushPath的回调函数。5.8 拦截器通过setInterception可实现在跳转前进行登录鉴权、数据保护等拦截逻辑提升应用安全性。六、总结本文从Navigation的核心概念出发通过一个完整的登录跳转个人中心示例详细讲解了路由映射表配置、页面创建、参数传递和页面返回等关键步骤。掌握这些内容后你就能在鸿蒙应用中灵活运用Navigation构建复杂的多页面交互了。