摘要：页面跳转是应用交互的核心。在 HarmonyOS NEXT 及 ArkTS 开发中，传统的 router 模块正逐渐被声明式的 Navigation 组件取代。本文基于 API 11 环境，深入解析 Navigation 组件、NavPathStack 状态管理、参数传递、路由拦截及自定义动画，帮助开发者构建结构清晰、体验流畅的多页面应用。

1. 前言

在开发新闻资讯类应用时，页面跳转看似简单，实则暗藏玄机。作为鸿蒙领域的资深工程师，我见过太多开发者因为路由管理不当导致的问题：

1. 栈管理混乱：页面返回逻辑错误，出现“死循环”或无法返回。
2. 参数传递丢失：复杂对象在页面间传递时序列化失败。
3. 转场动画生硬：缺乏自定义动画，用户体验割裂。
4. 性能损耗：频繁创建销毁页面导致内存抖动。

华为在 ArkUI 中推出了全新的 Navigation 组件，旨在提供声明式、状态驱动的路由体验。本文将结合新闻详情页跳转场景，手把手教你掌握鸿蒙路由的核心玩法。

2. 核心概念解析

在开始编码前，必须理解鸿蒙路由的两大体系：

特性	router 模块 (传统)	Navigation 组件 (推荐)
编程范式	命令式 ( imperative )	声明式 ( Declarative )
状态管理	内部维护，难以监听	基于 NavPathStack，可观察
适用场景	简单跳转，兼容旧版本	复杂应用，鸿蒙 NEXT 首选
自定义能力	较弱	强 (支持拦截、自定义动画)

本文重点讲解 Navigation 组件方案，这是鸿蒙生态未来的标准。

3. 环境准备与结构规划

延续上一篇新闻アプリ 的场景，我们需要实现从 新闻列表页 (Index) 跳转到 新闻详情页 (Detail)。

3.1 页面注册

在鸿蒙中，使用 Navigation 组件时，页面不需要在 main_pages.json 中全部注册（除非是独立 Ability 页面），NavDestination 可以直接在组件内定义。但为了规范，我们依然建议在 main_pages.json 中配置入口页。

{
  "src": [
    "pages/Index"
  ]
}

3.2 定义路由路径常量

为了避免硬编码字符串导致维护困难，建议统一管理路由路径。

文件路径: entry/src/main/ets/common/constant/RoutePath.ts

export enum RoutePath {
  INDEX = 'pages/Index',
  DETAIL = 'pages/Detail'
}

4. 核心实现：构建导航容器

Navigation 组件是路由的容器，它需要绑定一个 NavPathStack 对象来管理页面栈。

文件路径: entry/src/main/ets/pages/Index.ets (修改版)

import { router } from '@kit.ArkUI';
import { NavPathStack, Navigation, NavDestination } from '@kit.ArkUI';
import { RoutePath } from '../common/constant/RoutePath';
import { NewsItem } from '../model/NewsModel';
import { NewsViewModel } from '../viewmodel/NewsViewModel';

@Entry
@Component
struct Index {
  // 1. 创建路径栈实例
  private pathStack: NavPathStack = new NavPathStack();
  private viewModel: NewsViewModel = new NewsViewModel();

  build() {
    // 2. 使用 Navigation 包裹内容
    Navigation(this.pathStack) {
      // 3. 定义首页目的地
      NavDestination() {
        Column() {
          Text('实时热点新闻')
            .fontSize(24)
            .fontWeight(FontWeight.Bold)
            .padding(16)
          
          // 列表内容 (简化版，参考上一篇文章)
          List({ space: 10 }) {
            LazyForEach(this.viewModel.newsList, (item: NewsItem) => {
              ListItem() {
                // 点击卡片触发跳转
                NewsCard(itemData: item)
                  .onClick(() => {
                    this.navigateToDetail(item);
                  })
              }
            }, (item: NewsItem) => item.id)
          }
          .layoutWeight(1)
          .width('100%')
        }
        .width('100%')
        .height('100%')
      }
      .title('首页') // 顶部标题
    }
    .width('100%')
    .height('100%')
  }

  // 跳转逻辑
  navigateToDetail(item: NewsItem) {
    // 4. 压栈操作，携带参数
    // 参数必须是可序列化对象 (string, number, boolean, object 等)
    this.pathStack.pushPath({
      name: RoutePath.DETAIL,
      args: { newsData: item } 
    });
  }
}

5. 目标页面接收参数

在详情页，我们需要从 NavDestination 的参数中获取新闻数据。

文件路径: entry/src/main/ets/pages/Detail.ets

import { NavDestination } from '@kit.ArkUI';
import { NewsItem } from '../model/NewsModel';

@Entry
@Component
struct Detail {
  // 接收参数，需使用 @State 或普通变量初始化
  @State newsData: NewsItem = { id: '', title: '', summary: '', imageUrl: '', source: '', timestamp: 0 };

  // 页面加载时获取参数
  aboutToAppear() {
    // 获取路由参数
    // 注意：在 Navigation 模式下，参数通常通过构造传参或全局状态管理获取
    // 此处演示通过自定义方法接收 (实际开发中建议配合状态管理模块)
    const params = router.getParams() as { newsData: NewsItem }; 
    // 注：若纯使用 Navigation 组件，建议通过路径栈 args 直接绑定或在 NavDestination 中监听
    if (params && params.newsData) {
      this.newsData = params.newsData;
    }
  }

  build() {
    NavDestination() {
      Column() {
        // 顶部导航栏通常由 Navigation 组件自动处理，这里做内容区
        Scroll() {
          Column() {
            Image(this.newsData.imageUrl)
              .width('100%')
              .height(200)
              .objectFit(ImageFit.Cover)
            
            Text(this.newsData.title)
              .fontSize(22)
              .fontWeight(FontWeight.Bold)
              .margin({ top: 16, left: 16, right: 16 })
            
            Text(this.newsData.source)
              .fontColor('#999999')
              .margin({ left: 16, top: 8 })
            
            Text(this.newsData.summary)
              .fontSize(16)
              .lineHeight(24)
              .margin({ top: 16, left: 16, right: 16 })
              .width('100%')
          }
          .width('100%')
        }
        .layoutWeight(1)
      }
      .width('100%')
      .height('100%')
    }
    .title(this.newsData.title) // 动态设置标题
  }
}

注意：在纯 Navigation 组件模式下，参数传递更推荐通过 NavPathStack 的 args 直接在 NavDestination 的构建函数中接收，或者使用应用级状态管理（如 AppStorage）共享数据，以避免序列化开销。

优化后的参数接收方式 (推荐)： 在 Index.ets 中 pushPath 时传递 args，在 Detail 组件定义时通过 @BuilderParam 或监听栈变化获取。但为了兼容性，上述 router.getParams() 在混合模式下仍有效。若纯 Navigation 模式，建议如下：

// 在 Index 中
this.pathStack.pushPath({ name: RoutePath.DETAIL, args: { id: item.id } });

// 在 Detail 中 (伪代码示意)
// 实际开发中，建议创建一个单例 DataManager 存储当前新闻详情，通过 ID 查询

6. 进阶功能：路由拦截与自定义动画

6.1 路由拦截 (Guard)

在某些场景下（如用户未登录、文章已删除），我们需要阻止跳转。Navigation 组件支持 onIntercept。

Navigation(this.pathStack) {
  // ... 内容
}
.onIntercept((target: NavPathStack.Target) => {
  // target.name 是目标页面路径
  if (target.name === RoutePath.DETAIL) {
    // 模拟检查登录状态
    const isLogin = false; 
    if (!isLogin) {
      // 拦截跳转，转而跳转到登录页
      this.pathStack.pushPath({ name: 'pages/Login' });
      return true; // 返回 true 表示拦截成功，原跳转取消
    }
  }
  return false; // 放行
})

6.2 自定义转场动画

默认的推拉动画可能不符合设计需求。我们可以自定义 pageTransition。

Navigation(this.pathStack) {
  // ...
}
.pageTransition({
  enter: (from: Resource, to: Resource) => {
    // 定义进入动画
    // 例如：淡入 + 上滑
    animation.duration(300).ease(Ease.Out);
  },
  exit: (from: Resource, to: Resource) => {
    // 定义退出动画
  }
})

注：具体动画 API 需参考最新 ArkUI 动画文档，此处为逻辑示意。

---

7. 性能优化与最佳实践

7.1 避免栈溢出

无限跳转会导致 NavPathStack 过大，消耗内存。

    策略：使用 replacePath 代替 pushPath。例如从“登录页”跳回“首页”，不应保留登录页在栈中。

// 错误：登录后返回会回到登录页
this.pathStack.pushPath({ name: RoutePath.INDEX });

// 正确：替换当前页，返回时直接退出应用或回到更上层
this.pathStack.replacePath({ name: RoutePath.INDEX });

7.2 大数据对象传递优化

在 args 中传递巨大的 JSON 对象会导致序列化开销。

策略：只传递 ID，在目标页面通过 ID 请求数据或从全局缓存（AppStorage）中读取。

// 推荐
this.pathStack.pushPath({ name: RoutePath.DETAIL, args: { id: '12345' } });

// 不推荐 (当对象极大时)
this.pathStack.pushPath({ name: RoutePath.DETAIL, args: { fullData: hugeObject } });

7.3 状态保持

当用户从详情页返回列表页时，列表页的状态（如滚动位置、筛选条件）默认会保留。但如果列表页被销毁重建，状态会丢失。

• 策略：利用 @Observed 和全局状态管理保存列表状态，或在 Navigation 配置中开启状态保持（视具体 API 版本支持情况）。

---

8. 常见问题排查 (FAQ)

1. Q: NavPathStack 变化了，但 UI 没更新？
   • A: NavPathStack 内部已做状态管理，但如果你自定义了基于栈长度的 UI（如自定义返回按钮），确保该 UI 属性被 @State 或 @Observed 装饰，或者直接使用 Navigation 提供的默认标题栏。
2. Q: 返回键失效怎么办？
   • A: 检查是否拦截了系统的 backPress 事件。Navigation 组件默认处理物理返回键，若自定义了 onBackPress，需手动调用 pathStack.pop()。
3. Q: 如何在跳转前执行异步操作（如保存草稿）？
   • A: 使用 onIntercept 拦截，在拦截回调中执行异步操作，完成后手动调用 pushPath。注意拦截回调目前主要支持同步逻辑，异步需配合状态标志位。

---

9. 总结

鸿蒙的页面路由机制正在从命令式向声明式演进。掌握 Navigation 组件和 NavPathStack 是开发高质量鸿蒙应用的关键。

• 简单跳转：pushPath / pop。
• 复杂逻辑：利用 onIntercept 做权限控制。
• 性能关键：避免大对象传参，合理使用 replacePath。

希望本文能帮助你理清鸿蒙路由的脉络，构建出逻辑严密、体验丝滑的应用架构。