——从“能跑”到“可维护、可扩展”的工程化实践
在 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.pushUrlURL 写死，改路径成本极高
解决方案：统一路由层
common/ └── router/ ├── RouteMap.ts └── AppRouter.tsRouteMap.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.etsHomeViewModel.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
或正在做一个中大型鸿蒙项目
那么尽早建立清晰的多页面架构，会极大降低后期维护成本。
