arkTs：UIAbility 组件的生命周期

1 主要内容说明

在 ArkTS（HarmonyOS NEXT）应用中，UIAbility 是最常见的能力类型，负责管理整个应用的生命周期事件。而窗口（WindowStage）作为界面承载层，也有独立的生命周期回调。理解这些生命周期，对于正确地管理资源、初始化页面、监听事件等操作至关重要。

该部分内容文件的路径为 src/main/ets/entryability/entryability.ets。生命周期事件在entryability.ets文件中编辑使用。

1.1 能力（Ability）生命周期

生命周期方法	触发时机	常见用途
onCreate	Ability 实例创建时	初始化全局状态，接收启动参数
onForeground	Ability 进入前台	（可见）时 重新加载数据、恢复定时器
onBackground	Ability 进入后台	（不可见）时 保存状态、暂停任务
onDestroy	Ability 被销毁时	释放资源、清理缓存

1.2 窗口（WindowStage）生命周期

生命周期方法	触发时机	常见用途
onWindowStageCreate	窗口创建时	加载页面、设置窗口事件监听
onWindowStageWillDestroy	窗口即将销毁前	停止计时器、解绑事件、保存页面状态
onWindowStageDestroy	窗口销毁完成后	记录日志、资源归档、通知销毁完成

1.3 实际开发建议

• 若需保存页面状态、解绑监听器，请在 onWindowStageWillDestroy() 中完成。
• onWindowStageDestroy() 更适合用于日志记录或启动后续逻辑流程。
• 避免在 onWindowStageDestroy() 中访问 UI 元素，因为此时窗口已被销毁。

1.4 监听窗口事件

1.4.1 相关代码

windowStage.getMainWindow().then((win: window.Window) => {win.on('windowEvent', (event: window.WindowEventType) => {console.log('===>', '[窗口事件] 触发 windowEvent -> 类型:', event);});});

1.4.2 窗口生命周期WindowEventType枚举

名称	值	说明
WINDOW_SHOWN	1	切到前台
WINDOW_ACTIVE	2	获焦状态
WINDOW_INACTIVE	3	失焦状态
WINDOW_HIDDEN	4	切到后台
WINDOW_DESTROYED	7	窗口销毁

2 例子

2.1 源码A

• 文件路径：src/main/ets/entryability/entryability.ets
• 这段代码展示了一个 UIAbility 的完整生命周期实现，涵盖了 Ability 自身的创建与销毁、窗口的创建与销毁、以及前后台切换处理。

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';export default class EntryAbility extends UIAbility {/*** Ability 创建时触发（初始化阶段）*/onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {console.log('===>', '[生命周期] Ability 创建 -> onCreate');}/*** Ability 销毁时触发（资源释放阶段）*/onDestroy(): void {console.log('===>', '[生命周期] Ability 销毁 -> onDestroy');}/*** 窗口阶段创建时触发（适合加载 UI 页面、监听窗口事件等）*/onWindowStageCreate(windowStage: window.WindowStage): void {// 加载首页页面内容windowStage.loadContent('pages/Index').then(() => {console.log('===>', '[页面] 首页加载完成 -> pages/Index');}).catch((err: BusinessError) => {console.error('===>', '[页面] 加载失败:', JSON.stringify(err));});// 获取主窗口对象并监听窗口事件windowStage.getMainWindow().then((win: window.Window) => {win.on('windowEvent', (event: window.WindowEventType) => {console.log('===>', '[窗口事件] 触发 windowEvent -> 类型:', event);});});}/*** 窗口即将销毁时触发（适合做解绑和清理操作）*/onWindowStageWillDestroy(windowStage: window.WindowStage): void {console.log('===>', '[生命周期] WindowStage 即将销毁 -> onWindowStageWillDestroy');// 可在此处：// - 停止定时器// - 解绑 window 事件监听器// - 清理页面缓存或保存状态}/*** 销毁完成后触发（页面资源清理）* 通知你，表示窗口已经没有了*/onWindowStageDestroy(): void {console.log('===>', '[生命周期] WindowStage 销毁 -> onWindowStageDestroy');}/*** Ability 切入前台时触发（可见、可交互）*/onForeground(): void {console.log('===>', '[生命周期] Ability 切入前台 -> onForeground');// 可用于：恢复数据、重连服务、重启定时器等}/*** Ability 切入后台时触发（不可见）*/onBackground(): void {console.log('===>', '[生命周期] Ability 切入后台 -> onBackground');// 可用于：保存状态、断开连接、释放资源等}
}

2.2 源码A的运行效果

2.2.1 效果截图

2.2.1.1 运行程序

• 当运行程序后，进入窗口主页面，可查看此时控制台的打印显示内容
  

2.2.1.2 将程序置于后台

2.2.1.3 再次回到程序页面

2.2.1.4 退出程序

2.2.2 效果视频

3.结语

UIAbility的生命周期内容事件有多个，可分层来记，如功能的创建到销毁，窗口的创建到销毁，这样容易理解和记忆。其实内容并不难，主要是一些状态不常使用久了就容易忘记如何拼写使用。由此简单记录一下，便于后期重新拾起。

理解程序的生命周期是有必要的，如进入程序前要做什么，需不需要提前加载内容数据。像进入程序前的广告，可以在onWindowStageCreate设置相关参数内容，在进入程序前，可以先加载接收广告的内容，再跳转到主页。也不一定是onWindowStageCreate的内容，也可以是其他状态内容，具体如何使用哪个状态的生命周期内容，根据实际情况使用。

华为官方UIAbility组件生命周期的指南参考地址UIAbility组件生命周期
华为官方on('windowEvent')开启窗口生命周期变化的监听API参考地址开启窗口生命周期变化的监听
华为官方WindowEventType窗口生命周期API参考地址窗口生命周期

由于笔者的能力有限，创作的内容有所不足在所难免，也敬请读者包涵和指出，万分感谢！

4.定位日期

2025-4-21；
16:29；