前言

在鸿蒙应用开发中，页面路由与导航是构建多页面应用的核心能力。无论是商城应用的购物车跳转，还是工具类应用的多功能模块切换，开发者都需要依赖灵活且高效的页面栈管理机制来完成。
鸿蒙的 NavPathStack 提供了完整的页面栈管理能力，结合 Navigation 组件，可以轻松实现页面跳转、返回、替换、删除、参数传递以及路由拦截等功能。相比传统的直接引用页面文件方式，鸿蒙推荐使用 系统路由表，这不仅降低了页面间的耦合度，也使得应用的可维护性更强。

本文将从基础概念入手，结合实际代码案例，对鸿蒙模块内页面路由的实现进行全面讲解，帮助开发者掌握从入门到进阶的完整思路。

1 页面路由的基本概念

1.1 什么是页面路由

页面路由本质上是在应用中进行页面跳转的规则与实现方式。在鸿蒙中，路由操作依赖 NavPathStack 来管理页面栈，它类似于一个栈结构，记录页面的进入和退出轨迹。

1.2 Navigation与NavPathStack的关系

• Navigation：负责承载和展示页面内容，相当于一个容器。
• NavPathStack：作为页面栈的管理器，负责记录当前页面栈信息和提供跳转方法。

二者的关系可以理解为：
Navigation 是“舞台”，NavPathStack 是“导演”，而页面则是“演员”。

1.3 页面路由的功能

鸿蒙的页面路由提供了以下核心功能：

• 页面跳转（push）
• 页面返回（pop）
• 页面替换（replace）
• 页面删除（remove）
• 参数传递
• 路由拦截

这些功能构成了应用内完整的路由闭环，开发者几乎可以覆盖所有场景。

2 Navigation与页面栈的创建

2.1 基础代码示例

以下示例展示了如何在应用入口 Index.ets 中创建页面栈并传入 Navigation：

@Entry
@Component
struct Index {
  // 创建一个页面栈对象
  pathStack: NavPathStack = new NavPathStack()

  build() {
    // 把页面栈对象传入 Navigation
    Navigation(this.pathStack) {
    }
    .title('Main')
  }
}

在该代码中，pathStack 就是页面栈对象，它负责后续所有路由行为的管理。

2.2 为什么需要单独创建NavPathStack

如果 Navigation 没有绑定一个独立的 NavPathStack，就无法完成页面跳转等操作。因此，为每个 Navigation 创建并传入一个独立的 NavPathStack 是使用路由的前提。

3 页面跳转的实现方式

3.1 两种路由方式对比

路由方式	特点	适用场景
自定义路由表	页面之间通过直接引用组件文件进行跳转，耦合度较高	小型项目、快速开发
系统路由表	通过配置文件进行页面注册，不需要直接引用组件文件，耦合度低、维护性好	中大型项目、多人协作

鸿蒙官方推荐使用 系统路由表，因为它能减少页面之间的强依赖，利于维护。

3.2 系统路由表的跳转流程

以下以跳转到 ShoppingCar.ets 页面为例，展示完整的系统路由表实现步骤。

3.2.1 在目标页面创建NavDestination

@Component
struct ShoppingCar {
  pathStack: NavPathStack = new NavPathStack()

  build() {
    NavDestination() {
      Text('购物车')
    }
    .title('购物车')
    .onReady((context: NavDestinationContext) => {
      this.pathStack = context.pathStack
    })
  }
}

说明：

• NavDestination 表示导航目标页面。
• onReady 事件中可以获取到目标页面的 pathStack。

3.2.2 创建Builder函数

在 ShoppingCar.ets 中新增一个入口 Builder 函数，用于在路由时构建页面：

@Builder
export function ShoppingCarBuilder() {
  ShoppingCar()
}

3.2.3 配置route_map.json

在 resources/base/profile/route_map.json 中添加路由配置：

{
  "routerMap": [
    {
      "name": "ShoppingCar",
      "pageSourceFile": "src/main/ets/pages/ShoppingCar.ets",
      "buildFunction": "ShoppingCarBuilder",
      "data": {
        "description": "this is ShoppingCar"
      }
    }
  ]
}

这里的 "name" 字段是路由跳转时使用的标识。

3.2.4 在module.json5中声明路由表

"routerMap": "$profile:route_map"

3.2.5 调用跳转方法

在入口页面中，通过以下方式跳转到 ShoppingCar：

this.pathStack.pushPathByName("ShoppingCar", null, false)

4 NavPathStack的常用方法详解

4.1 页面跳转

this.pathStack.pushPathByName("ShoppingCar", null, false)

参数说明：

• "ShoppingCar"：目标页面名称，对应 route_map.json 中的 name。
• null：跳转时可传递参数对象。
• false：是否为替换模式。

4.2 页面返回

this.pathStack.pop()

将当前页面弹出，返回到上一个页面。

4.3 页面替换

this.pathStack.replacePathByName("ShoppingCar", null)

直接替换当前页面，而不是入栈。

4.4 页面删除

this.pathStack.remove(index)

可以删除指定下标的页面，常用于清理不必要的页面堆栈。

4.5 参数获取

在目标页面中可以通过 NavDestinationContext 获取参数：

.onReady((context: NavDestinationContext) => {
  let params = context.pathStack.getParams()
})

4.6 路由拦截

开发者可以在跳转之前添加逻辑，例如登录校验。

if (isLogin) {
  this.pathStack.pushPathByName("ShoppingCar", null, false)
} else {
  prompt.showToast({ message: "请先登录" })
}

5 系统路由表的优势与实践经验

5.1 优势总结

• 解耦：页面之间无需相互引用，避免了循环依赖问题。
• 可维护：通过配置文件集中管理路由，更直观。
• 灵活扩展：适合多人协作开发，只需在路由表中新增配置即可。

5.2 实践建议

• 在中大型项目中务必使用 系统路由表。
• 路由命名要规范，避免重名。
• 在路由参数传递中尽量使用对象，而不是简单字符串，保证扩展性。

6 综合案例：购物车跳转与登录拦截

以下是一个完整案例：当用户点击“去购物车”按钮时，如果已登录则进入购物车，否则提示登录。

Button("去购物车")
  .onClick(() => {
    if (AppStorage.get("isLogin") === true) {
      this.pathStack.pushPathByName("ShoppingCar", null, false)
    } else {
      prompt.showToast({ message: "请先登录" })
    }
  })

这个案例展示了 页面跳转 + 路由拦截 + 参数存储 的组合应用，贴合真实业务需求。

7 常见问题与解决方案

• Q1：跳转时报错找不到页面？
  检查 route_map.json 是否配置正确，name 与 pushPathByName 的参数是否一致。
• Q2：页面返回无效？
  确认是否使用了 replacePathByName 替换了页面，替换后栈中可能不存在上一个页面。
• Q3：参数传递丢失？
  确认传参时是否为对象格式，并在目标页面中通过 context.pathStack.getParams() 获取。

结语

模块内页面路由是鸿蒙应用开发中不可或缺的一环。通过 NavPathStack 与 Navigation 的配合，开发者能够实现页面的灵活跳转与栈管理。而系统路由表的引入，则进一步降低了页面间的耦合度，使项目结构更加清晰，适合中大型项目的团队协作。

在实际开发中，建议开发者逐步养成以下习惯：

• 使用系统路由表集中管理路由；
• 结合路由拦截机制保障业务逻辑安全；
• 合理设计页面栈结构，避免不必要的冗余页面。