鸿蒙原生 ArkTS 布局实践：Navigation 容器入门与页面栈管理

---

一、引言

在移动端开发中，页面导航是最核心的用户交互模式。用户从首页进入详情、从详情返回、从列表跳转到设置——这些操作的背后，是一个精密的页面栈（Page Stack）在默默工作。

HarmonyOS NEXT 自 API 12 起，将 Navigation 确立为官方首选的页面导航容器，替代了早期零散的路由方案。它提供了统一的页面栈管理、声明式路由注册、原生转场动画支持，是构建多页面应用的基石。

本文将从一个完整示例出发，深入剖析 Navigation 容器与页面栈管理机制。

---

二、页面栈：后进先出的数据结构

栈（Stack） 的核心规则是 后进先出（LIFO）——最后放入的，最先取出。

移动端页面导航天然遵循这一规律：用户从「首页」进入「详情页」（入栈），再从「详情页」进入「设置页」（入栈），点击返回则回到「详情页」（出栈），再返回到「首页」（出栈）。

页面栈机制自动解决三个核心问题：

1. 导航历史追踪——随时知道用户从哪来、经过了哪些页面
2. 返回路径管理——用户点击返回时自动回到上一页
3. 资源生命周期——页面弹出时自动释放资源，避免内存泄漏

---

三、Navigation 与传统路由的对比

维度	Navigation + NavPathStack	router API
页面管理	组件级页面栈	Ability 级页面跳转
页面间通信	参数传递 + onPop 回调	参数对象传递
性能开销	低（组件级）	较高（Ability 级）
子页面注册	无需注册 main_pages.json	需注册到 main_pages.json
转场动画	内置，自动跟随	需手动配置

核心结论：应用内部的页面导航，Navigation 是更优选择——更轻量、更灵活、更符合组件化思维。

---

四、实战示例：项目结构

示例应用由 4 个文件组成：

entry/src/main/ets/pages/
├── Index.ets        # 主入口：Navigation 容器 + 页面栈实例
├── PageOne.ets      # 子页面1：个人资料（参数传递 + pop）
├── PageTwo.ets      # 子页面2：系统设置（连续入栈演示）
└── PageThree.ets    # 子页面3：关于页面（clear 清空栈演示）

4.1 Index.ets —— 页面栈的中枢

1) 创建 NavPathStack 实例：

@State
pathStack: NavPathStack = new NavPathStack();

NavPathStack 是页面栈的"遥控器"——入栈、出栈、清空都通过它完成。@State 装饰器让栈状态变化自动触发 UI 刷新。

2) 注册页面路由构造器：

@Builder
pageBuilder(name: string, param: Object) {
  if (name === 'PageOne') {
    PageOne({ pathStack: this.pathStack, param: param as Record<string, Object> });
  } else if (name === 'PageTwo') {
    PageTwo({ pathStack: this.pathStack });
  } else if (name === 'PageThree') {
    PageThree({ pathStack: this.pathStack });
  }
}

这是一个路由分发器。Navigation 收到 pushPath 请求后，将路由名称和参数传递给此 @Builder，由它决定实例化哪个组件。子页面共享同一个 pathStack 引用，使它们也能操作页面栈。

3) Navigation 容器包裹首页：

Navigation(this.pathStack) {
  // 首页 UI 内容
}
.title('Navigation 页面栈示例')
.hideTitleBar(false)
.titleMode(NavigationTitleMode.Full)
.navDestination(this.pageBuilder)

4.2 关键细节：无需 import

Navigation、NavPathStack、NavDestination 在 API 24 中属于系统内置全局组件，与 Column、Row、Text 一样无需显式导入。若编辑器报红，请确认 SDK 版本是否支持 API 24 以上。

4.3 子页面：NavDestination 正确用法

每个子页面最外层必须是 NavDestination——这是 Navigation 识别和管理子页面的关键契约：

@Component
export struct PageOne {
  pathStack: NavPathStack = new NavPathStack();   // 不能加 private
  param: Record<string, Object> = {};              // 不能加 private

  build() {
    NavDestination() {
      // 页面内容
    }
    .title('个人资料')
  }
}

注意 pathStack 和 param 不能使用 private——这是 ArkTS 编译器对组件构造器传参的安全要求。

---

五、页面栈的三种核心操作

5.1 pushPath() —— 入栈

this.pathStack.pushPath({
  name: 'PageOne',
  param: { name: '张三', avatar: '👤', email: 'zhangsan@example.com' }
});

name 必须与 pageBuilder 中的分支名称一致，param 为任意可序列化数据。设计哲学：数据跟着路由走，参数不再是全局状态，而是路径信息的一部分。

5.2 pop() —— 出栈

this.pathStack.pop();

弹出栈顶页面，返回上一页。语义清晰：“我不要当前页面了，回到我来的地方”。这是 LIFO 特性的最直接体现。

5.3 clear() —— 清空栈

this.pathStack.clear();

清空整个页面栈，直接回到根页面。与连续 pop 的区别：

• pop 到首页：每个页面依次经历生命周期回调，逐层释放
• clear 到首页：所有页面一次性销毁，直接回到根页面

5.4 参数传递的完整链路

首页（pushPath 传入 param）
  → pageBuilder（转发 pathStack 和 param）
    → PageOne（接收并使用 param）

// 接收端
Text((this.param['name'] as string) || '未知用户')
  .fontSize(24)
  .fontWeight(FontWeight.Bold)

5.5 获取页面栈状态

方法	返回类型	说明
size()	number	栈中页面数量（首页不计入）
getAllPathName()	string[]	所有页面名称数组，末项为栈顶
getIndexByName(name)	number[]	指定名称页面的所有索引位置

示例中首页的"栈状态信息卡"实时展示这些信息：

Text(this.pathStack.size() > 0 ?
  this.pathStack.getAllPathName()[this.pathStack.size() - 1] :
  '首页 (根页面)')

---

六、注意事项与易错点

6.1 NavPathStack 没有 get() 方法

// ❌ 错误（无此方法）
this.pathStack.get(0).name

// ✅ 正确
this.pathStack.getAllPathName()[0]

6.2 getIndexByName 返回数组

let indices: number[] = this.pathStack.getIndexByName('PageOne');
if (indices.length > 0) {
  // 取第一个索引
  console.log(`PageOne 在第 ${indices[0] + 1} 层`);
}

6.3 @Builder 中不能使用循环语句

在 @Builder 方法体内只能包含 UI 组件声明和条件语句，不能有 for 循环或 let 变量声明。解决方案：将数据源生成逻辑放在 struct 的普通方法中，在 @Builder 中使用 ForEach 组件：

// 在 struct 中定义
getIndices(size: number): number[] {
  let result: number[] = [];
  for (let i = 0; i < size; i++) {
    result.push(i);
  }
  return result;
}

// 在 @Builder 中使用 ForEach
@Builder
depthIndicator() {
  ForEach(this.getIndices(this.pathStack.size()), (index: number) => {
    Circle().fill(index === this.pathStack.size() - 1 ? '#FF8F1F' : '#D0D0D0')
  }, (item: number) => item.toString());
}

6.4 子页面不需注册到 main_pages.json

Entry 页面（有 @Entry）才需注册到 main_pages.json。Navigation 子页面（无 @Entry，有 NavDestination）由 navDestination() 的 @Builder 统一管理，本质上是 Navigation 容器内部的组件。

---

七、进阶技巧

7.1 页面生命周期回调

NavDestination 提供的生命周期回调：

回调	触发时机	典型用途
onReady	页面即将展示	初始化数据
onShow	页面变为可见	刷新数据
onHide	页面被覆盖	保存草稿
onDisappear	页面被销毁	释放资源
onBackPressed	系统返回键	拦截确认

7.2 数据回传

子页面 pop 时携带结果返回给父页面：

// 子页面
this.pathStack.pop({ success: true, data: '完成' });

// 父页面（push 时注册回调）
this.pathStack.pushPathByName('PageOne', param, (popInfo: PopInfo) => {
  console.log('回传数据:', JSON.stringify(popInfo));
});

7.3 嵌套 Navigation

通过 getParent() 获取父级栈引用，实现嵌套 Navigation 协同：

let parentStack = this.pathStack.getParent();
if (parentStack) {
  parentStack.popToIndex(0);
}

7.4 控制转场动画

通过 pushPath 的第二个参数控制动画开关：

// 禁用转场动画
this.pathStack.pushPath({ name: 'PageTwo' }, false);

---

八、总结

本文从一个完整实战示例出发，剖析了 HarmonyOS NEXT 中 Navigation 容器和页面栈管理机制。核心要点：

1. 页面栈基于 LIFO 数据结构，天然适配移动端导航场景
2. Navigation 三要素：Navigation 容器、NavPathStack 操作器、NavDestination 页面容器
3. 三种核心操作：pushPath 入栈、pop 出栈、clear 清空栈
4. 声明式路由：通过 navDestination() 注册路由构造器，实现"注册调用分离"
5. 避坑指南：注意 get() 方法不存在、getIndexByName 返回数组、@Builder 不能写循环、构造器属性不能为 private

掌握 Navigation，意味着能够构建结构清晰、用户体验流畅的多页面应用。它是 HarmonyOS NEXT 应用架构的基石，值得深入学习。