鸿蒙应用开发：深入解析Navigation路由跳转与实战代码

来自卡卡

628人浏览 · 2025-09-03 14:34:45

来自卡卡 · 2025-09-03 14:34:45 发布

Navigation是鸿蒙HarmonyOS ArkUI框架中用于实现应用内导航的核心组件，它提供了比传统Router更强大的页面栈管理和复杂路由逻辑支持。以下将详细介绍其核心概念、实现步骤及代码示例。

一、Navigation核心优势

Navigation组件作为路由导航的根视图容器，具备以下特性：

强大的页面栈管理：可精细控制页面栈的压入、弹出操作
多级路由嵌套：支持复杂应用结构的路由配置
动态路由配置：可根据运行时条件动态调整路由
模块化解耦：通过系统路由表实现跨HAR/HSP模块的无依赖跳转

二、基础实现步骤

2.1路由容器组件

根容器使用Navigation

// 首页
@Entry
@Component
struct Index {
  build() {
    // Navigation 是路由容器组件，一般作为首页的根容器
    Navigation() {
      Tabs(){
        // ...
      }
    }
    .hideTitleBar(true)// 隐藏标题栏
  }
}

首页页面跳转

@Entry
@Component
struct Index {
  // 1. 创建一个路由栈对象，并绑定到 Navigation 组件中
 @Provide pageStack: NavPathStack = new NavPathStack()

  build() {
    // 2. 绑定路由栈到 Navigation 组件
    Navigation(this.pageStack) {
      Button('跳转页面')
        .onClick(() => {
          // 3. 通过路由栈跳转页面
          this.pageStack.pushPath({ name: 'xxx', param: 'xxx Param' })
          // this.pageStack.pushPathByName('xxx', 'xxx Param')
        })
    }
    .hideTitleBar(true)// 隐藏导航栏
  }
}

子组件跳转

@Component
struct MySonComp {
  // 1. 接收路由栈对象
 @Consume pageStack: NavPathStack 

  build() {
    Column() {
      Button('跳转页面')
        .onClick(() => {
          // 2. 通过路由栈跳转页面
          this.pageStack.pushPath({ name: 'xxx', param: 'xxx Param' })
          // this.pageStack.pushPathByName('xxx', 'xxx Param')
        })
    }
  }
}

2.2 动态路由跳转

新建 Builder 入口函数和 NavDestination 组件

// 1子页的入口函数，必须以 @Builder 修饰
@Builder
function DemoBuilder() {
   // 2 子页结构，必须以 NavDestination 组件包裹
    NavDestination() {
      Demo()
    }
   .hideTitleBar(true)// 隐藏导航栏
}
@Component
struct Demo {
  //  接收路由栈对象
 @Consume pageStack: NavPathStack 
  
  build() {
    Column() {
        Text('Demo页面')
         .fontSize(30)
         .onClick(()=>{
           // 返回上一页
           this.pageStack.pop()
         })
     }
  }
}

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

{
  "routerMap": [
    {
      "name": "SearchView",  // 跳转页面名称
      "pageSourceFile": "src/main/ets/views/SearchView.ets", // 跳转目标页的路径
      "buildFunction": "SearchViewBuilder", // 跳转目标页的入口函数名称
    }
  ]
}

在跳转目标模块的配置文件 module.json5 添加路由表配置：

{
  "module": {
    "name": "home",
    "type": "shared",
    "description": "$string:shared_desc",
    "deviceTypes": [
      "phone",
      "tablet",
      "2in1"
    ],
    "deliveryWithInstall": true,
    "pages": "$profile:main_pages",
    "routerMap": "$profile:route_map"
  }
}

2.3. 路由传参和获取

NavPathStack 通过 Push 相关的接口去实现页面跳转的功能

// 通过页面的 name 去跳转，并可以携带 param
this.pageStack.pushPath({ name: "页面名称", param: 参数})
this.pageStack.pushPathByName("页面名称", 参数))  // 不传参可以 在参数位置写null

NavPathStack 路由栈通过 Get 相关接口去获取页面的一些参数

// 1子页的入口函数，必须以 @Builder 修饰
@Builder
function DemoBuilder() {
   // 2 子页结构，必须以 NavDestination 组件包裹
    NavDestination() {
       Demo()
    }
   .hideTitleBar(true)// 隐藏导航栏
}
@Entry
@Component
struct Demo {
  //  接收路由栈对象
 @Consume pageStack: NavPathStack 
  
  aboutToAppear(){
    // 获取页面的参数，注意返回的是数组类型
    const params = this.pageStack.getParamByName('页面名称') as 类型[]
  }
  build() {
    Column() {
        Text('Demo页面')
         .fontSize(30)
         .onClick(()=>{
           // 返回上一页
           this.pageStack.pop()
         })
     }
  }
}