前言

在鸿蒙应用的开发历程中，页面跳转一直是大家最先接触的功能之一。很长一段时间里，Router 模块都是我们手中的标配武器，那句 router.pushUrl 相信每一位开发者都烂熟于心。但在构建大型应用，尤其是面对平板、折叠屏这些复杂设备时，老旧的 Router 逐渐显露出了疲态。它是一个页面级别的全局单例，难以处理分屏、弹窗嵌套路由以及模块化的动态加载。这就像是用一把瑞士军刀去砍伐整片森林，虽然能用，但效率极低且手感生涩。

在 HarmonyOS 6 的时代，官方明确推荐我们全面拥抱 Navigation 组件。这不仅仅是一个组件的更替，更是一次架构思维的升级。Navigation 不再是一个简单的 API 调用，它是一个容器，一个能够容纳完整路由栈、标题栏和工具栏的超级容器。它将路由的管理权从系统底层交还到了开发者手中，让我们能够像操作数组一样精准地控制页面的进出栈。

今天，我们就把那个陈旧的 Router 放在一边，深入探讨如何利用 Navigation V2 架构和 NavPathStack 构建一个现代化、健壮的应用导航体系。

一、 从 Router 到 Navigation：架构的范式转移

要理解 Navigation 的强大，我们先得明白它解决了什么痛点。传统的 Router 是基于 Page（页面）的，每一个页面都是一个独立的 Ability 或者窗口层级。当我们想要在一个弹窗里再做一套局部导航，或者在平板的左侧菜单里嵌入一个独立的路由栈时，Router 就束手无策了。

Navigation 组件的出现彻底改变了这一局面。它本质上是一个 UI 组件，这意味着它可以被放置在界面的任何位置。你可以把它放在根节点作为全屏导航，也可以把它放在一个 Dialog 内部，甚至可以嵌套使用。

在 API 20 中，Navigation 采用了 组件级路由 的概念。每一个“页面”不再是 @Entry 修饰的独立文件，而是被 NavDestination 包裹的自定义组件。这种设计让页面变得极其轻量，页面的切换本质上就是组件的挂载与卸载，性能得到了巨大的提升。更重要的是，它配合 NavPathStack 实现了路由栈的可编程化，我们终于可以像操作数据一样去操作界面了。

二、 核心大脑：NavPathStack 路由栈管理

如果说 Navigation 是躯壳，那么 NavPathStack 就是它的灵魂。在 V2 版本中，我们不再直接调用组件的方法来跳转，而是创建一个 NavPathStack 的实例，并将其绑定到 Navigation 组件的 pathStack 属性上。这个栈对象就是我们操控界面的遥控器。

你需要实现一个复杂的登录流程：用户点击购买 -> 跳转登录 -> 跳转注册 -> 注册成功 -> 直接返回购买页（跳过登录页）。在旧的 Router 模式下，你需要计算 delta 索引或者使用 replace 模式小心翼翼地堆叠。而在 NavPathStack 中，就方便多了。你可以随时调用 popToName 直接回到指定的路由锚点，或者操作栈数组，精准地移除中间的某几个页面。

数据的传递也变得优雅。当我们调用 pushPath 时，可以直接传入一个 param 对象。而在目标页面中，我们不需要再写繁琐的 router.getParams()，而是直接在 NavDestination 的 onShown 生命周期或者组件初始化时，从栈中获取参数。这种参数传递是类型安全的，且完全受控。此外，NavPathStack 还提供了强大的拦截器机制（Interception），让我们可以在路由跳转发生前进行鉴权拦截，比如用户未登录时直接重定向到登录页，这一切都在路由层面被优雅地拦截处理了。

三、 页面构造：NavDestination 与路由表设计

在 Navigation 架构下，我们的一级页面（根页面）通常直接写在 Navigation 的闭包里，而二级、三级页面则通过 NavDestination 来定义。这里有一个关键的概念转变：我们需要构建一个 路由映射表。

我们不再是通过文件路径去跳转，而是通过 路由名称（Name）。我们需要在 Navigation 组件中配置 navDestination 属性，它接收一个 @Builder 构建函数。当 NavPathStack 请求跳转到 "DetailPage" 时，这个构建函数就会被触发，我们需要在这个函数里根据传入的 name 返回对应的 NavDestination 包裹的组件。

这种设计模式天然支持模块化开发。我们可以把不同模块的路由表分散在各自的 HAR 包中，最后在主工程中进行聚合。每个 NavDestination 都是一个独立的沙箱，它拥有自己的标题栏、菜单栏和生命周期（onShown, onHidden）。这对于开发者来说非常友好，我们可以在 onWillAppear 中发起网络请求，在 onWillDisappear 中保存草稿，页面的生命周期完全掌握在自己手中。

四、 界面定制：摆脱默认样式的束缚

Navigation 自带了标准的标题栏（TitleBar）和工具栏（ToolBar），这在快速开发原型时非常方便。但在实际的商业项目中，设计师往往会给出天马行空的顶部导航设计，比如透明渐变背景、复杂的搜索框或者异形的返回按钮。

很多初学者会困惑：我是该用系统自带的，还是自己画？我的建议是按需定制。Navigation 和 NavDestination 都提供了 title、menus 和 toolBar 属性。如果设计风格符合系统规范，直接传入资源配置即可，系统会自动适配深色模式和折叠屏布局。但如果设计差异巨大，我们可以通过 .hideTitleBar(true) 彻底隐藏系统标题栏，然后在内容区域（Content）的顶部放置我们自定义的 NavBar 组件。

这里有一个细节需要注意，当我们隐藏了系统标题栏后，原本的滑动返回手势依然有效，但左上角的返回箭头没了。我们需要自己实现一个返回按钮，并调用 this.pageStack.pop() 来手动触发返回。这种灵活性让我们既能享受系统手势的便利，又能完全掌控视觉呈现。

import { promptAction } from '@kit.ArkUI';

// 1. 定义路由参数模型
interface ContactParams {
  id: string;
  name: string;
  phone: string;
}

@Entry
@Component
struct NavigationBestPracticePage {
  // 核心修正：使用 @Provide 而不是 @State
  // 这样后代组件 (DetailPage) 才能通过 @Consume 直接获取该对象
  @Provide('pageStack') pageStack: NavPathStack = new NavPathStack();

  // 模拟的首页数据
  @State contacts: ContactParams[] = [
    { id: '1', name: '张三', phone: '13800138000' },
    { id: '2', name: '李四', phone: '13900139000' },
    { id: '3', name: '王五', phone: '15000150000' }
  ];

  // -------------------------------------------------------
  // 路由工厂：根据路由名称动态构建页面
  // -------------------------------------------------------
  @Builder
  PagesMap(name: string, param: Object) {
    if (name === 'DetailPage') {
      // 跳转到详情页
      DetailPage({
        contactInfo: param as ContactParams
      })
    } else if (name === 'EditPage') {
      // 跳转到编辑页
      EditPage({
        contactInfo: param as ContactParams
      })
    }
  }

  build() {
    // 根容器：Navigation
    Navigation(this.pageStack) {
      // 首页内容区域
      Column() {
        Text('通讯录 (V2)')
          .fontSize(24)
          .fontWeight(FontWeight.Bold)
          .margin({ top: 20, bottom: 20 })
          .width('100%')
          .padding({ left: 16 })

        List() {
          ForEach(this.contacts, (item: ContactParams) => {
            ListItem() {
              Row() {
                // 这里使用系统图标模拟头像，实际请替换为 app.media.xxx
                Image($r('app.media.startIcon'))
                  .width(40)
                  .height(40)
                  .borderRadius(20)
                  .margin({ right: 12 })
                  .backgroundColor('#E0E0E0') // 兜底背景色

                Column() {
                  Text(item.name).fontSize(16).fontWeight(FontWeight.Medium)
                  Text(item.phone).fontSize(14).fontColor('#999')
                }
                .alignItems(HorizontalAlign.Start)
                .layoutWeight(1)

                // 跳转按钮
                Button('查看')
                  .fontSize(12)
                  .height(28)
                  .onClick(() => {
                    // 核心动作：压栈跳转
                    this.pageStack.pushPathByName('DetailPage', item, true);
                  })
              }
              .width('100%')
              .padding(12)
              .backgroundColor(Color.White)
              .borderRadius(12)
              .margin({ bottom: 8 })
            }
          })
        }
        .padding(16)
        .layoutWeight(1)
      }
      .width('100%')
      .height('100%')
      .backgroundColor('#F1F3F5')
    }
    // 绑定路由映射构建器
    .navDestination(this.PagesMap)
    // 首页的标题模式
    .titleMode(NavigationTitleMode.Mini)
    .hideTitleBar(true) // 首页隐藏系统标题栏，使用自定义内容
    .mode(NavigationMode.Stack) // 强制使用堆叠模式
  }
}

// -------------------------------------------------------
// 子页面 1：详情页 (使用 @Consume 获取 Stack)
// -------------------------------------------------------
@Component
struct DetailPage {
  // 接收参数
  contactInfo: ContactParams = { id: '', name: '', phone: '' };

  // 获取当前的路由栈 (对应父组件的 @Provide)
  @Consume('pageStack') pageStack: NavPathStack;

  build() {
    NavDestination() {
      Column({ space: 20 }) {
        Image($r('app.media.startIcon'))
          .width(80)
          .height(80)
          .borderRadius(40)
          .margin({ top: 40 })
          .backgroundColor('#E0E0E0')

        Text(this.contactInfo.name)
          .fontSize(24)
          .fontWeight(FontWeight.Bold)

        Text(this.contactInfo.phone)
          .fontSize(18)
          .fontColor('#666')

        Button('编辑资料')
          .width('80%')
          .margin({ top: 40 })
          .onClick(() => {
            // 继续压栈，跳转到编辑页
            this.pageStack.pushPathByName('EditPage', this.contactInfo);
          })
      }
      .width('100%')
      .height('100%')
    }
    .title('联系人详情') // 设置系统标题
  }
}

// -------------------------------------------------------
// 子页面 2：编辑页 (使用 onReady 获取 Stack)
// -------------------------------------------------------
@Component
struct EditPage {
  @State contactInfo: ContactParams = { id: '', name: '', phone: '' };
  @State newName: string = '';

  // 独立维护 Stack 引用，不依赖 @Consume，解耦性更好
  private stack: NavPathStack | null = null;

  aboutToAppear(): void {
    this.newName = this.contactInfo.name;
  }

  build() {
    NavDestination() {
      Column({ space: 16 }) {
        Text('修改姓名:')
          .fontSize(14)
          .fontColor('#666')
          .width('90%')
          .margin({ top: 20 })

        TextInput({ text: $$this.newName, placeholder: '请输入新名字' })
          .backgroundColor(Color.White)
          .width('90%')
          .height(50)
          .borderRadius(10)

        Button('保存并返回')
          .width('90%')
          .margin({ top: 20 })
          .onClick(() => {
            // 模拟保存操作
            if (this.stack) {
              this.stack.pop(true); // 出栈
              promptAction.showToast({ message: `保存成功: ${this.newName}` });
            }
          })
      }
      .width('100%')
      .height('100%')
      .backgroundColor('#F1F3F5')
    }
    .title('编辑')
    .onReady((context: NavDestinationContext) => {
      // 最佳实践：在 onReady 中获取当前页面的 stack
      // 这种方式不需要父组件必须使用 @Provide，适用性更广
      this.stack = context.pathStack;
    })
  }
}

五、 总结与实战

Navigation 组件配合 NavPathStack，标志着鸿蒙应用开发进入了 单窗口多组件（Single Window, Multi-Component） 的架构时代。它解决了 Router 时代的诸多顽疾，提供了更灵活的嵌套能力、更强大的路由栈控制以及更轻量的页面切换开销。

对于任何一个立志于构建专业级鸿蒙应用的开发者来说，尽早重构代码，迁移到 Navigation 架构，是提升应用质量的关键一步。

摘要

随着 HarmonyOS / OpenHarmony 在手机、平板、智慧屏、车机等多设备上的落地，应用的复杂度正在明显提升。页面不再只是简单展示，而是伴随着网络请求、数据计算、设备协同等大量逻辑。如果这些逻辑处理不当，很容易出现页面卡顿、点击无响应，甚至 Ability 被系统回收的问题。

线程阻塞，已经成为鸿蒙应用开发中最容易踩坑、也最影响体验的问题之一。本文将结合实际开发场景，用尽量口语化的方式，聊一聊在鸿蒙系统中如何系统性地避免线程阻塞，并给出可以直接运行的 Demo 代码。

引言

在早期的应用开发中，很多开发者习惯把逻辑直接写在点击事件里，或者在页面加载时同步读取数据。这种写法在简单页面中问题不大，但在 HarmonyOS 这种强调流畅体验和多设备协同的系统中，很容易暴露问题。

鸿蒙的 UI 是声明式的，系统对主线程（UI 线程）非常敏感。一旦主线程被占用，页面掉帧、动画卡住、操作延迟都会立刻出现。因此，理解哪些操作会阻塞线程，以及如何把这些操作合理地“挪走”，是每个鸿蒙开发者绕不开的一课。

下面我们从原理、工具、代码和真实场景几个角度，完整地拆解这个问题。

为什么线程阻塞在鸿蒙中这么致命

UI 线程到底在忙什么

在 HarmonyOS 中，UI 线程主要负责三件事：

• ArkUI 页面渲染
• 用户事件分发（点击、滑动等）
• Ability 生命周期回调

简单理解就是：只要和“看得见、点得动”有关的事情，几乎都在 UI 线程上完成。

一旦你在这里做了耗时操作，比如计算、IO、网络等待，页面就会立刻表现出“卡”的感觉。

常见的阻塞来源

在实际项目中，最容易导致阻塞的操作通常包括：

• 同步网络请求
• 文件读写
• 数据库查询
• 大量 for 循环计算
• 人为 sleep 或死循环

这些操作本身不一定是错的，问题在于它们被放在了不该放的线程上。

鸿蒙中避免线程阻塞的核心思路

一个总原则

可以把鸿蒙里的线程使用总结成一句话：

UI 线程只处理 UI，其他事情交给异步、线程池或 Worker。

围绕这个原则，系统也提供了多种工具，帮助开发者把任务“分流”。

异步编程是第一道防线

使用 async / await 处理耗时逻辑

在 ArkTS 中，官方推荐优先使用 Promise 和 async / await。它的好处是代码结构清晰，而且不会阻塞 UI 线程。

示例：页面加载网络数据

@Entry
@Component
struct AsyncDemo {
  @State message: string = '加载中...'

  build() {
    Column() {
      Text(this.message)
        .fontSize(20)
        .margin(20)

      Button('重新加载')
        .onClick(() => {
          this.loadData()
        })
    }
  }

  async loadData() {
    this.message = '请求中...'
    let response = await fetch('https://example.com/data')
    let result = await response.text()
    this.message = result
  }
}

代码说明

• loadData 使用 async 声明，不会阻塞 UI
• await 只是暂停当前函数执行，不会卡住页面
• UI 更新完全由状态变化驱动

这是最基础、也是最常用的一种防阻塞方式。

TaskPool：处理计算和 IO 的利器

什么时候该用 TaskPool

当你遇到下面这些情况时，TaskPool 几乎是必选项：

• 大量计算
• 批量数据处理
• 文件压缩、解析

可运行 Demo 示例

import taskpool from '@ohos.taskpool'

@Concurrent
function calculateSum(count: number): number {
  let sum = 0
  for (let i = 0; i < count; i++) {
    sum += i
  }
  return sum
}

@Entry
@Component
struct TaskPoolDemo {
  @State result: string = '等待计算'

  build() {
    Column() {
      Text(this.result)
        .fontSize(18)
        .margin(20)

      Button('开始计算')
        .onClick(() => {
          this.startTask()
        })
    }
  }

  startTask() {
    this.result = '计算中...'
    taskpool.execute(calculateSum, 1000000).then(res => {
      this.result = `结果是：${res}`
    })
  }
}

代码说明

• @Concurrent 表示该函数可以并发执行
• TaskPool 自动管理线程，不需要开发者手动创建线程
• UI 线程只负责接收结果和更新状态

在真实项目中，使用 TaskPool 往往能立刻解决页面卡顿问题。

Worker：长期后台任务的选择

Worker 的使用场景

如果任务具有下面这些特点，就更适合使用 Worker：

• 长时间运行
• 需要持续处理数据
• 与 UI 强隔离

比如日志分析、音视频处理、复杂解析等。

示例：使用 Worker 处理数据

主线程代码

let worker = new Worker('workers/data_worker.ts')

worker.postMessage({ action: 'start' })

worker.onmessage = (e) => {
  console.log('收到结果：', e.data)
}

Worker 线程代码

onmessage = function (e) {
  if (e.data.action === 'start') {
    let result = 0
    for (let i = 0; i < 500000; i++) {
      result += i
    }
    postMessage(result)
  }
}

代码说明

• Worker 与 UI 线程完全独立
• 即使计算时间较长，也不会影响页面交互
• 通过消息机制进行通信

结合实际场景的应用示例

场景一：列表页面加载大量数据

问题：

• 首次进入页面时一次性处理全部数据
• 页面明显卡顿

解决思路：

• 网络请求使用 async
• 数据整理放入 TaskPool

async loadList() {
  let data = await fetchData()
  taskpool.execute(processData, data).then(list => {
    this.list = list
  })
}

场景二：文件导入与解析

问题：

• 文件较大
• 解析过程耗时

解决思路：

• Worker 负责解析
• UI 只显示进度

worker.postMessage({ filePath })

场景三：复杂计算驱动 UI 更新

问题：

• 计算逻辑和 UI 耦合

解决思路：

• 计算完全放到 TaskPool
• UI 只订阅结果

QA 环节

Q：async / await 会不会阻塞线程？
A：不会，它只是让出执行权，不会卡住 UI 线程。

Q：TaskPool 和 Worker 怎么选？
A：短期、一次性的任务优先 TaskPool，长期或持续任务用 Worker。

Q：能不能在生命周期里做耗时操作？
A：不建议，生命周期函数应尽量轻量。

总结

线程阻塞并不是某一个 API 的问题，而是设计问题。在 HarmonyOS 中，系统已经为我们准备好了异步模型、TaskPool 和 Worker，只要遵循“UI 线程只做 UI”的原则，大多数卡顿问题都可以提前避免。

在真实项目中，提前做好任务拆分、线程规划，比后期排查卡顿要省心得多。这也是鸿蒙开发从“能跑”到“跑得顺”的一个重要分水岭。