鸿蒙 ArkUI 路由新贵：Navigation 与 NavPathStack 极简入门指南

在鸿蒙应用开发中，页面跳转已经全面拥抱了单页面（SPA）组件级架构的设计思想。官方主推的 Navigation 组件搭配 NavPathStack 路由栈，成为了管理页面导航的标准方案。

刚接触这两个对象时可能会觉得有些绕，但其实只要掌握了核心的“三步走”套路，就能轻松搞定路由流转。下面通过一个极简的 Demo，带你快速跑通完整的页面跳转流程。

核心代码演示

这是一段包含主页面容器、路由控制器以及子页面跳转的最简代码结构：

@Entry
@Component
struct NavPathStackPage {
  // 1、创建路由栈对象（核心控制器）
  pathStack: NavPathStack = new NavPathStack()

  // 3、定义子页面的UI结构（必须使用 @Builder 装饰器）
  @Builder
  getPage(name: string) {
    // 子页内容必须包裹在 NavDestination 组件之内
    NavDestination() {
      Text(name + "测试内容")
        .fontSize(20)
        .margin({ top: 20 })
    }
    .title("测试标题") // 自带标题栏配置
  }

  build() {
    // 2、将路由栈对象传入 Navigation 组件作关联
    Navigation(this.pathStack) {
      Column() {
        Button("进入子页")
          .onClick(() => {
            // 触发跳转：向栈中推入一个新的页面
            this.pathStack.pushPath({ name: "detail" })
          })
      }
      .width('100%')
      .height('100%')
      .justifyContent(FlexAlign.Center)
    }
    // 4、注册子页面的构建函数（路由拦截/分发中心）
    .navDestination(this.getPage)
  }
}

核心流程拆解

实现 Navigation 路由跳转，核心就是理清控制器（Stack）、主容器（Navigation）和子页面（Destination）的关系。

1. 实例化路由控制器 (NavPathStack)

pathStack: NavPathStack = new NavPathStack()

它是整个路由系统的“方向盘”。后续所有的页面跳转（pushPath）、返回上一页（pop）、清空路由栈（clear）以及跨页面传参，都是直接调用这个对象上的方法来实现的。

2. 绑定导航主容器 (Navigation)

Navigation(this.pathStack) { ... }

Navigation 是整个页面的导航根视图。将刚才创建的 pathStack 作为参数传入，相当于完成了绑定。从此，这个容器内的页面进出记录，完全由该栈对象统一接管。

3. 构建子页面视图 (NavDestination)

@Builder getPage(name: string) { NavDestination() { ... } }

在现代鸿蒙架构中，子页面不再是独立分散的物理页面，而是主页面里的组件替换。

@Builder：用于封装复用 UI 结构的自定义构建函数。

NavDestination：极其关键的底层容器。所有准备被路由跳转过去的子页面代码，最外层都必须包裹 NavDestination。它天生自带标准页面的标题栏（.title()）和左上角的物理返回键逻辑。

4. 注册路由分发通道 (.navDestination)

.navDestination(this.getPage)

这是衔接跳转指令和UI渲染的桥梁。当你在代码中执行 this.pathStack.pushPath({ name: "detail" }) 时，系统其实是拿着 "detail" 这个名字去找 .navDestination() 绑定的函数。函数接收到名字后，负责把对应的 NavDestination 组件渲染出来，完成画面的切换。

在实际的中大型鸿蒙项目中，开发者通常会将 @Builder 里的内容配合 switch-case 语句，根据传入的不同 name 渲染不同的独立自定义组件，从而实现一个丝滑且高性能的单页面路由系统。