1# @ohos.app.ability.AbilityStage (Component Manager) 2 3<!--Kit: Ability Kit--> 4<!--Subsystem: Ability--> 5<!--Owner: @zexin_c--> 6<!--Designer: @li-weifeng2--> 7<!--Tester: @lixueqing513--> 8<!--Adviser: @huipeizi--> 9 10AbilityStage is a [module](../../../application-dev/quick-start/application-package-overview.md#multi-module-design-mechanism)-level component manager. It is used for initializing operations such as resource preloading and thread creation at the module level, as well as maintaining the application state under the module. An AbilityStage instance corresponds to a module. 11 12When the [HAP](../../../application-dev/quick-start/hap-package.md) or [HSP](../../../application-dev/quick-start/in-app-hsp.md) of an application is first loaded, an AbilityStage instance is created. If a module contains both AbilityStage and other components (like UIAbility or ExtensionAbility), the AbilityStage instance is created before the other component instances. 13 14An AbilityStage has the lifecycle callbacks [onCreate()](#oncreate) and [onDestroy()](#ondestroy12), and the event callbacks [onAcceptWant()](#onacceptwant), [onConfigurationUpdate()](#onconfigurationupdate), and [onMemoryLevel()](#onmemorylevel). 15 16> **NOTE** 17> 18> 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. 19> 20> The APIs of this module can be used only in the stage model. 21 22## Modules to Import 23 24```ts 25import { AbilityStage } from '@kit.AbilityKit'; 26``` 27 28## AbilityStage 29 30### Properties 31 32**Atomic service API**: This API can be used in atomic services since API version 11. 33 34**System capability**: SystemCapability.Ability.AbilityRuntime.Core 35 36| Name| Type| Read-Only| Optional| Description| 37| -------- | -------- | -------- | -------- | -------- | 38| context | [AbilityStageContext](js-apis-inner-application-abilityStageContext.md) | No| No| Context of an AbilityStage.| 39 40### onCreate 41 42onCreate(): void 43 44Called when an AbilityStage instance is created. Such an instance is automatically created by the system before it loads the first Ability instance of the module. 45 46You can initialize the module (for example, preload resources or create threads) in this callback. This API returns the result synchronously and does not support asynchronous callbacks. 47 48**Atomic service API**: This API can be used in atomic services since API version 11. 49 50**System capability**: SystemCapability.Ability.AbilityRuntime.Core 51 52**Example** 53 54```ts 55import { AbilityStage } from '@kit.AbilityKit'; 56 57export default class MyAbilityStage extends AbilityStage { 58 onCreate() { 59 console.log('MyAbilityStage.onCreate is called'); 60 } 61} 62``` 63 64 65### onAcceptWant 66 67onAcceptWant(want: Want): string 68 69Called when a UIAbility with the launch mode set to [specified](../../application-models/uiability-launch-type.md#specified) is launched. This API returns a string representing the unique ID of the UIAbility instance. This API returns the result synchronously and does not support asynchronous callbacks. 70 71If a UIAbility instance with the same ID already exists in the system, that instance is reused. Otherwise, a new instance is created. 72 73> **NOTE** 74> 75> Starting from API version 20, this callback is not triggered when [AbilityStage.onAcceptWantAsync](#onacceptwantasync20) is implemented. 76 77**Atomic service API**: This API can be used in atomic services since API version 11. 78 79**System capability**: SystemCapability.Ability.AbilityRuntime.Core 80 81**Parameters** 82 83| Name| Type| Mandatory| Description| 84| -------- | -------- | -------- | -------- | 85| want | [Want](js-apis-app-ability-want.md) | Yes| Want type parameter that includes the launch parameters provided by the caller, such as the ability name and bundle name.| 86 87**Return value** 88 89| Type| Description| 90| -------- | -------- | 91| string | ID of the UIAbility. If a UIAbility with the same ID has been launched, that UIAbility is reused. Otherwise, a new instance is created and launched.| 92 93**Example** 94 95 96```ts 97import { AbilityStage, Want } from '@kit.AbilityKit'; 98 99export default class MyAbilityStage extends AbilityStage { 100 onAcceptWant(want: Want) { 101 console.log('MyAbilityStage.onAcceptWant called'); 102 return 'com.example.test'; 103 } 104} 105``` 106 107### onNewProcessRequest<sup>11+</sup> 108 109onNewProcessRequest(want: Want): string 110 111Called when a UIAbility or UIExtensionAbility, which is configured to run in an independent process (with **isolationProcess** set to **true** in the [module.json5](../../quick-start/module-configuration-file.md) file), is launched. This API returns a string representing the unique process ID. This API returns the result synchronously and does not support asynchronous callbacks. 112 113If the application already has a process with the same ID, the UIAbility or UIExtensionAbility runs in that process. Otherwise, a new process is created. 114 115If you implement both **onNewProcessRequest** and [onAcceptWant](#onacceptwant), the system first invokes the **onNewProcessRequest** callback, and then the **onAcceptWant** callback. 116 117<!--Del--> 118The **isolationProcess** field can be set to **true** in the [module.json5](../../quick-start/module-configuration-file.md) file, but only for the UIExtensionAbility of the sys/commonUI type. 119<!--DelEnd--> 120 121This API takes effect only on 2-in-1 devices and tablets. 122 123> **NOTE** 124> 125> - In API version 19 and earlier, only a UIAbility can be launched in the specified process. Starting from API version 20, a UIExtensionAbility can also be launched in the specified process. 126> - Starting from API version 20, this callback is not executed when [AbilityStage.onNewProcessRequestAsync](#onnewprocessrequestasync20) is implemented. 127 128**System capability**: SystemCapability.Ability.AbilityRuntime.Core 129 130 131**Parameters** 132 133| Name| Type| Mandatory| Description| 134| -------- | -------- | -------- | -------- | 135| want | [Want](js-apis-app-ability-want.md) | Yes| Want type parameter that includes the launch parameters provided by the caller, such as the UIAbility or UIExtensionAbility name and bundle name.| 136 137**Return value** 138 139| Type| Description| 140| -------- | -------- | 141| 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.| 142 143**Example** 144 145```ts 146import { AbilityStage, Want } from '@kit.AbilityKit'; 147 148export default class MyAbilityStage extends AbilityStage { 149 onNewProcessRequest(want: Want) { 150 console.log('MyAbilityStage.onNewProcessRequest called'); 151 return 'com.example.test'; 152 } 153} 154``` 155 156 157### onConfigurationUpdate 158 159onConfigurationUpdate(newConfig: Configuration): void 160 161Called when the system global configuration (such as the system language and dark/light color mode) changes. All the configuration items are defined in the [Configuration](../../../application-dev/reference/apis-ability-kit/js-apis-app-ability-configuration.md) class. This API returns the result synchronously and does not support asynchronous callbacks. 162 163**Atomic service API**: This API can be used in atomic services since API version 11. 164 165**System capability**: SystemCapability.Ability.AbilityRuntime.Core 166 167**Parameters** 168 169 | Name| Type| Mandatory| Description| 170 | -------- | -------- | -------- | -------- | 171 | 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.| 172 173**Example** 174 175```ts 176import { AbilityStage, Configuration } from '@kit.AbilityKit'; 177 178export default class MyAbilityStage extends AbilityStage { 179 onConfigurationUpdate(config: Configuration) { 180 console.log(`MyAbilityStage.onConfigurationUpdate, language: ${config.language}`); 181 } 182} 183``` 184 185### onMemoryLevel 186 187onMemoryLevel(level: AbilityConstant.MemoryLevel): void 188 189Listens for changes in the system memory level status. Called when the available memory of the entire device changes to a specified level. You can implement this callback to promptly release non-essential resources (such as cached data or temporary objects) upon receiving a memory shortage event, thereby preventing the application process from being forcibly terminated by the system. 190 191This API returns the result synchronously and does not support asynchronous callbacks. 192 193**Atomic service API**: This API can be used in atomic services since API version 11. 194 195**System capability**: SystemCapability.Ability.AbilityRuntime.Core 196 197**Parameters** 198 199 | Name| Type| Mandatory| Description| 200 | -------- | -------- | -------- | -------- | 201 | 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.<br>**NOTE**<br>The trigger conditions may differ across various devices. For example, on a standard device with 12 GB of memory:<br>- A callback with value 0 is triggered when available memory drops between 1700 MB and 1800 MB.<br>- A callback with value 1 is triggered when available memory drops between 1600 MB and 1700 MB.<br>- A callback with value 2 is triggered when available memory falls below 1600 MB.| 202 203**Example** 204 205```ts 206import { AbilityStage, AbilityConstant } from '@kit.AbilityKit'; 207 208export default class MyAbilityStage extends AbilityStage { 209 onMemoryLevel(level: AbilityConstant.MemoryLevel) { 210 console.log(`MyAbilityStage.onMemoryLevel, level: ${JSON.stringify(level)}`); 211 } 212} 213``` 214 215### onDestroy<sup>12+<sup> 216 217onDestroy(): void 218 219Called when the last Ability instance of the corresponding module exits. 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. 220 221**Atomic service API**: This API can be used in atomic services since API version 12. 222 223**System capability**: SystemCapability.Ability.AbilityRuntime.Core 224 225**Example** 226 227```ts 228import { AbilityStage } from '@kit.AbilityKit'; 229 230export default class MyAbilityStage extends AbilityStage { 231 onDestroy() { 232 console.log('MyAbilityStage.onDestroy is called'); 233 } 234} 235``` 236 237### onPrepareTermination<sup>15+<sup> 238 239onPrepareTermination(): AbilityConstant.PrepareTermination 240 241Called 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. 242 243> **NOTE** 244> 245> - Starting from API version 15, this API takes effect only on 2-in-1 devices. Starting from API version 19, it takes effect on tablets. 246> 247> - The API is called only when the application exits under normal circumstances (for example, when the application is closed through the doc bar or tray, or when the application shuts down along with the device). It will not be called if the application is terminated forcibly. 248> 249> - This API is not executed when [AbilityStage.onPrepareTerminationAsync](#onprepareterminationasync15) is implemented. 250 251**Required permissions**: ohos.permission.PREPARE_APP_TERMINATE 252 253**Atomic service API**: This API can be used in atomic services since API version 15. 254 255**System capability**: SystemCapability.Ability.AbilityRuntime.Core 256 257 258**Return value** 259 260| Type| Description| 261| -------- | -------- | 262| [AbilityConstant.PrepareTermination](js-apis-app-ability-abilityConstant.md#preparetermination15) | The user's choice.| 263 264**Example** 265 266```ts 267import { AbilityConstant, AbilityStage } from '@kit.AbilityKit'; 268 269export default class MyAbilityStage extends AbilityStage { 270 onPrepareTermination(): AbilityConstant.PrepareTermination { 271 console.info('MyAbilityStage.onPrepareTermination is called'); 272 return AbilityConstant.PrepareTermination.CANCEL; 273 } 274} 275``` 276 277### onPrepareTerminationAsync<sup>15+<sup> 278 279onPrepareTerminationAsync(): Promise\<AbilityConstant.PrepareTermination> 280 281Called 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. 282 283> **NOTE** 284> 285> - Starting from API version 15, this API takes effect only on 2-in-1 devices. Starting from API version 19, it takes effect on tablets. 286> 287> - The API is called only when the application exits under normal circumstances (for example, when the application is closed through the doc bar or tray, or when the application shuts down along with the device). It will not be called if the application is terminated forcibly. 288> 289> - 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. 290 291**Required permissions**: ohos.permission.PREPARE_APP_TERMINATE 292 293**Atomic service API**: This API can be used in atomic services since API version 15. 294 295**System capability**: SystemCapability.Ability.AbilityRuntime.Core 296 297 298**Return value** 299 300| Type| Description| 301| -------- | -------- | 302| Promise\<[AbilityConstant.PrepareTermination](js-apis-app-ability-abilityConstant.md#preparetermination15)> | Promise used to return the user's choice.| 303 304**Example** 305 306```ts 307import { AbilityConstant, AbilityStage } from '@kit.AbilityKit'; 308 309export default class MyAbilityStage extends AbilityStage { 310 async onPrepareTerminationAsync(): Promise<AbilityConstant.PrepareTermination> { 311 await new Promise<AbilityConstant.PrepareTermination>((res, rej) => { 312 setTimeout(res, 3000); // Execute the operation after 3 seconds. 313 }); 314 return AbilityConstant.PrepareTermination.CANCEL; 315 } 316} 317``` 318 319### onAcceptWantAsync<sup>20+</sup> 320 321onAcceptWantAsync(want: Want): Promise\<string\> 322 323Called when a UIAbility with the launch mode set to [specified](../../application-models/uiability-launch-type.md#specified) is launched. This API returns a string representing the unique ID of the UIAbility instance. This API uses a promise to return the result. 324 325If a UIAbility instance with the same ID already exists in the system, that instance is reused. Otherwise, a new instance is created. 326 327**Atomic service API**: This API can be used in atomic services since API version 20. 328 329**System capability**: SystemCapability.Ability.AbilityRuntime.Core 330 331**Parameters** 332 333| Name| Type| Mandatory| Description| 334| -------- | -------- | -------- | -------- | 335| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target UIAbility, such as the UIAbility name and bundle name.| 336 337**Return value** 338 339 | Type| Description| 340 | -------- | -------- | 341 | Promise\<string\> | Promise used to return a string that uniquely identifies the UIAbility instance launched. If a UIAbility instance with the same ID already exists in the system, that instance is reused. Otherwise, a new instance is created.| 342 343**Example** 344 345```ts 346import { AbilityStage } from '@kit.AbilityKit'; 347 348class MyAbilityStage extends AbilityStage { 349 async onAcceptWantAsync(): Promise<string> { 350 await new Promise<string>((res, rej) => { 351 setTimeout(res, 1000); // Execute the operation after 1 second. 352 }); 353 return 'default'; 354 } 355} 356``` 357 358### onNewProcessRequestAsync<sup>20+</sup> 359 360onNewProcessRequestAsync(want: Want): Promise\<string\> 361 362Called when a UIAbility or UIExtensionAbility, which is configured to run in an independent process (with **isolationProcess** set to **true** in the [module.json5](../../quick-start/module-configuration-file.md) file), is launched. This API returns a string representing the unique process ID. This API uses a promise to return the result. 363 364If the application already has a process with the same ID, the UIAbility or UIExtensionAbility runs in that process. Otherwise, a new process is created. 365 366<!--Del--> 367The **isolationProcess** field can be set to **true** in the [module.json5](../../quick-start/module-configuration-file.md) file, but only for the UIExtensionAbility of the sys/commonUI type. 368<!--DelEnd--> 369 370This API takes effect only on 2-in-1 devices and tablets. 371 372**Atomic service API**: This API can be used in atomic services since API version 20. 373 374**System capability**: SystemCapability.Ability.AbilityRuntime.Core 375 376 377**Parameters** 378 379| Name| Type| Mandatory| Description| 380| -------- | -------- | -------- | -------- | 381| want | [Want](js-apis-app-ability-want.md) | Yes| Want type parameter that includes the launch parameters provided by the caller, such as the UIAbility or UIExtensionAbility name and bundle name.| 382 383**Return value** 384 385| Type| Description| 386| -------- | -------- | 387| Promise\<string\> | Promise used to return a string representing the process ID. If the application already has a process with the same ID, the UIAbility or UIExtensionAbility runs in that process. Otherwise, a new process is created.| 388 389**Example** 390 391```ts 392import { AbilityStage } from '@kit.AbilityKit'; 393 394class MyAbilityStage extends AbilityStage { 395 async onNewProcessRequestAsync(): Promise<string> { 396 await new Promise<string>((res, rej) => { 397 setTimeout(res, 1000); // Execute the operation after 1 second. 398 }); 399 return ''; 400 } 401} 402``` 403