arkTs：UIAbility 生命周期（补充版）

1.UIAbility 是什么？

在鸿蒙中，UIAbility（继承自 @kit.AbilityKit 的 UIAbility 类）
代表了应用的一个“能力模块”，它管理应用的界面窗口与生命周期回调。

它的生命周期可以分为两部分：

• Ability 生命周期（整体级别）

	onCreate()		// 创建onForeground()	// 前台onBackground()	// 后台onDestroy()		// 销毁

• WindowStage 生命周期（UI窗口级别）

	onWindowStageCreate()		// 窗口创建onWindowStageWillDestroy()	// 窗口即将销毁onWindowStageDestroy()		// 窗口销毁

在鸿蒙中，UIAbility 就像是一个「页面管理者」。
它负责窗口的创建、前后台切换，以及整个页面的销毁清理。

2.文件代码A（可直接复制替换使用）

项目中目录 entry/src/main/ets/entryability/EntryAbility.ets

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';// 定义日志域号（方便分类输出日志）domain_number
const DOMAIN_NUMBER: number = 0xFF00;export default class EntryAbility extends UIAbility {// 保存窗口舞台对象，用于后续注销监听或清理windowStage: window.WindowStage | undefined = undefined;/*** 🧱 Ability 创建阶段（应用启动时）* 可在此初始化全局变量、注册服务或准备数据。*/onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {hilog.info(DOMAIN_NUMBER, 'testTag', 'Ability 创建完成 → onCreate');}/*** 🪟 窗口舞台创建阶段（UI 窗口创建完成）* 通常在此加载主页面，并注册窗口事件监听。*/onWindowStageCreate(windowStage: window.WindowStage): void {this.windowStage = windowStage; // ✅ 保存当前窗口引用try {// 监听窗口事件（前台/后台、焦点变化等）windowStage.on('windowStageEvent', (data) => {let stageEventType: window.WindowStageEventType = data;switch (stageEventType) {case window.WindowStageEventType.SHOWN:hilog.info(DOMAIN_NUMBER, 'testTag', '窗口切换到前台（SHOWN）');break;case window.WindowStageEventType.ACTIVE:hilog.info(DOMAIN_NUMBER, 'testTag', '窗口获得焦点（ACTIVE）');break;case window.WindowStageEventType.INACTIVE:hilog.info(DOMAIN_NUMBER, 'testTag', '窗口失去焦点（INACTIVE）');break;case window.WindowStageEventType.HIDDEN:hilog.info(DOMAIN_NUMBER, 'testTag', '窗口切换到后台（HIDDEN）');break;case window.WindowStageEventType.RESUMED:hilog.info(DOMAIN_NUMBER, 'testTag', '窗口恢复可交互（RESUMED）');break;case window.WindowStageEventType.PAUSED:hilog.info(DOMAIN_NUMBER, 'testTag', '窗口暂停交互（PAUSED）');break;default:break;}});} catch (exception) {hilog.error(DOMAIN_NUMBER, 'testTag',`监听窗口事件失败，原因: ${JSON.stringify(exception)}`);}// 加载主页面内容hilog.info(DOMAIN_NUMBER, 'testTag', '窗口阶段创建完成 → onWindowStageCreate');windowStage.loadContent('pages/Index', (err) => {if (err.code) {hilog.error(DOMAIN_NUMBER, 'testTag',`加载页面失败，原因: ${JSON.stringify(err) ?? ''}`);return;}hilog.info(DOMAIN_NUMBER, 'testTag', '主页面加载成功');});}/*** ⚠️ 窗口即将销毁（可访问 windowStage）* 在此阶段应注销监听事件、释放通过 windowStage 获取的资源。* ⚠️ 注意：窗口仍然存在，但马上就要被销毁。*/onWindowStageWillDestroy(windowStage: window.WindowStage): void {try {if (this.windowStage) {this.windowStage.off('windowStageEvent'); // 注销事件监听hilog.info(DOMAIN_NUMBER, 'testTag', '已注销 windowStageEvent 监听');}} catch (err) {let code = (err as BusinessError).code;let message = (err as BusinessError).message;hilog.error(DOMAIN_NUMBER, 'testTag',`取消监听失败，错误码：${code}，信息：${message}`);}hilog.info(DOMAIN_NUMBER, 'testTag', '窗口即将销毁 → onWindowStageWillDestroy');}/*** 💥 窗口销毁完成（windowStage 已被系统释放）* 此时不能再访问 windowStage 对象。* 一般用于记录日志或清理全局资源引用。*/onWindowStageDestroy(): void {this.windowStage = undefined; // 释放引用hilog.info(DOMAIN_NUMBER, 'testTag', '窗口阶段销毁完成 → onWindowStageDestroy');}/*** 🚀 Ability 切换到前台（应用可见时触发）* 可恢复动画、重启任务、刷新数据等。*/onForeground(): void {hilog.info(DOMAIN_NUMBER, 'testTag', '切换到前台 → onForeground');}/*** 🌙 Ability 切换到后台（应用不可见时触发）* 可保存状态、暂停任务、释放部分资源。*/onBackground(): void {hilog.info(DOMAIN_NUMBER, 'testTag', '切换到后台 → onBackground');}/*** 💣 Ability 销毁阶段（整个能力被系统回收时）* 一般在此做彻底清理，如移除全局监听、释放单例资源。*/onDestroy(): void {hilog.info(DOMAIN_NUMBER, 'testTag', 'Ability 销毁完成 → onDestroy');}
}

3.根据代码A，模拟器效果截图显示

• 运行项目代码，根据图片指示顺序，可根据输入日志观察各事件的效果。
  
• 将程序至于后台，然后观察输入日志
  
• 程序置于后台后，观察工作台的输入内容
  
• 从后台中打开程序，然后观察工作台的输入内容
  
• 工作台输入内容变化
  

4.生命周期阶段拆解

生命周期方法	触发时机	常见用途
onCreate()	Ability 创建时（应用启动）	初始化全局变量、注册服务、准备数据
onWindowStageCreate()	UI 窗口创建完成	加载主页面、注册窗口事件
onWindowStageWillDestroy()	窗口即将销毁	注销监听、释放资源
onWindowStageDestroy()	窗口销毁完成	彻底清理引用
onForeground()	Ability 切到前台	恢复动画、刷新数据
onBackground()	Ability 切到后台	保存状态、暂停任务
onDestroy()	Ability 销毁	释放单例、清理全局资源

4.1 onCreate()

应用启动时最先执行。
可在这里初始化全局变量、配置日志域号、注册全局服务。

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {hilog.info(DOMAIN_NUMBER, 'testTag', 'Ability 创建完成 → onCreate');
}

4.2 onWindowStageCreate()

当窗口（WindowStage）准备好后触发。
这里可以加载主页面内容，并注册窗口事件监听。

onWindowStageCreate(windowStage: window.WindowStage): void {this.windowStage = windowStage;// 监听窗口事件（前台/后台/焦点变化）windowStage.on('windowStageEvent', (data) => {switch (data) {case window.WindowStageEventType.SHOWN:hilog.info(DOMAIN_NUMBER, 'testTag', '窗口切换到前台（SHOWN）');break;case window.WindowStageEventType.HIDDEN:hilog.info(DOMAIN_NUMBER, 'testTag', '窗口切换到后台（HIDDEN）');break;}});// 加载页面windowStage.loadContent('pages/Index', (err) => {if (err.code) return;hilog.info(DOMAIN_NUMBER, 'testTag', '主页面加载成功');});
}

4.3 onWindowStageWillDestroy()

窗口还存在，但马上要销毁。
此时适合 取消事件监听、释放资源引用。

onWindowStageWillDestroy(windowStage: window.WindowStage): void {if (this.windowStage) {this.windowStage.off('windowStageEvent');hilog.info(DOMAIN_NUMBER, 'testTag', '已注销 windowStageEvent 监听');}
}

4.4 onWindowStageDestroy()

窗口已经被系统彻底销毁。
不能再访问 windowStage 对象。

onWindowStageDestroy(): void {this.windowStage = undefined;hilog.info(DOMAIN_NUMBER, 'testTag', '窗口阶段销毁完成 → onWindowStageDestroy');
}

4.5 onForeground()

应用回到前台。
可在此恢复动画、刷新数据。

onForeground(): void {hilog.info(DOMAIN_NUMBER, 'testTag', '切换到前台 → onForeground');
}

4.6 onBackground()

应用切换到后台。
保存状态、暂停耗时任务是个好时机。

onBackground(): void {hilog.info(DOMAIN_NUMBER, 'testTag', '切换到后台 → onBackground');
}

4.7 onDestroy()

Ability 即将被系统销毁。
可以清理缓存、注销全局服务、释放单例。

onDestroy(): void {hilog.info(DOMAIN_NUMBER, 'testTag', 'Ability 销毁完成 → onDestroy');
}

5.补充说明(onNewWant())

关于onNewWant()，华为官方的说明如下：
当应用的UIAbility实例已创建，再次调用方法启动该UIAbility实例时，系统触发该UIAbility的onNewWant()回调。开发者可以在该回调中更新要加载的资源和数据等，用于后续的UI展示。

后续根据使用率需要看是否需要补充相关的内容知识，本篇文章不多写该相关内容了。

6.结语

因为每个人的记忆力是有限的，过往的知识可能会暂时性想不起来，本文为方便技术人员快速重新拾起内容而创作。更详细的内容更推荐查阅官方文档。

华为官方UIAbility生命周期相关内容的指南参考地址UIAbility组件生命周期
由于笔者的能力有限，创作的内容有所不足在所难免，也敬请读者包涵和指出，万分感谢！

7.定位日期

2025.10.13；
17:26