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

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

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

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