1# @ohos.app.ability.AbilityStage (AbilityStage) 2 3**AbilityStage** is a runtime class for HAP files. 4 5**AbilityStage** notifies you of when you can perform HAP initialization such as resource pre-loading and thread creation during the HAP loading. 6 7> **NOTE** 8> 9> 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. 10> 11> The APIs of this module can be used only in the stage model. 12 13## Modules to Import 14 15```ts 16import { AbilityStage } from '@kit.AbilityKit'; 17``` 18 19## Properties 20 21**Atomic service API**: This API can be used in atomic services since API version 11. 22 23**System capability**: SystemCapability.Ability.AbilityRuntime.Core 24 25| Name| Type| Read-Only| Optional| Description| 26| -------- | -------- | -------- | -------- | -------- | 27| context | [AbilityStageContext](js-apis-inner-application-abilityStageContext.md) | No| No| Context of an AbilityStage.| 28 29## AbilityStage.onCreate 30 31onCreate(): void 32 33Called when the application is created. 34 35**Atomic service API**: This API can be used in atomic services since API version 11. 36 37**System capability**: SystemCapability.Ability.AbilityRuntime.Core 38 39**Example** 40 41```ts 42import { AbilityStage } from '@kit.AbilityKit'; 43 44class MyAbilityStage extends AbilityStage { 45 onCreate() { 46 console.log('MyAbilityStage.onCreate is called'); 47 } 48} 49``` 50 51 52## AbilityStage.onAcceptWant 53 54onAcceptWant(want: Want): string 55 56Called when a specified ability is started. 57 58**Atomic service API**: This API can be used in atomic services since API version 11. 59 60**System capability**: SystemCapability.Ability.AbilityRuntime.Core 61 62**Parameters** 63 64| Name| Type| Mandatory| Description| 65| -------- | -------- | -------- | -------- | 66| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability, such as the ability name and bundle name.| 67 68**Return value** 69 70 | Type| Description| 71 | -------- | -------- | 72 | string | Ability ID. If the ability with this ID has been started, no new instance is created and the ability is placed at the top of the stack. Otherwise, a new instance is created and started.| 73 74**Example** 75 76```ts 77import { AbilityStage, Want } from '@kit.AbilityKit'; 78 79class MyAbilityStage extends AbilityStage { 80 onAcceptWant(want: Want) { 81 console.log('MyAbilityStage.onAcceptWant called'); 82 return 'com.example.test'; 83 } 84} 85``` 86 87## AbilityStage.onNewProcessRequest<sup>11+</sup> 88 89onNewProcessRequest(want: Want): string 90 91Called when the UIAbility is started in the specified process. 92 93**System capability**: SystemCapability.Ability.AbilityRuntime.Core 94 95**Parameters** 96 97| Name| Type| Mandatory| Description| 98| -------- | -------- | -------- | -------- | 99| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability, such as the ability name and bundle name.| 100 101**Return value** 102 103| Type| Description| 104| -------- | -------- | 105| string | Custom process identifier. If the process with this identifier has been created, the ability runs in the process. Otherwise, a new process is created and the ability runs in it.| 106 107**Example** 108 109```ts 110import { AbilityStage, Want } from '@kit.AbilityKit'; 111 112class MyAbilityStage extends AbilityStage { 113 onNewProcessRequest(want: Want) { 114 console.log('MyAbilityStage.onNewProcessRequest called'); 115 return 'com.example.test'; 116 } 117} 118``` 119 120 121## AbilityStage.onConfigurationUpdate 122 123onConfigurationUpdate(newConfig: Configuration): void 124 125Called when the global configuration is updated. 126 127**Atomic service API**: This API can be used in atomic services since API version 11. 128 129**System capability**: SystemCapability.Ability.AbilityRuntime.Core 130 131**Parameters** 132 133 | Name| Type| Mandatory| Description| 134 | -------- | -------- | -------- | -------- | 135 | newConfig | [Configuration](js-apis-app-ability-configuration.md) | Yes| Callback invoked when the global configuration is updated. The global configuration indicates the configuration of the environment where the application is running and includes the language and color mode.| 136 137**Example** 138 139```ts 140import { AbilityStage, Configuration } from '@kit.AbilityKit'; 141 142class MyAbilityStage extends AbilityStage { 143 onConfigurationUpdate(config: Configuration) { 144 console.log(`onConfigurationUpdate, language: ${config.language}`); 145 } 146} 147``` 148 149## AbilityStage.onMemoryLevel 150 151onMemoryLevel(level: AbilityConstant.MemoryLevel): void 152 153Called when the system has decided to adjust the memory level. For example, this API can be used when there is not enough memory to run as many background processes as possible. 154 155**Atomic service API**: This API can be used in atomic services since API version 11. 156 157**System capability**: SystemCapability.Ability.AbilityRuntime.Core 158 159**Parameters** 160 161 | Name| Type| Mandatory| Description| 162 | -------- | -------- | -------- | -------- | 163 | level | [AbilityConstant.MemoryLevel](js-apis-app-ability-abilityConstant.md#memorylevel) | Yes| Memory level that indicates the memory usage status. When the specified memory level is reached, a callback will be invoked and the system will start adjustment.| 164 165**Example** 166 167```ts 168import { AbilityStage, AbilityConstant } from '@kit.AbilityKit'; 169 170class MyAbilityStage extends AbilityStage { 171 onMemoryLevel(level: AbilityConstant.MemoryLevel) { 172 console.log(`onMemoryLevel, level: ${JSON.stringify(level)}`); 173 } 174} 175``` 176 177## AbilityStage.context 178 179context: AbilityStageContext 180 181Defines the context of **AbilityStage**. 182 183**Atomic service API**: This API can be used in atomic services since API version 11. 184 185**System capability**: SystemCapability.Ability.AbilityRuntime.Core 186 187| Name | Type | Description | 188| ----------- | --------------------------- | ------------------------------------------------------------ | 189| context | [AbilityStageContext](js-apis-inner-application-abilityStageContext.md) | The context is obtained in the callback invoked when initialization is performed during ability startup.| 190 191**Example** 192 193```ts 194import { AbilityStage } from '@kit.AbilityKit'; 195 196export default class MyAbilityStage extends AbilityStage { 197 onCreate() { 198 let abilityStageContext = this.context; 199 } 200} 201``` 202 203## AbilityStage.onDestroy<sup>12+<sup> 204 205onDestroy(): void 206 207Called when the application is destroyed. This API is called during the normal lifecycle. If the application exits abnormally or is terminated, this API is not called. 208 209**Atomic service API**: This API can be used in atomic services since API version 12. 210 211**System capability**: SystemCapability.Ability.AbilityRuntime.Core 212 213**Example** 214 215```ts 216import { AbilityStage } from '@kit.AbilityKit'; 217 218class MyAbilityStage extends AbilityStage { 219 onDestroy() { 220 console.log('MyAbilityStage.onDestroy is called'); 221 } 222} 223``` 224 225## AbilityStage.onPrepareTermination<sup>15+<sup> 226 227onPrepareTermination(): AbilityConstant.PrepareTermination 228 229Called when the application is closed by the user, allowing the user to choose between immediate termination or cancellation. Currently, this API takes effect only on 2-in-1 devices. 230 231> **NOTE** 232> 233> - This API is called only when the application exits normally. It is not called if the application is forcibly closed. 234> 235> - This API is not executed when [AbilityStage.onPrepareTerminationAsync](#abilitystageonprepareterminationasync15) is implemented. 236 237**Required permissions**: ohos.permission.PREPARE_APP_TERMINATE 238 239**Atomic service API**: This API can be used in atomic services since API version 15. 240 241**System capability**: SystemCapability.Ability.AbilityRuntime.Core 242 243**Return value** 244 245| Type| Description| 246| -------- | -------- | 247| [AbilityConstant.PrepareTermination](js-apis-app-ability-abilityConstant.md#preparetermination15) | The user's choice.| 248 249**Example** 250 251```ts 252import { AbilityConstant, AbilityStage } from '@kit.AbilityKit'; 253 254class MyAbilityStage extends AbilityStage { 255 onPrepareTermination(): AbilityConstant.PrepareTermination { 256 console.info('MyAbilityStage.onPrepareTermination is called'); 257 return AbilityConstant.PrepareTermination.CANCEL; 258 } 259} 260``` 261 262## AbilityStage.onPrepareTerminationAsync<sup>15+<sup> 263 264onPrepareTerminationAsync(): Promise\<AbilityConstant.PrepareTermination> 265 266Called when the application is closed by the user, allowing the user to choose between immediate termination or cancellation. This API uses a promise to return the result. Currently, this API takes effect only on 2-in-1 devices. 267 268> **NOTE** 269> 270> - This API is called only when the application exits normally. It is not called if the application is forcibly closed. 271> 272> - If an asynchronous callback crashes, it will be handled as a timeout. If the application does not respond within 10 seconds, it will be terminated forcibly. 273 274**Required permissions**: ohos.permission.PREPARE_APP_TERMINATE 275 276**Atomic service API**: This API can be used in atomic services since API version 15. 277 278**System capability**: SystemCapability.Ability.AbilityRuntime.Core 279 280**Return value** 281 282| Type| Description| 283| -------- | -------- | 284| Promise\<[AbilityConstant.PrepareTermination](js-apis-app-ability-abilityConstant.md#preparetermination15)> | Promise used to return the user's choice.| 285 286**Example** 287 288```ts 289import { AbilityConstant, AbilityStage } from '@kit.AbilityKit'; 290 291class MyAbilityStage extends AbilityStage { 292 async onPrepareTerminationAsync(): Promise<AbilityConstant.PrepareTermination> { 293 await new Promise<AbilityConstant.PrepareTermination>((res, rej) => { 294 setTimeout(res, 3000); // Execute the operation after 3 seconds. 295 }); 296 return AbilityConstant.PrepareTermination.CANCEL; 297 } 298} 299``` 300