1# @ohos.app.ability.abilityLifecycleCallback (AbilityLifecycleCallback) 2 3The **AbilityLifecycleCallback** module defines the callbacks to receive lifecycle changes of [ApplicationContext](js-apis-inner-application-applicationContext.md). 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> 9> The APIs of this module can be used only in the stage model. 10 11## Modules to Import 12 13```ts 14import { AbilityLifecycleCallback } from '@kit.AbilityKit'; 15``` 16 17## AbilityLifecycleCallback.onAbilityCreate 18 19onAbilityCreate(ability: UIAbility): void 20 21Called when an ability is created. 22 23**Atomic service API**: This API can be used in atomic services since API version 11. 24 25**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 26 27**Parameters** 28 29 | Name| Type| Mandatory| Description| 30 | -------- | -------- | -------- | -------- | 31 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 32 33**Example** 34 35See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 36 37## AbilityLifecycleCallback.onWindowStageCreate 38 39onWindowStageCreate(ability: UIAbility, windowStage: window.WindowStage): void 40 41Called when the window stage of an ability is created. 42 43**Atomic service API**: This API can be used in atomic services since API version 11. 44 45**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 46 47**Parameters** 48 49 | Name| Type| Mandatory| Description| 50 | -------- | -------- | -------- | -------- | 51 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 52 | windowStage | [window.WindowStage](../apis-arkui/js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| 53 54**Example** 55 56See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 57 58## AbilityLifecycleCallback.onWindowStageActive 59 60onWindowStageActive(ability: UIAbility, windowStage: window.WindowStage): void 61 62Called when the window stage of an ability gains focus. 63 64**Atomic service API**: This API can be used in atomic services since API version 11. 65 66**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 67 68**Parameters** 69 70 | Name| Type| Mandatory| Description| 71 | -------- | -------- | -------- | -------- | 72 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 73 | windowStage | [window.WindowStage](../apis-arkui/js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| 74 75**Example** 76 77See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 78 79## AbilityLifecycleCallback.onWindowStageInactive 80 81onWindowStageInactive(ability: UIAbility, windowStage: window.WindowStage): void 82 83Called when the window stage of an ability loses focus. 84 85**Atomic service API**: This API can be used in atomic services since API version 11. 86 87**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 88 89**Parameters** 90 91 | Name| Type| Mandatory| Description| 92 | -------- | -------- | -------- | -------- | 93 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 94 | windowStage | [window.WindowStage](../apis-arkui/js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| 95 96**Example** 97 98See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 99 100## AbilityLifecycleCallback.onWindowStageDestroy 101 102onWindowStageDestroy(ability: UIAbility, windowStage: window.WindowStage): void 103 104Called when the window stage of an ability is destroyed. 105 106**Atomic service API**: This API can be used in atomic services since API version 11. 107 108**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 109 110**Parameters** 111 112 | Name| Type| Mandatory| Description| 113 | -------- | -------- | -------- | -------- | 114 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 115 | windowStage | [window.WindowStage](../apis-arkui/js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| 116 117**Example** 118 119See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 120 121## AbilityLifecycleCallback.onAbilityDestroy 122 123onAbilityDestroy(ability: UIAbility): void 124 125Called when an ability is destroyed. 126 127**Atomic service API**: This API can be used in atomic services since API version 11. 128 129**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 130 131**Parameters** 132 133 | Name| Type| Mandatory| Description| 134 | -------- | -------- | -------- | -------- | 135 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 136 137**Example** 138 139See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 140 141## AbilityLifecycleCallback.onAbilityForeground 142 143onAbilityForeground(ability: UIAbility): void 144 145Called when an ability is switched from the background to the foreground. 146 147**Atomic service API**: This API can be used in atomic services since API version 11. 148 149**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 150 151**Parameters** 152 153 | Name| Type| Mandatory| Description| 154 | -------- | -------- | -------- | -------- | 155 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 156 157**Example** 158 159See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 160 161## AbilityLifecycleCallback.onAbilityBackground 162 163onAbilityBackground(ability: UIAbility): void 164 165Called when an ability is switched from the foreground to the background. 166 167**Atomic service API**: This API can be used in atomic services since API version 11. 168 169**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 170 171**Parameters** 172 173 | Name| Type| Mandatory| Description| 174 | -------- | -------- | -------- | -------- | 175 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 176 177**Example** 178 179See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 180 181## AbilityLifecycleCallback.onAbilityContinue 182 183onAbilityContinue(ability: UIAbility): void 184 185Called when an ability is continued on another device. 186 187**Atomic service API**: This API can be used in atomic services since API version 11. 188 189**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 190 191**Parameters** 192 193 | Name| Type| Mandatory| Description| 194 | -------- | -------- | -------- | -------- | 195 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 196 197**Example** 198 199See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 200 201## AbilityLifecycleCallback.onAbilityWillCreate<sup>12+</sup> 202 203onAbilityWillCreate?(ability: UIAbility): void 204 205Called before the [onCreate](js-apis-app-ability-uiAbility.md#uiabilityoncreate) callback of the UIAbility is triggered. 206 207**Atomic service API**: This API can be used in atomic services since API version 12. 208 209**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 210 211**Parameters** 212 213 | Name| Type| Mandatory| Description| 214 | -------- | -------- | -------- | -------- | 215 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 216 217**Example** 218 219See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 220 221## AbilityLifecycleCallback.onWindowStageWillCreate<sup>12+</sup> 222 223onWindowStageWillCreate?(ability: UIAbility, windowStage: window.WindowStage): void 224 225Called before the [onWindowStageCreate](js-apis-app-ability-uiAbility.md#uiabilityonwindowstagecreate) callback of the UIAbility is triggered. 226 227**Atomic service API**: This API can be used in atomic services since API version 12. 228 229**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 230 231**Parameters** 232 233 | Name| Type| Mandatory| Description| 234 | -------- | -------- | -------- | -------- | 235 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 236 | windowStage | [window.WindowStage](../apis-arkui/js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| 237 238**Example** 239 240See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 241 242## AbilityLifecycleCallback.onWindowStageWillDestroy<sup>12+</sup> 243 244onWindowStageWillDestroy?(ability: UIAbility, windowStage: window.WindowStage): void 245 246Called before the [onWindowStageDestroy](js-apis-app-ability-uiAbility.md#uiabilityonwindowstagedestroy) callback of the UIAbility is triggered. 247 248**Atomic service API**: This API can be used in atomic services since API version 12. 249 250**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 251 252**Parameters** 253 254 | Name| Type| Mandatory| Description| 255 | -------- | -------- | -------- | -------- | 256 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 257 | windowStage | [window.WindowStage](../apis-arkui/js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| 258 259**Example** 260 261See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 262 263## AbilityLifecycleCallback.onAbilityWillForeground<sup>12+</sup> 264 265onAbilityWillForeground?(ability: UIAbility): void 266 267Called before the [onForeground](js-apis-app-ability-uiAbility.md#uiabilityonforeground) callback of the UIAbility is triggered. 268 269**Atomic service API**: This API can be used in atomic services since API version 12. 270 271**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 272 273**Parameters** 274 275 | Name| Type| Mandatory| Description| 276 | -------- | -------- | -------- | -------- | 277 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 278 279**Example** 280 281See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 282 283## AbilityLifecycleCallback.onAbilityWillDestroy<sup>12+</sup> 284 285onAbilityWillDestroy?(ability: UIAbility): void 286 287Called before the [onDestroy](js-apis-app-ability-uiAbility.md#uiabilityondestroy) callback of the UIAbility is triggered. 288 289**Atomic service API**: This API can be used in atomic services since API version 12. 290 291**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 292 293**Parameters** 294 295 | Name| Type| Mandatory| Description| 296 | -------- | -------- | -------- | -------- | 297 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 298 299**Example** 300 301See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 302 303## AbilityLifecycleCallback.onAbilityWillBackground<sup>12+</sup> 304 305onAbilityWillBackground?(ability: UIAbility): void 306 307Called before the [onBackground](js-apis-app-ability-uiAbility.md#uiabilityonbackground) callback of the UIAbility is triggered. 308 309**Atomic service API**: This API can be used in atomic services since API version 12. 310 311**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 312 313**Parameters** 314 315 | Name| Type| Mandatory| Description| 316 | -------- | -------- | -------- | -------- | 317 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 318 319**Example** 320 321See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 322 323## AbilityLifecycleCallback.onWillNewWant<sup>12+</sup> 324 325onWillNewWant?(ability: UIAbility): void 326 327Called before the [onNewWant](js-apis-app-ability-uiAbility.md#uiabilityonnewwant) callback of the UIAbility is triggered. 328 329**Atomic service API**: This API can be used in atomic services since API version 12. 330 331**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 332 333**Parameters** 334 335 | Name| Type| Mandatory| Description| 336 | -------- | -------- | -------- | -------- | 337 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 338 339**Example** 340 341See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 342 343## AbilityLifecycleCallback.onNewWant<sup>12+</sup> 344 345onNewWant?(ability: UIAbility): void 346 347Called after the [onNewWant](js-apis-app-ability-uiAbility.md#uiabilityonnewwant) callback of the UIAbility is triggered. 348 349**Atomic service API**: This API can be used in atomic services since API version 12. 350 351**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 352 353**Parameters** 354 355 | Name| Type| Mandatory| Description| 356 | -------- | -------- | -------- | -------- | 357 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 358 359**Example** 360 361See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 362 363## AbilityLifecycleCallback.onAbilityWillContinue<sup>12+</sup> 364 365onAbilityWillContinue?(ability: UIAbility): void 366 367Called before the [onContinue](js-apis-app-ability-uiAbility.md#uiabilityoncontinue) callback of the UIAbility is triggered. 368 369**Atomic service API**: This API can be used in atomic services since API version 12. 370 371**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 372 373**Parameters** 374 375 | Name| Type| Mandatory| Description| 376 | ------ | ------ | ------ | ------ | 377 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 378 379**Example** 380 381See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 382 383## AbilityLifecycleCallback.onWindowStageWillRestore<sup>12+</sup> 384 385onWindowStageWillRestore?(ability: UIAbility, windowStage: window.WindowStage): void 386 387Called before the [onWindowStageRestore](js-apis-app-ability-uiAbility.md#uiabilityonwindowstagerestore) callback of the UIAbility is triggered. 388 389**Atomic service API**: This API can be used in atomic services since API version 12. 390 391**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 392 393**Parameters** 394 395 | Name| Type| Mandatory| Description| 396 | ------ | ------ | ------ | ------ | 397 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 398 | windowStage | [window.WindowStage](../apis-arkui/js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| 399 400**Example** 401 402See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 403 404## AbilityLifecycleCallback.onWindowStageRestore<sup>12+</sup> 405 406onWindowStageRestore?(ability: UIAbility, windowStage: window.WindowStage): void 407 408Called after the [onWindowStageRestore](js-apis-app-ability-uiAbility.md#uiabilityonwindowstagerestore) callback of the UIAbility is triggered. 409 410**Atomic service API**: This API can be used in atomic services since API version 12. 411 412**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 413 414**Parameters** 415 416 | Name| Type| Mandatory| Description| 417 | ------ | ------ | ------ | ------ | 418 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 419 | windowStage | [window.WindowStage](../apis-arkui/js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| 420 421**Example** 422 423See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 424 425## AbilityLifecycleCallback.onAbilityWillSaveState<sup>12+</sup> 426 427onAbilityWillSaveState?(ability: UIAbility): void 428 429Called before the [onSaveState](js-apis-app-ability-uiAbility.md#uiabilityonsavestate) callback of the UIAbility is triggered. 430 431**Atomic service API**: This API can be used in atomic services since API version 12. 432 433**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 434 435**Parameters** 436 437 | Name| Type| Mandatory| Description| 438 | ------ | ------ | ------ | ------ | 439 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 440 441**Example** 442 443See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 444 445## AbilityLifecycleCallback.onAbilitySaveState<sup>12+</sup> 446 447onAbilitySaveState?(ability: UIAbility): void 448 449Called after the [onSaveState](js-apis-app-ability-uiAbility.md#uiabilityonsavestate) callback of the UIAbility is triggered. 450 451**Atomic service API**: This API can be used in atomic services since API version 12. 452 453**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 454 455**Parameters** 456 457 | Name| Type| Mandatory| Description| 458 | ------ | ------ | ------ | ------ | 459 | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes| **Ability** object.| 460 461**Example** 462 463See [Usage of AbilityLifecycleCallback](#usage-of-abilitylifecyclecallback). 464 465## Usage of AbilityLifecycleCallback 466 467**Example** 468GlobalContext.ts 469Global context 470```ts 471// Construct a singleton object. 472export class GlobalContext { 473 private constructor() {} 474 private static instance: GlobalContext; 475 private _objects = new Map<string, Object>(); 476 477 public static getContext(): GlobalContext { 478 if (!GlobalContext.instance) { 479 GlobalContext.instance = new GlobalContext(); 480 } 481 return GlobalContext.instance; 482 } 483 484 getObject(value: string): Object | undefined { 485 return this._objects.get(value); 486 } 487 488 setObject(key: string, objectClass: Object): void { 489 this._objects.set(key, objectClass); 490 } 491} 492``` 493 494MyFirstAbility.ts 495First ability of the application 496```ts 497import { AbilityLifecycleCallback, UIAbility } from '@kit.AbilityKit'; 498import { window } from '@kit.ArkUI'; 499 500// Import GlobalContext. Use the actual path declared. 501import { GlobalContext } from '../GlobalContext' 502 503// Declare the ability lifecycle callbacks. A listener can be registered in applicationContext only after all the callbacks are configured. 504let abilityLifecycleCallback: AbilityLifecycleCallback = { 505 onAbilityCreate(ability){ 506 console.log('AbilityLifecycleCallback onAbilityCreate.'); 507 }, 508 onWindowStageCreate(ability, windowStage){ 509 console.log('AbilityLifecycleCallback onWindowStageCreate.'); 510 }, 511 onWindowStageActive(ability, windowStage){ 512 console.log('AbilityLifecycleCallback onWindowStageActive.'); 513 }, 514 onWindowStageInactive(ability, windowStage){ 515 console.log('AbilityLifecycleCallback onWindowStageInactive.'); 516 }, 517 onWindowStageDestroy(ability, windowStage){ 518 console.log('AbilityLifecycleCallback onWindowStageDestroy.'); 519 }, 520 onAbilityDestroy(ability){ 521 console.log('AbilityLifecycleCallback onAbilityDestroy.'); 522 }, 523 onAbilityForeground(ability){ 524 console.log('AbilityLifecycleCallback onAbilityForeground.'); 525 }, 526 onAbilityBackground(ability){ 527 console.log('AbilityLifecycleCallback onAbilityBackground.'); 528 }, 529 onAbilityContinue(ability){ 530 console.log('AbilityLifecycleCallback onAbilityContinue.'); 531 }, 532 onNewWant(ability) { 533 console.log('AbilityLifecycleCallback onNewWant'); 534 }, 535 onWillNewWant(ability) { 536 console.log('AbilityLifecycleCallback onWillNewWant'); 537 }, 538 onAbilityWillCreate(ability) { 539 console.log('AbilityLifecycleCallback onAbilityWillCreate'); 540 }, 541 onWindowStageWillCreate(ability, windowStage) { 542 console.log('AbilityLifecycleCallback onWindowStageWillCreate'); 543 }, 544 onWindowStageWillDestroy(ability, windowStage) { 545 console.log('AbilityLifecycleCallback onWindowStageWillDestroy'); 546 }, 547 onAbilityWillDestroy(ability) { 548 console.log('AbilityLifecycleCallback onAbilityWillDestroy'); 549 }, 550 onAbilityWillForeground(ability) { 551 console.log('AbilityLifecycleCallback onAbilityWillForeground'); 552 }, 553 onAbilityWillBackground(ability) { 554 console.log('AbilityLifecycleCallback onAbilityWillBackground'); 555 }, 556 onAbilityWillContinue(ability: UIAbility) { 557 console.log('AbilityLifecycleCallback onAbilityWillContinue.'); 558 }, 559 onWindowStageWillRestore(ability: UIAbility, windowStage: window.WindowStage) { 560 console.log('AbilityLifecycleCallback onWindowStageWillRestore.'); 561 }, 562 onWindowStageRestore(ability: UIAbility, windowStage: window.WindowStage) { 563 console.log('AbilityLifecycleCallback onWindowStageRestore.'); 564 }, 565 onAbilityWillSaveState(ability: UIAbility) { 566 console.log('AbilityLifecycleCallback onAbilityWillSaveState.'); 567 }, 568 onAbilitySaveState(ability: UIAbility) { 569 console.log('AbilityLifecycleCallback onAbilitySaveState.'); 570 } 571}; 572 573export default class MyFirstAbility extends UIAbility { 574 onCreate() { 575 console.log('MyAbilityStage onCreate'); 576 // 1. Obtain applicationContext through the context property. 577 let applicationContext = this.context.getApplicationContext(); 578 // 2. Register the listener for the ability lifecycle changes through the applicationContext object. 579 try { 580 let lifecycleId = applicationContext.on('abilityLifecycle', abilityLifecycleCallback); 581 GlobalContext.getContext().setObject("lifecycleId", lifecycleId); 582 console.log(`registerAbilityLifecycleCallback lifecycleId: ${GlobalContext.getContext().getObject('lifecycleId')}`); 583 } catch (paramError) { 584 console.error(`error: ${paramError.code}, ${paramError.message}`); 585 } 586 } 587} 588``` 589 590MySecondAbility.ts 591Second ability of the application 592```ts 593import { UIAbility } from '@kit.AbilityKit'; 594 595// Import GlobalContext. Use the actual path declared. 596import { GlobalContext } from '../GlobalContext' 597import { BusinessError } from '@ohos.base'; 598 599export default class MySecondAbility extends UIAbility { 600 onDestroy() { 601 let applicationContext = this.context.getApplicationContext(); 602 let lifecycleId = GlobalContext.getContext().getObject("lifecycleId") as number; 603 try { 604 // 3. Deregister the listener for the ability lifecycle changes through the applicationContext object. 605 applicationContext.off('abilityLifecycle', lifecycleId, (error) => { 606 if (error && error.code !== 0) { 607 console.error(`unregisterAbilityLifecycleCallback fail, error: ${JSON.stringify(error)}`); 608 } else { 609 console.log('unregisterAbilityLifecycleCallback success.'); 610 } 611 }); 612 } catch (paramError) { 613 console.error(`error: ${(paramError as BusinessError).code}, ${(paramError as BusinessError).message}`); 614 } 615 } 616} 617``` 618