HarmonyOS Navigation实现导航与路由切换原创精华

waylau

发布于 2025-9-15 10:38

浏览

0收藏

本文主要介绍在HarmonyOS下如何使用Navigation和NavDestination来实现导航与路由切换。

Navigation和NavDestination概述

Navigation组件是路由导航的根视图容器，一般作为Page页面的根容器使用，其内部默认包含了标题栏、内容区和工具栏，其中内容区默认首页显示导航内容（Navigation的子组件）或非首页显示（NavDestination的子组件），首页和非首页通过路由进行切换。

从API Version 10开始，推荐使用NavPathStack配合navDestination属性进行页面路由。

创建应用

创建一个名为“ArkTSNavigation”的ArkTS应用作为演示。完整源码见文末。

首页

修改src/main/ets/pages/Index.ets，内容如下：

@Entry
@Component
struct Index {
 @State message: string = '主页';

 // 创建一个导航控制器对象并传入Navigation
 pageInfos: NavPathStack = new NavPathStack();

 build() {
   Navigation(this.pageInfos) {
     Column() {
       Text(this.message)
         .fontSize($r('app.float.page_text_font_size'))
         .fontWeight(FontWeight.Bold)
         .alignRules({
           center: { anchor: '__container__', align: VerticalAlign.Center },
           middle: { anchor: '__container__', align: HorizontalAlign.Center }
         })

       Button('导航到第一页')
         .width(128).height(28)
         .onClick(() => {
           // 跳转页面时不携带参数
           this.pageInfos.pushPathByName('pageOne', null);
         })

       Button('导航到第二页')
         .width(128).height(28)
         .onClick(() => {
           // 跳转页面时携带参数
           this.pageInfos.pushPathByName('pageTwo', "Page Two");
         })
     }
     .height('100%')
     .width('100%')
   }
   .mode(NavigationMode.Auto)
 }
}

上述页面

通过NavPathStack来初始化Navigation。NavPathStack是Navigation路由栈，允许被继承。开发者可以在派生类中新增属性方法，也可以重写基类NavPathStack的方法。派生类对象可以替代基类NavPathStack对象使用。
设置了两个按钮，点击按钮会跳转到不同的页面。通过pushPathByName等路由接口进行页面跳转。其中一个按钮会跳转到一个新页面，不并携带参数；另一个按钮会跳转到一个新页面，并携带参数内容为“Page Two”。

第一个子页面

新建src/main/ets/pages/PageOne.ets：

@Builder
export function PageOneBuilder(name: string, param: Object) {
 PageOne()
}

@Component
export struct PageOne {
 @State message: string = '第一页';
 pageInfos: NavPathStack = new NavPathStack();

 build() {
   NavDestination() {
     RelativeContainer() {
       Text(this.message)
         .fontSize($r('app.float.page_text_font_size'))
         .fontWeight(FontWeight.Bold)
         .alignRules({
           center: { anchor: '__container__', align: VerticalAlign.Center },
           middle: { anchor: '__container__', align: HorizontalAlign.Center }
         })
     }
     .height('100%')
     .width('100%')
   }
   .title('PageOne')
   .onReady((context: NavDestinationContext) => {
     this.pageInfos = context.pathStack;
   })
 }
}

通过@Builder定义的函数PageOneBuilder来构建PageOne。函数名称需要和route_map.json配置文件中的buildFunction保持一致，否则在编译时会报错。

NavDestination作为子页面的根容器，用于显示Navigation的内容区。

当切换到该界面时，会显示页面内容“第一页”。

第二个子页面

新建src/main/ets/pages/PageTwo.ets：

@Builder
export function PageTwoBuilder(name: string, param: Object) {
 PageTwo()
}

@Component
export struct PageTwo {
 @State message: string = '第二页';
 pageInfos: NavPathStack = new NavPathStack();

 build() {
   NavDestination() {
     RelativeContainer() {
       Text(this.message)
         .fontSize($r('app.float.page_text_font_size'))
         .fontWeight(FontWeight.Bold)
         .alignRules({
           center: { anchor: '__container__', align: VerticalAlign.Center },
           middle: { anchor: '__container__', align: HorizontalAlign.Center }
         })
     }
     .height('100%')
     .width('100%')
   }
   .title('PageTwo')
   .onReady((context: NavDestinationContext) => {
     this.pageInfos = context.pathStack
     this.message = context.pathInfo.param as string;
   })
 }
}

大体与PageOne类似，确保在于，会通过NavDestinationContext来接收从首页路由过来传递的参数。

当切换到该界面时，会显示从首页传递的参数“Page Two”。

设置路由

Navigation支持使用系统路由表的方式进行动态路由。各业务模块（HSP/HAR）中需要独立配置route_map.json文件，在触发路由跳转时，应用只需要通过NavPathStack提供的路由方法，传入需要路由的页面配置名称，此时系统会自动完成路由模块的动态加载、页面组件构建，并完成路由跳转，从而实现了开发层面的模块解耦。系统路由表不支持预览器，跨平台及模拟器。其主要步骤如下。

修改src/main/module.json5添加路由表配置：

{
 "module" : {

   //...为节约篇幅，此处省略非核心内容

   "routerMap": "$profile:route_map"
 }
}

添加完路由配置文件地址后，需要在工程resources/base/profile中创建route_map.json文件。添加如下配置信息：

{
 "routerMap": [
   {
     "name": "pageOne",
     "pageSourceFile": "src/main/ets/pages/PageOne.ets",
     "buildFunction": "PageOneBuilder",
     "data": {
       "description": "this is pageOne"
     }
   },
   {
     "name": "pageTwo",
     "pageSourceFile": "src/main/ets/pages/PageTwo.ets",
     "buildFunction": "PageTwoBuilder",
     "data": {
       "description": "this is pageTwo"
     }
   }
 ]
}

上述配置

name 跳转页面名称。
pageSourceFile 跳转目标页在包内的路径，相对src目录的相对路径。
buildFunction 跳转目标页的入口函数名称，必须以@Builder修饰。
data 应用自定义字段。可以通过配置项读取接口getConfigInRouteMap获取。

在跳转目标页面中，需要配置入口Builder函数，函数名称需要和route_map.json配置文件中的buildFunction保持一致，否则在编译时会报错。

运行调测

界面效果如下图所示。

HarmonyOS Navigation实现导航与路由切换-鸿蒙开发者社区

参考引用

本文同步至：https://waylau.com/2025-07-21-harmonyos-arkts-geo-location-manager
源码见《跟老卫学HarmonyOS开发》开源免费教程，https://github.com/waylau/harmonyos-tutorial
《跟老卫学AI大模型开发》开源免费教程，https://github.com/waylau/ai-large-model-tutorial/
《跟老卫学仓颉编程语言开发》开源免费教程，https://github.com/waylau/cangjie-programming-language-tutorial
《鸿蒙HarmonyOS手机应用开发实战》（清华大学出版社）
《鸿蒙HarmonyOS应用开发入门》（清华大学出版社）
“鸿蒙零基础快速实战-仿抖音App开发（ArkTS版）”（https://coding.imooc.com/class/843.html）
《鸿蒙HarmonyOS应用开发从入门到精通（第2版）》（北京大学出版社)
《鸿蒙之光HarmonyOS NEXT原生应用开发入门》（清华大学出版社)
“HarmonyOS NEXT+AI大模型打造智能助手APP(仓颉版)”（https://coding.imooc.com/class/927.html）