一、为什么多页面架构是 HarmonyOS 应用的“分水岭”

在 HarmonyOS 开发初期，很多开发者会先从单页面应用入手：

一个页面、少量状态、简单交互，这类场景下 ArkUI 的优势非常明显。

但当应用逐渐具备以下特征时，问题就会显现：

• 页面数量增多（列表页、详情页、编辑页、设置页等）
• 页面之间存在频繁跳转
• 页面需要共享部分业务状态
• 登录态、用户信息、配置状态需要全局管理

此时，如果仍然以“单页面思维”开发，代码会迅速走向混乱。
多页面架构设计能力，往往决定了一个 HarmonyOS 项目能否长期维护。

二、HarmonyOS 页面模型与路由机制概览

1. 页面在 HarmonyOS 中的基本形态

在 ArkUI（Stage 模型）下，页面本质上是：

• 一个 @Entry 修饰的组件
• 由 router 进行统一调度
• 运行在 Ability 的页面栈中

与传统 Android Activity 不同，HarmonyOS 的页面更偏向“轻量 UI 容器”，页面逻辑应该尽量简单。

2. router 模块的基本使用方式

在 ArkTS 中，页面跳转依赖 @ohos.router 模块。

import router from '@ohos.router'

最常用的页面跳转方式是 pushUrl：

router.pushUrl({
  url: 'pages/DetailPage',
  params: {
    title: 'HarmonyOS'
  }
})

这一设计非常直观，也符合前端开发者的使用习惯。

三、页面参数传递的正确使用方式

1. 页面参数的典型应用场景

参数传递通常用于：

• 列表页 → 详情页
• 首页 → 功能页
• 搜索页 → 结果页

原则：参数只传“必要信息”，不传“大对象”。

2. 接收参数的方式

@Entry
@Component
struct DetailPage {
  @State title: string = ''

  aboutToAppear() {
    const params = router.getParams()
    this.title = params?.title as string
  }

  build() {
    Text(this.title)
      .fontSize(26)
  }
}

这里使用 aboutToAppear，而不是直接在 build() 中获取参数，是一个非常重要的工程习惯。

3. 参数传递的局限性

需要注意的是：

• 参数仅适合轻量数据
• 页面刷新或重建时需重新获取
• 不适合复杂业务状态共享

当页面之间需要共享复杂状态时，应考虑其他方案。

四、页面返回与页面栈管理策略

1. 普通返回操作

router.back()

适用于：

• 普通页面返回
• 不需要清理状态的场景

2. replaceUrl 的使用场景

router.replaceUrl({
  url: 'pages/MainPage'
})

适用于：

• 登录成功后返回首页
• 页面不希望被返回访问

合理使用 replaceUrl 可以避免页面栈过深。

3. 页面栈设计的工程建议

• 页面层级尽量控制在 3–5 层以内
• 核心页面避免重复入栈
• 登录、引导页应主动清理栈

五、实战案例：列表 → 详情 → 编辑的完整流程

1. 列表页设计

@Entry
@Component
struct ListPage {
  @State dataList: Array<string> = [
    'ArkUI',
    'HarmonyOS',
    'OpenHarmony'
  ]

  build() {
    List() {
      ForEach(this.dataList, (item) => {
        ListItem() {
          Text(item)
            .fontSize(20)
        }
        .onClick(() => {
          router.pushUrl({
            url: 'pages/DetailPage',
            params: { name: item }
          })
        })
      })
    }
  }
}

2. 详情页展示与操作入口

@Entry
@Component
struct DetailPage {
  @State name: string = ''

  aboutToAppear() {
    this.name = router.getParams()?.name as string
  }

  build() {
    Column() {
      Text(this.name)
        .fontSize(28)

      Button('编辑')
        .onClick(() => {
          router.pushUrl({
            url: 'pages/EditPage',
            params: { name: this.name }
          })
        })
    }
  }
}

3. 编辑页与返回逻辑

@Entry
@Component
struct EditPage {
  @State name: string = ''

  aboutToAppear() {
    this.name = router.getParams()?.name as string
  }

  build() {
    Column() {
      TextInput({ text: this.name })
        .onChange((value) => {
          this.name = value
        })

      Button('保存并返回')
        .onClick(() => {
          router.back()
        })
    }
  }
}

六、状态共享：什么时候不该用页面参数

当应用中出现以下情况时，页面参数已经不够用：

• 多个页面依赖同一份用户数据
• 状态需要跨多个页面生命周期存在
• 页面刷新后仍需保留状态

此时可以考虑：

• 应用级状态管理
• Ability 级共享状态
• 数据持久化方案

七、工程化页面架构设计建议

1. 页面职责划分原则

• 页面：负责路由与结构
• 组件：负责 UI 与局部交互
• 状态：尽量集中管理

2. 页面目录结构建议

pages/
 ├── home/
 ├── list/
 ├── detail/
 ├── edit/

清晰的目录结构可以显著降低维护成本。

3. 常见错误总结

• 页面承担过多业务逻辑
• 页面间强耦合
• 滥用参数传递
• 页面栈失控

八、HarmonyOS 多页面开发的实践总结

HarmonyOS 的多页面架构设计并不复杂，但是否规范使用，差距会在项目后期被无限放大。

一个清晰的页面路由策略、合理的参数传递方式、可控的页面栈管理，是构建稳定 HarmonyOS 应用的基础。

九、结语

在 HarmonyOS 开发中，多页面并不是简单的“跳转”，而是一套完整的架构设计问题。只有在早期就建立正确的页面模型和路由思维，才能避免后期的维护困境。

对于希望长期深耕 HarmonyOS 生态的开发者而言，多页面架构能力是一项必须掌握的核心技能。