摘要
在 Qt 中,QApplication 管理事件循环,QMainWindow 有 showEvent/hideEvent/closeEvent 等生命周期回调。鸿蒙的 Stage 模型对应这套体系:UIAbility 是应用的窗口承载单元,拥有完整生命周期回调;AbilityStage 是模块级入口。本节对标 Qt 的生命周期机制,讲清 Stage 模型的核心架构。
11.1 Stage 模型全景
应用 (App)
├── AbilityStage ← 模块入口(类似 QApplication 的初始化)
│ ├── UIAbility ← 窗口承载单元(类似 QMainWindow)
│ │ ├── pages/ ← 页面组件
│ │ └── WindowStage ← 窗口舞台(管理显示内容)
│ └── UIAbility ← 可有多个(多窗口/多入口)
└── HAP/HSP ← 打包单元(类似 .exe / .dll)
Qt 类比:
AbilityStage≈QApplication(应用级初始化)UIAbility≈QMainWindow(窗口生命周期)WindowStage≈QWindow/QGraphicsScene(显示内容的容器)
11.2 UIAbility 生命周期 —— 对标 QMainWindow
UIAbility 有 7 个生命周期回调,对标 Qt 的窗口事件:
Create → WindowStageCreate → Foreground → Background → WindowStageDestroy → Destroy
↑___________|
(可来回切换)
11.3 代码实现
import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
export default class EntryAbility extends UIAbility {
// 1. 创建 —— 类似 QMainWindow 构造
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
console.log('Ability onCreate');
// 全局初始化:读取配置、初始化 AppStorage
AppStorage.setOrCreate('userName', want.parameters?.userName ?? 'Guest');
}
// 2. 窗口创建 —— 类似 showEvent + setCentralWidget
onWindowStageCreate(windowStage: window.WindowStage): void {
console.log('onWindowStageCreate');
// 加载首页 —— 类似 setCentralWidget(new MainPage)
windowStage.loadContent('pages/Index', (err) => {
if (err.code) {
console.error(`Failed to load content. ${JSON.stringify(err)}`);
}
});
}
// 3. 进入前台 —— 类似 focusInEvent
onForeground(): void {
console.log('onForeground');
// 恢复定时器、刷新数据、重连 WebSocket
}
// 4. 进入后台 —— 类似 focusOutEvent / hideEvent
onBackground(): void {
console.log('onBackground');
// 暂停定时器、保存草稿、断开 WebSocket
}
// 5. 窗口销毁 —— 类似 closeEvent
onWindowStageDestroy(): void {
console.log('onWindowStageDestroy');
// 释放 UI 相关资源
}
// 6. Ability 销毁 —— 类似析构
onDestroy(): void {
console.log('onDestroy');
// 释放全部资源
}
// 7. 配置变化 —— 类似 resizeEvent
onConfigurationUpdate(newConfig: ConfigurationConstant.Configuration): void {
console.log('onConfigurationUpdate');
// 屏幕旋转、语言切换、深色模式切换
}
}
Qt 类比:Qt 中你重写
showEvent、hideEvent、closeEvent等虚函数;ArkUI 中你重写onForeground、onBackground等方法。机制完全一致——框架在特定时机回调你。
11.4 前后台切换的实战处理
这是最常用的生命周期场景。用户把 App 切到后台再切回来,你需要暂停和恢复:
export default class MusicPlayerAbility extends UIAbility {
private timer: number = -1;
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
// 初始化全局状态
AppStorage.setOrCreate('isPlaying', false);
}
onWindowStageCreate(windowStage: window.WindowStage): void {
windowStage.loadContent('pages/MusicPlayer', (err) => {
if (err.code) console.error(JSON.stringify(err));
});
}
onForeground(): void {
// 用户切回 App —— 恢复播放、刷新列表
console.log('回到前台,恢复播放');
const isPlaying = AppStorage.get('isPlaying');
if (isPlaying) {
this.resumePlayback();
}
// 刷新在线数据
this.refreshData();
}
onBackground(): void {
// 用户切到后台 —— 暂停播放、保存进度
console.log('进入后台,保存进度');
this.saveProgress();
// 注意:音乐可以继续在后台播放(需要后台任务能力,后续课程讲)
}
private resumePlayback(): void { /* ... */ }
private saveProgress(): void { /* ... */ }
private refreshData(): void { /* ... */ }
}
对比 Qt:
cpp复制
void MainWindow::focusInEvent(QFocusEvent *e) { if (m_wasPlaying) m_player->play(); refreshData(); } void MainWindow::focusOutEvent(QFocusEvent *e) { saveProgress(); }逻辑一样,只是回调名字不同。
11.5 页面组件的生命周期
除了 UIAbility 的生命周期,ArkUI 页面组件(@Entry 标注的 struct)也有自己的生命周期:
@Entry
@Component
struct HomePage {
// 组件即将出现(进入可见区域前)
aboutToAppear(): void {
console.log('aboutToAppear');
// 发起网络请求、订阅事件
this.loadData();
}
// 组件已出现(UI 渲染完成)
onPageShow(): void {
console.log('onPageShow');
// 页面完全显示,可做动画
}
// 组件即将消失(离开页面时)
onPageHide(): void {
console.log('onPageHide');
// 取消订阅、暂停动画
}
// 组件销毁
aboutToDisappear(): void {
console.log('aboutToDisappear');
// 释放定时器、清理引用
}
@State data: string[] = [];
loadData(): void {
setTimeout(() => {
this.data = ['Item 1', 'Item 2', 'Item 3'];
}, 1000);
}
build() {
Column() {
ForEach(this.data, (item: string) => {
Text(item).padding(16)
})
}
}
}
生命周期对照:
注意区分:
onPageShow/onPageHide是页面级的(路由切换时触发);aboutToAppear/aboutToDisappear是组件级的(组件创建/销毁时触发)。@Entry页面两者都有,普通@Component子组件只有aboutToAppear/aboutToDisappear。
11.6 生命周期全景图
应用启动
│
├─ AbilityStage.onAddConfiguration ← 模块加载
│
├─ UIAbility.onCreate ← Ability 创建
│ │
│ ├─ UIAbility.onWindowStageCreate ← 窗口创建
│ │ │
│ │ ├─ Page.aboutToAppear ← 页面组件初始化
│ │ ├─ Page.onPageShow ← 页面显示
│ │ │ │
│ │ │ ├─ <用户交互> ← 正常使用
│ │ │ │
│ │ │ ├─ Page.onPageHide ← 路由跳走 / 切后台
│ │ │ └─ Page.onPageShow ← 路由回来 / 切前台
│ │ │
│ ├─ UIAbility.onForeground ← 进入前台
│ ├─ UIAbility.onBackground ← 进入后台
│ │ (可多次来回)
│ │
│ ├─ UIAbility.onWindowStageDestroy ← 窗口销毁
│ │ ├─ Page.onPageHide
│ │ └─ Page.aboutToDisappear ← 页面组件销毁
│ │
└─ UIAbility.onDestroy ← Ability 销毁
11.7 实战:数据加载与资源清理
@Entry
@Component
struct ArticlePage {
@State articles: Article[] = [];
@State loading: boolean = false;
private refreshTimer: number = -1;
// 组件创建时加载初始数据
aboutToAppear(): void {
console.log('aboutToAppear: 加载文章');
this.loadArticles();
}
// 页面显示时刷新数据 + 启动定时刷新
onPageShow(): void {
console.log('onPageShow: 刷新数据');
this.loadArticles();
// 每 30 秒刷新一次
this.refreshTimer = setInterval(() => {
this.loadArticles();
}, 30000);
}
// 页面隐藏时停止定时器
onPageHide(): void {
console.log('onPageHide: 停止定时器');
if (this.refreshTimer !== -1) {
clearInterval(this.refreshTimer);
this.refreshTimer = -1;
}
}
// 组件销毁时做最终清理
aboutToDisappear(): void {
console.log('aboutToDisappear: 清理资源');
if (this.refreshTimer !== -1) {
clearInterval(this.refreshTimer);
}
}
async loadArticles(): Promise<void> {
this.loading = true;
setTimeout(() => {
this.articles = [
{ id: 1, title: 'ArkTS 入门' },
{ id: 2, title: 'ArkUI 实战' },
];
this.loading = false;
}, 1000);
}
build() {
Column() {
if (this.loading) {
LoadingProgress().width(40).height(40)
} else {
List() {
ForEach(this.articles, (article: Article) => {
ListItem() {
Text(article.title).padding(16)
}
})
}
}
}
}
}
interface Article {
id: number;
title: string;
}
Qt 类比:
aboutToAppear≈ 构造函数中loadData()onPageShow≈showEvent中m_timer->start(30000)onPageHide≈hideEvent中m_timer->stop()aboutToDisappear≈ 析构中delete m_timer逻辑完全对应,只是 API 名字不同。
11.8 AbilityStage —— 模块入口
AbilityStage 是 HAP 模块加载时的入口,比 UIAbility 更早执行:
import { AbilityStage } from '@kit.AbilityKit';
export default class MyAbilityStage extends AbilityStage {
onCreate(): void {
// 应用启动时最先执行 —— 类似 main() 中的 QApplication 初始化
console.log('AbilityStage onCreate');
this.initGlobalConfig();
}
onAcceptWant(want: Want): string {
// 处理启动请求,返回 UIAbility 实例标识
// 用于多实例场景(类似 Qt 中创建多个 MainWindow)
return 'EntryAbility';
}
private initGlobalConfig(): void {
AppStorage.setOrCreate('apiBase', 'https://api.example.com');
AppStorage.setOrCreate('appVersion', '1.0.0');
}
}
Qt 类比:
AbilityStage.onCreate()≈int main() { QApplication app; initGlobalConfig(); ... }。在第一个窗口创建之前做全局初始化。
11.9 速查:ArkUI 生命周期 vs Qt 生命周期
本节思考题
Q1:用户正在浏览文章列表页,突然来电话把 App 切到后台。通话结束后切回 App。这个过程中,onPageHide/onPageShow 和 onBackground/onForeground 的触发顺序是什么?
答案:触发顺序为:
- 来电切后台:
onBackground→onPageHide(页面不可见) - 通话结束切回:
onForeground→onPageShow(页面重新可见)
注意:
onBackground/onForeground是 UIAbility 级的(整个应用进后台/前台),onPageHide/onPageShow是页面级的。Ability 切后台时页面也会隐藏,所以两者都会触发。
Q2:你在 onPageShow 中启动了一个 30 秒的定时器刷新数据,在 onPageHide 中停止它。但如果用户直接按返回键退出页面(触发 aboutToDisappear),定时器会被停掉吗?
答案:不会自动停掉!aboutToDisappear 不会自动调用 onPageHide。如果 aboutToDisappear 中没有 clearInterval,定时器会泄漏。正确做法是在 aboutToDisappear 中也做清理:
aboutToDisappear(): void {
if (this.refreshTimer !== -1) {
clearInterval(this.refreshTimer);
this.refreshTimer = -1;
}
}
这和 Qt 一样——析构函数里必须释放资源,不能依赖
closeEvent先被调用。
Q3:你需要实现一个聊天应用:进入页面时连接 WebSocket,离开页面时断开,切后台时保持连接但停止消息提醒,切前台时恢复提醒。应该在哪些回调中处理?
答案:
// 页面级管理连接生命周期
@Entry
@Component
struct ChatPage {
aboutToAppear(): void {
this.connectWebSocket(); // 组件创建时连接
}
onPageShow(): void {
this.enableNotification(); // 页面可见时开启消息提醒
}
onPageHide(): void {
this.disableNotification(); // 页面不可见时关闭提醒
}
aboutToDisappear(): void {
this.disconnectWebSocket(); // 组件销毁时断开连接
}
}
// Ability 级处理前后台差异
export default class ChatAbility extends UIAbility {
onBackground(): void {
// 切后台:保持 WebSocket 连接(不断开)
// 改为通知栏推送消息
this.enablePushNotification();
}
onForeground(): void {
// 切前台:恢复应用内提醒,清除通知栏
this.disablePushNotification();
}
}
分层处理:页面级用 aboutToAppear/aboutToDisappear 管理连接生命周期,Ability 级用 onBackground/onForeground 管理前后台差异行为。





































苏公安网备 32011402010933号