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. This API returns the result synchronously and does not support asynchronous callbacks. 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. This API returns the result synchronously and does not support asynchronous callbacks. 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. This API returns the result synchronously and does not support asynchronous callbacks. 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. This API returns the result synchronously and does not support asynchronous callbacks. 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. This API returns the result synchronously and does not support asynchronous callbacks. 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. This API returns the result synchronously and does not support asynchronous callbacks. 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. This API returns the result synchronously and does not support asynchronous callbacks. 230 231Currently, this API takes effect only on 2-in-1 devices. 232 233> **NOTE** 234> 235> - This API is called only when the application exits normally. It is not called if the application is forcibly closed. 236> 237> - This API is not executed when [AbilityStage.onPrepareTerminationAsync](#abilitystageonprepareterminationasync15) is implemented. 238 239**Required permissions**: ohos.permission.PREPARE_APP_TERMINATE 240 241**Atomic service API**: This API can be used in atomic services since API version 15. 242 243**System capability**: SystemCapability.Ability.AbilityRuntime.Core 244 245**Return value** 246 247| Type| Description| 248| -------- | -------- | 249| [AbilityConstant.PrepareTermination](js-apis-app-ability-abilityConstant.md#preparetermination15) | The user's choice.| 250 251**Example** 252 253```ts 254import { AbilityConstant, AbilityStage } from '@kit.AbilityKit'; 255 256class MyAbilityStage extends AbilityStage { 257 onPrepareTermination(): AbilityConstant.PrepareTermination { 258 console.info('MyAbilityStage.onPrepareTermination is called'); 259 return AbilityConstant.PrepareTermination.CANCEL; 260 } 261} 262``` 263 264## AbilityStage.onPrepareTerminationAsync<sup>15+<sup> 265 266onPrepareTerminationAsync(): Promise\<AbilityConstant.PrepareTermination> 267 268Called 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. 269 270> **NOTE** 271> 272> - This API is called only when the application exits normally. It is not called if the application is forcibly closed. 273> 274> - 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. 275 276**Required permissions**: ohos.permission.PREPARE_APP_TERMINATE 277 278**Atomic service API**: This API can be used in atomic services since API version 15. 279 280**System capability**: SystemCapability.Ability.AbilityRuntime.Core 281 282**Return value** 283 284| Type| Description| 285| -------- | -------- | 286| Promise\<[AbilityConstant.PrepareTermination](js-apis-app-ability-abilityConstant.md#preparetermination15)> | Promise used to return the user's choice.| 287 288**Example** 289 290```ts 291import { AbilityConstant, AbilityStage } from '@kit.AbilityKit'; 292 293class MyAbilityStage extends AbilityStage { 294 async onPrepareTerminationAsync(): Promise<AbilityConstant.PrepareTermination> { 295 await new Promise<AbilityConstant.PrepareTermination>((res, rej) => { 296 setTimeout(res, 3000); // Execute the operation after 3 seconds. 297 }); 298 return AbilityConstant.PrepareTermination.CANCEL; 299 } 300} 301``` 302