文档管理中心
您当前正在浏览HarmonyOS最新文档,覆盖已发布的所有API版本,可在API参考中筛选您使用的API版本。详细的版本配套关系请参考版本说明
API参考应用框架Ability Kit(程序框架服务)ArkTS APIStage模型能力的接口@ohos.app.ability.abilityLifecycleCallback (UIAbility生命周期回调监听器)

@ohos.app.ability.abilityLifecycleCallback (UIAbility生命周期回调监听器)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

UIAbility从创建到销毁过程其生命周期是动态变化的。AbilityLifecycleCallback模块提供监听UIAbility生命周期变化的能力,可用于统计每个UIAbility的运行时长、执行与UIAbility业务逻辑解耦的数据加载等场景。

说明

本模块首批接口从API version 9 开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

本模块接口仅可在Stage模型下使用。

本模块接口只能监听进程内UIAbility生命周期变化。

使用说明

  1. 应用创建AbilityLifecycleCallback对象,并调用ApplicationContext.on('abilityLifecycle')接口注册UIAbility生命周期变化监听。
  2. 当UIAbility生命周期变化时,应用可以通过已注册的AbilityLifecycleCallback对象接收到UIAbility生命周期的变化通知。
  3. 当应用不需要监听UIAbility生命周期变化时,需要通过ApplicationContext.off('abilityLifecycle')接口取消监听。

导入模块

收起
自动换行
深色代码主题
复制
  1. import { AbilityLifecycleCallback } from '@kit.AbilityKit';

AbilityLifecycleCallback

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onAbilityCreate

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onAbilityCreate(ability: UIAbility): void

在UIAbility的onCreate触发后回调。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象。

示例:

参见AbilityLifecycleCallback使用示例

onWindowStageCreate

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onWindowStageCreate(ability: UIAbility, windowStage: window.WindowStage): void

在UIAbility的onWindowStageCreate触发后回调。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象。
windowStage window.WindowStage 回调事件对应的UIAbility主窗管理器。

示例:

参见AbilityLifecycleCallback使用示例

onWindowStageActive

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onWindowStageActive(ability: UIAbility, windowStage: window.WindowStage): void

在UIAbility主窗获焦时触发回调。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象。
windowStage window.WindowStage 回调事件对应的UIAbility主窗管理器。

示例:

参见AbilityLifecycleCallback使用示例

onWindowStageInactive

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onWindowStageInactive(ability: UIAbility, windowStage: window.WindowStage): void

在UIAbility主窗失焦时触发回调。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象。
windowStage window.WindowStage 回调事件对应的UIAbility主窗管理器。

示例:

参见AbilityLifecycleCallback使用示例

onWindowStageDestroy

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onWindowStageDestroy(ability: UIAbility, windowStage: window.WindowStage): void

在UIAbility的onWindowStageDestroy触发后回调。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象
windowStage window.WindowStage 回调事件对应的UIAbility主窗管理器。

示例:

参见AbilityLifecycleCallback使用示例

onAbilityDestroy

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onAbilityDestroy(ability: UIAbility): void

在UIAbility的onDestroy触发后回调。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象。

示例:

参见AbilityLifecycleCallback使用示例

onAbilityForeground

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onAbilityForeground(ability: UIAbility): void

在UIAbility的onForeground触发后回调。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象。

示例:

参见AbilityLifecycleCallback使用示例

onAbilityBackground

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onAbilityBackground(ability: UIAbility): void

在UIAbility的onBackground触发后回调。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象。

示例:

参见AbilityLifecycleCallback使用示例

onAbilityContinue

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onAbilityContinue(ability: UIAbility): void

在UIAbility的onContinue触发后回调。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象。

示例:

参见AbilityLifecycleCallback使用示例

onAbilityWillCreate12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onAbilityWillCreate?(ability: UIAbility): void

在UIAbility的onCreate触发前回调。

元服务API:从API version 12开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象。

示例:

参见AbilityLifecycleCallback使用示例

onWindowStageWillCreate12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onWindowStageWillCreate?(ability: UIAbility, windowStage: window.WindowStage): void

在UIAbility的onWindowStageCreate触发前回调。

元服务API:从API version 12开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象。
windowStage window.WindowStage 回调事件对应的UIAbility主窗管理器。

示例:

参见AbilityLifecycleCallback使用示例

onWindowStageWillDestroy12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onWindowStageWillDestroy?(ability: UIAbility, windowStage: window.WindowStage): void

在UIAbility的onWindowStageDestroy触发前回调。

元服务API:从API version 12开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象。
windowStage window.WindowStage 回调事件对应的UIAbility主窗管理器。

示例:

参见AbilityLifecycleCallback使用示例

onAbilityWillForeground12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onAbilityWillForeground?(ability: UIAbility): void

在UIAbility的onForeground触发前回调。

元服务API:从API version 12开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象。

示例:

参见AbilityLifecycleCallback使用示例

onAbilityWillDestroy12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onAbilityWillDestroy?(ability: UIAbility): void

在UIAbility的onDestroy触发前回调。

元服务API:从API version 12开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象。

示例:

参见AbilityLifecycleCallback使用示例

onAbilityWillBackground12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onAbilityWillBackground?(ability: UIAbility): void

在UIAbility的onBackground触发前回调。

元服务API:从API version 12开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象。

示例:

参见AbilityLifecycleCallback使用示例

onWillNewWant12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onWillNewWant?(ability: UIAbility): void

在UIAbility的onNewWant触发前回调。

元服务API:从API version 12开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象。

示例:

参见AbilityLifecycleCallback使用示例

onNewWant12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onNewWant?(ability: UIAbility): void

在UIAbility的onNewWant触发后回调。

元服务API:从API version 12开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象。

示例:

参见AbilityLifecycleCallback使用示例

onAbilityWillContinue12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onAbilityWillContinue?(ability: UIAbility): void

在UIAbility的onContinue触发前回调。

元服务API:从API version 12开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象。

示例:

参见AbilityLifecycleCallback使用示例

onWindowStageWillRestore12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onWindowStageWillRestore?(ability: UIAbility, windowStage: window.WindowStage): void

在UIAbility的onWindowStageRestore触发前回调。

元服务API:从API version 12开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象。
windowStage window.WindowStage 回调事件对应的UIAbility主窗管理器。

示例:

参见AbilityLifecycleCallback使用示例

onWindowStageRestore12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onWindowStageRestore?(ability: UIAbility, windowStage: window.WindowStage): void

在UIAbility的onWindowStageRestore触发后回调。

元服务API:从API version 12开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象。
windowStage window.WindowStage 回调事件对应的UIAbility主窗管理器。

示例:

参见AbilityLifecycleCallback使用示例

onAbilityWillSaveState12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onAbilityWillSaveState?(ability: UIAbility): void

在UIAbility的onSaveState触发前回调。

元服务API:从API version 12开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象。

示例:

参见AbilityLifecycleCallback使用示例

onAbilitySaveState12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onAbilitySaveState?(ability: UIAbility): void

在UIAbility的onSaveState触发后回调。

元服务API:从API version 12开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

展开
参数名 类型 必填 说明
ability UIAbility 回调事件对应的UIAbility对象。

示例:

参见AbilityLifecycleCallback使用示例

AbilityLifecycleCallback使用示例

本示例展示了生命周期监听机制的部分使用场景:

  1. AbilityStage创建时注册监听。
  2. AbilityStage销毁时注销监听。
  3. 监听到对应UIAbility创建时加载资源,监听到对应UIAbility销毁时释放资源。
  4. 在UIAbility创建、销毁及前后台状态切换时,记录事件并向外发送通知。
收起
自动换行
深色代码主题
复制
  1. // 以MyStage.ets文件为例,使用AbilityLifecycleCallback监听UIAbility生命周期
  2. import { AbilityLifecycleCallback, AbilityStage, application, UIAbility } from "@kit.AbilityKit";
  3. import { hilog } from '@kit.PerformanceAnalysisKit';
  4. import { JSON } from "@kit.ArkTS";
  5. import { window } from "@kit.ArkUI";
  6. import { BusinessError } from "@kit.BasicServicesKit";
  7. const DOMAIN = 0x0000;
  8. const TAG = 'testTag';
  9. function loadContent() {
  10. // 加载数据
  11. }
  12. function releaseContent() {
  13. // 释放数据
  14. }
  15. function recordAbilityEvent(abilityName: string) {
  16. // 执行打点
  17. }
  18. function publishEvent() {
  19. // 对外发布通知
  20. }
  21. let abilityLifecycleCallback: AbilityLifecycleCallback = {
  22. onAbilityCreate(ability: UIAbility) {
  23. hilog.info(DOMAIN, TAG, 'onAbilityCreate: ' + ability.context.abilityInfo.name);
  24. // UIAbility事件打点记录
  25. recordAbilityEvent(ability.context.abilityInfo.name);
  26. // 模拟入口UIAbility创建时,加载资源对外发布通知
  27. if (ability.context.abilityInfo.name === 'EntryAbility') {
  28. loadContent();
  29. publishEvent();
  30. }
  31. },
  32. onWindowStageCreate(ability: UIAbility, windowStage: window.WindowStage) {
  33. hilog.info(DOMAIN, TAG, 'AbilityLifecycleCallback onWindowStageCreate.');
  34. },
  35. onWindowStageActive(ability: UIAbility, windowStage: window.WindowStage) {
  36. hilog.info(DOMAIN, TAG, 'AbilityLifecycleCallback onWindowStageActive.');
  37. },
  38. onWindowStageInactive(ability: UIAbility, windowStage: window.WindowStage) {
  39. hilog.info(DOMAIN, TAG, 'AbilityLifecycleCallback onWindowStageInactive.');
  40. },
  41. onWindowStageDestroy(ability: UIAbility, windowStage: window.WindowStage) {
  42. hilog.info(DOMAIN, TAG, 'AbilityLifecycleCallback onWindowStageDestroy.');
  43. },
  44. onAbilityDestroy(ability: UIAbility) {
  45. hilog.info(DOMAIN, TAG, 'onAbilityDestroy: ' + ability.context.abilityInfo.name);
  46. recordAbilityEvent(ability.context.abilityInfo.name);
  47. // 模拟入口UIAbility销毁时,释放资源
  48. if (ability.context.abilityInfo.name === 'EntryAbility') {
  49. releaseContent();
  50. publishEvent();
  51. }
  52. },
  53. onAbilityForeground(ability: UIAbility) {
  54. hilog.info(DOMAIN, TAG, 'AbilityLifecycleCallback onAbilityForeground.');
  55. recordAbilityEvent(ability.context.abilityInfo.name);
  56. if (ability.context.abilityInfo.name === 'EntryAbility') {
  57. publishEvent();
  58. }
  59. },
  60. onAbilityBackground(ability: UIAbility) {
  61. hilog.info(DOMAIN, TAG, 'AbilityLifecycleCallback onAbilityBackground.');
  62. recordAbilityEvent(ability.context.abilityInfo.name);
  63. if (ability.context.abilityInfo.name === 'EntryAbility') {
  64. publishEvent();
  65. }
  66. },
  67. onAbilityContinue(ability: UIAbility) {
  68. hilog.info(DOMAIN, TAG, 'AbilityLifecycleCallback onAbilityContinue.');
  69. },
  70. onNewWant(ability: UIAbility) {
  71. hilog.info(DOMAIN, TAG, 'AbilityLifecycleCallback onNewWant');
  72. },
  73. onWillNewWant(ability: UIAbility) {
  74. hilog.info(DOMAIN, TAG, 'AbilityLifecycleCallback onWillNewWant');
  75. },
  76. onAbilityWillCreate(ability: UIAbility) {
  77. hilog.info(DOMAIN, TAG, 'AbilityLifecycleCallback onAbilityWillCreate');
  78. },
  79. onWindowStageWillCreate(ability: UIAbility, windowStage: window.WindowStage) {
  80. hilog.info(DOMAIN, TAG, 'AbilityLifecycleCallback onWindowStageWillCreate');
  81. },
  82. onWindowStageWillDestroy(ability: UIAbility, windowStage: window.WindowStage) {
  83. hilog.info(DOMAIN, TAG, 'AbilityLifecycleCallback onWindowStageWillDestroy');
  84. },
  85. onAbilityWillDestroy(ability: UIAbility) {
  86. hilog.info(DOMAIN, TAG, 'AbilityLifecycleCallback onAbilityWillDestroy');
  87. },
  88. onAbilityWillForeground(ability: UIAbility) {
  89. hilog.info(DOMAIN, TAG, 'AbilityLifecycleCallback onAbilityWillForeground');
  90. },
  91. onAbilityWillBackground(ability: UIAbility) {
  92. hilog.info(DOMAIN, TAG, 'AbilityLifecycleCallback onAbilityWillBackground');
  93. },
  94. onAbilityWillContinue(ability: UIAbility) {
  95. hilog.info(DOMAIN, TAG, 'AbilityLifecycleCallback onAbilityWillContinue.');
  96. },
  97. onWindowStageWillRestore(ability: UIAbility, windowStage: window.WindowStage) {
  98. hilog.info(DOMAIN, TAG, 'AbilityLifecycleCallback onWindowStageWillRestore.');
  99. },
  100. onWindowStageRestore(ability: UIAbility, windowStage: window.WindowStage) {
  101. hilog.info(DOMAIN, TAG, 'AbilityLifecycleCallback onWindowStageRestore.');
  102. },
  103. onAbilityWillSaveState(ability: UIAbility) {
  104. hilog.info(DOMAIN, TAG, 'AbilityLifecycleCallback onAbilityWillSaveState.');
  105. },
  106. onAbilitySaveState(ability: UIAbility) {
  107. hilog.info(DOMAIN, TAG, 'AbilityLifecycleCallback onAbilitySaveState.');
  108. }
  109. };
  110. let lifecycleId = -1; // 保存监听id
  111. export default class MyStage extends AbilityStage {
  112. onCreate(): void {
  113. hilog.info(DOMAIN, TAG, 'AbilityStage onCreate')
  114. // AbilityStage创建时注册UIAbility生命周期监听,并把监听id保存起来
  115. try {
  116. let applicationContext = application.getApplicationContext();
  117. lifecycleId = applicationContext.on('abilityLifecycle', abilityLifecycleCallback);
  118. } catch (e) {
  119. hilog.error(DOMAIN, TAG, `register abilityLifecycle failed: ${JSON.stringify(e)}`);
  120. }
  121. }
  122. onDestroy(): void {
  123. // AbilityStage销毁时取消UIAbility生命周期监听注册
  124. let applicationContext = application.getApplicationContext();
  125. applicationContext.off('abilityLifecycle', lifecycleId).catch((e: BusinessError) => {
  126. hilog.error(DOMAIN, TAG, `unregister abilityLifecycle failed: ${JSON.stringify(e)}`);
  127. });
  128. }
  129. }
收起
自动换行
深色代码主题
复制
  1. // 以EntryAbility.ets为例,展示应用入口UIAbility
  2. import { AbilityConstant, ConfigurationConstant, UIAbility, Want } from '@kit.AbilityKit';
  3. import { hilog } from '@kit.PerformanceAnalysisKit';
  4. import { window } from '@kit.ArkUI';
  5. const DOMAIN = 0x0000;
  6. const TAG = 'testTag';
  7. export default class EntryAbility extends UIAbility {
  8. onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  9. this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET);
  10. hilog.info(DOMAIN, TAG, 'EntryAbility onCreate');
  11. }
  12. onDestroy(): void {
  13. hilog.info(DOMAIN, TAG, 'EntryAbility onDestroy');
  14. }
  15. onWindowStageCreate(windowStage: window.WindowStage): void {
  16. // 主窗创建
  17. hilog.info(DOMAIN, TAG, 'EntryAbility onWindowStageCreate');
  18. windowStage.loadContent('pages/Index', (err) => {
  19. if (err.code) {
  20. hilog.error(DOMAIN, TAG, 'Failed to load the content. Cause: %{public}s', JSON.stringify(err));
  21. return;
  22. }
  23. hilog.info(DOMAIN, TAG, 'Succeeded in loading the content.');
  24. });
  25. }
  26. onWindowStageDestroy(): void {
  27. // 主窗销毁
  28. hilog.info(DOMAIN, TAG, 'EntryAbility onWindowStageDestroy');
  29. }
  30. onForeground(): void {
  31. // UIAbility切换到前台
  32. hilog.info(DOMAIN, TAG, 'EntryAbility onForeground');
  33. }
  34. onBackground(): void {
  35. // UIAbility切换到后台
  36. hilog.info(DOMAIN, TAG, 'EntryAbility onBackground');
  37. }
  38. }
在 API参考 中进行搜索
请输入您想要搜索的关键词