HarmonyOS 多页面架构设计模式总结

------从"能跑"到"可维护、可扩展"的工程化实践

在 HarmonyOS 项目中，页面数量一旦超过 5 个，如果没有清晰的多页面架构设计，很快就会出现以下问题：

• 路由混乱，页面之间互相跳转像"意大利面"

• 页面状态靠参数硬传，改一个页面牵一片

• 生命周期逻辑分散，难以统一管理

• 后期加新功能，不敢动老代码

本文将结合 Stage 模型 + ArkUI ，系统性总结 HarmonyOS 多页面架构的设计模式与最佳实践，帮你把项目从"Demo 级"升级到"工程级"。

---

一、HarmonyOS 的多页面基础认知

在 Stage 模型下，HarmonyOS 的页面体系核心是：

Application
 └── Ability (UIAbility)
     └── Window
         └── Page（ArkUI 页面）

页面切换的本质

• HarmonyOS 不是 Activity 栈

• 页面通过 Router 管理

• UIAbility 通常只有 1 个（推荐）

结论 ：
多页面 ≠ 多 Ability，而是多 Page

---

二、最基础的架构：单 Ability + Router 页面栈

推荐起手式

entry/
 ├── pages/
 │    ├── Home.ets
 │    ├── Detail.ets
 │    ├── Login.ets
 │    └── Profile.ets
 └── EntryAbility.ets

路由跳转示例

import router from '@ohos.router';

router.pushUrl({
  url: 'pages/Detail',
  params: {
    id: 1001
  }
});

页面接收参数

@Entry
@Component
struct Detail {
  aboutToAppear() {
    const params = router.getParams() as { id: number };
    console.info('id:', params.id);
  }
}

✔ 简单

参数泛滥、页面强耦合

---

三、进阶一：路由分层设计（Router 封装模式）

问题

• 页面中到处 router.pushUrl

• URL 写死，改路径成本极高

解决方案：统一路由层

common/
 └── router/
      ├── RouteMap.ts
      └── AppRouter.ts

RouteMap.ts

export enum RoutePath {
  HOME = 'pages/Home',
  DETAIL = 'pages/Detail',
  LOGIN = 'pages/Login'
}

AppRouter.ts

import router from '@ohos.router';
import { RoutePath } from './RouteMap';

export class AppRouter {
  static toDetail(id: number) {
    router.pushUrl({
      url: RoutePath.DETAIL,
      params: { id }
    });
  }

  static toLogin() {
    router.replaceUrl({ url: RoutePath.LOGIN });
  }
}

页面中使用

AppRouter.toDetail(1001);

好处

• 页面不关心路由细节

• 路径集中管理

• 方便后期埋点 / 权限校验

---

四、进阶二：页面职责拆分（Page ≠ Logic）

错误示范（典型新手写法）

@Component
struct Home {
  async loadData() {
    // 网络
    // 缓存
    // 数据处理
  }
}

推荐模式：Page + ViewModel

pages/
 ├── Home/
 │    ├── HomePage.ets
 │    └── HomeViewModel.ets

HomeViewModel.ts

@ObservedV2
export class HomeVM {
  @Local list: string[] = []

  async load() {
    this.list = ['A', 'B', 'C']
  }
}

HomePage.ets

@ComponentV2
struct HomePage {
  private vm = new HomeVM()

  aboutToAppear() {
    this.vm.load()
  }

  build() {
    List() {
      ForEach(this.vm.list, item => {
        Text(item)
      })
    }
  }
}

本质

• 页面只负责展示

• 逻辑可测试、可复用

---

五、进阶三：全局状态 + 页面解耦

典型场景

• 登录状态

• 用户信息

• 权限信息

全局状态容器

@ObservedV2
export class AppStore {
  @Local isLogin = false
  @Local userName = ''
}

export const appStore = new AppStore()

页面中使用

@ComponentV2
struct Profile {
  build() {
    if (appStore.isLogin) {
      Text(`欢迎：${appStore.userName}`)
    } else {
      Button('去登录').onClick(() => {
        AppRouter.toLogin()
      })
    }
  }
}

页面不再直接互相依赖，而是通过状态协作

---

六、进阶四：多页面生命周期协同设计

常用生命周期

生命周期	场景
aboutToAppear	页面进入
onPageShow	可见
onPageHide	被覆盖
aboutToDisappear	离开

推荐实践

• 数据加载：aboutToAppear

• 埋点 / 动画：onPageShow

• 暂停任务：onPageHide

  aboutToAppear() {
  this.vm.load()
  }

  onPageHide() {
  this.vm.pauseTimer()
  }

---

七、进阶五：模块化多页面架构（大项目必备）

目录示例

features/
 ├── login/
 ├── home/
 ├── order/
 └── profile/

每个 feature 自己管理：

• 页面

• ViewModel

• 路由注册

效果

• 模块可插拔

• 多人协作冲突少

• 接近 Android 的 Feature 模块化

---

八、HarmonyOS 多页面架构最佳实践总结

一句话总结

页面只负责 UI，路由统一管理，状态集中托管，逻辑模块化拆分

推荐组合

• Stage 模型 + 单 UIAbility

• Router 封装

• ViewModel（@ObservedV2）

• 全局 Store

• Feature 模块化

---

九、结语

HarmonyOS 的多页面架构并不复杂 ，难点不在 API，而在工程设计意识。

如果你：

• 正在从 Android 转 HarmonyOS

• 或正在做一个中大型鸿蒙项目

那么尽早建立清晰的多页面架构，会极大降低后期维护成本。