1# @ohos.app.ability.AbilityStage 组件管理器 2 3<!--Kit: Ability Kit--> 4<!--Subsystem: Ability--> 5<!--Owner: @zexin_c--> 6<!--Designer: @li-weifeng2--> 7<!--Tester: @lixueqing513--> 8<!--Adviser: @huipeizi--> 9 10AbilityStage是一个[Module](../../../application-dev/quick-start/application-package-overview.md#应用的多module设计机制)级别的组件管理器，用于进行Module级别的资源预加载、线程创建等初始化操作，以及维护Module下的应用状态。AbilityStage与Module一一对应，即一个Module拥有一个AbilityStage。 11 12应用的[HAP](../../../application-dev/quick-start/hap-package.md)/[HSP](../../../application-dev/quick-start/in-app-hsp.md)在首次加载时会创建一个AbilityStage实例。当一个Module中存在AbilityStage和其他组件（UIAbility/ExtensionAbility组件），AbilityStage实例会早于其他组件实例创建。 13 14AbilityStage拥有[onCreate()](#oncreate)、[onDestroy()](#ondestroy12)生命周期回调和[onAcceptWant()](#onacceptwant)、[onConfigurationUpdate()](#onconfigurationupdate)、[onMemoryLevel()](#onmemorylevel)事件回调等。 15 16> **说明：** 17> 18> 本模块首批接口从API version 9 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 19> 20> 本模块接口仅可在Stage模型下使用。 21 22## 导入模块 23 24```ts 25import { AbilityStage } from '@kit.AbilityKit'; 26``` 27 28## AbilityStage 29 30### 属性 31 32**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 33 34**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 35 36| 名称 | 类型 | 只读 | 可选 | 说明 | 37| -------- | -------- | -------- | -------- | -------- | 38| context | [AbilityStageContext](js-apis-inner-application-abilityStageContext.md) | 否 | 否 | AbilityStage上下文。 | 39 40### onCreate 41 42onCreate(): void 43 44在加载Module的第一个Ability实例前，系统会先创建对应的AbilityStage实例，并在AbilityStage创建完成后，自动触发该回调。 45 46开发者可以在该回调中执行Module的初始化操作（如资源预加载、线程创建等）。同步接口，不支持异步回调。 47 48**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 49 50**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 51 52**示例：** 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 69当启动模式配置为[specified](../../application-models/uiability-launch-type.md#specified启动模式)的UIAbility被拉起时，会触发该回调，并返回一个string作为待启动的UIAbility实例的唯一标识。同步接口，不支持异步回调。 70 71如果系统中已经有相同标识的UIAbility实例存在，则复用已有实例，否则创建新的实例。 72 73> **说明：** 74> 75> 从API version 20开始，当[AbilityStage.onAcceptWantAsync](#onacceptwantasync20)实现时，本回调函数将不会被触发。 76 77**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 78 79**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 80 81**参数：** 82 83| 参数名 | 类型 | 必填 | 说明 | 84| -------- | -------- | -------- | -------- | 85| want | [Want](js-apis-app-ability-want.md) | 是 | Want类型参数，此处表示调用方传入的启动参数，如Ability名称，Bundle名称等。 | 86 87**返回值：** 88 89| 类型 | 说明 | 90| -------- | -------- | 91| string | 返回开发者自定义的UIAbility标识。如果已经启动了相同标识的UIAbility，则复用该UIAbility，否则创建新的实例并启动。 | 92 93**示例：** 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 111如果UIAbility或UIExtensionAbility配置了在独立进程中运行（即[module.json5配置文件](../../quick-start/module-configuration-file.md)中UIAbility或UIExtensionAbility的isolationProcess字段取值为true），当该UIAbility或UIExtensionAbility被拉起时，会触发该回调，并返回一个string作为进程唯一标识。同步接口，不支持异步回调。 112 113如果该应用已有相同标识的进程存在，则待启动的UIAbility或UIExtensionAbility运行在此进程中，否则创建新的进程。 114 115如果开发者同时实现onNewProcessRequest和[onAcceptWant](#onacceptwant)，将先收到onNewProcessRequest回调，再收到onAcceptWant回调。 116 117<!--Del--> 118仅支持sys/commonUI类型的UIExtensionAbility组件在[module.json5配置文件](../../quick-start/module-configuration-file.md)配置文件中配置isolationProcess字段为true。 119<!--DelEnd--> 120 121> **说明：** 122> 123> - 在API version 19及之前版本，仅支持在指定进程中启动UIAbility。从API version 20开始，新增支持在指定进程中启动UIExtensionAbility。 124> - 从API version 20开始，当[AbilityStage.onNewProcessRequestAsync](#onnewprocessrequestasync20)实现时，本回调函数将不执行。 125 126**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 127 128**设备行为差异**：该接口仅在2in1和Tablet设备中可正常执行回调，在其他设备上不执行回调。 129 130**参数：** 131 132| 参数名 | 类型 | 必填 | 说明 | 133| -------- | -------- | -------- | -------- | 134| want | [Want](js-apis-app-ability-want.md) | 是 | Want类型参数，此处表示调用方传入的启动参数，如UIAbility或UIExtensionAbility名称、Bundle名称等。 | 135 136**返回值：** 137 138| 类型 | 说明 | 139| -------- | -------- | 140| string | 返回一个由开发者自行决定的进程字符串标识，如果之前此标识对应的进程已被创建，就让ability在此进程中运行，否则创建新的进程。 | 141 142**示例：** 143 144```ts 145import { AbilityStage, Want } from '@kit.AbilityKit'; 146 147export default class MyAbilityStage extends AbilityStage { 148 onNewProcessRequest(want: Want) { 149 console.log('MyAbilityStage.onNewProcessRequest called'); 150 return 'com.example.test'; 151 } 152} 153``` 154 155 156### onConfigurationUpdate 157 158onConfigurationUpdate(newConfig: Configuration): void 159 160当系统全局配置（例如系统语言、深浅色等）发生变更时，会触发该回调。配置项均定义在[Configuration](../../../application-dev/reference/apis-ability-kit/js-apis-app-ability-configuration.md)类中。同步接口，不支持异步回调。 161 162**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 163 164**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 165 166**参数：** 167 168 | 参数名 | 类型 | 必填 | 说明 | 169 | -------- | -------- | -------- | -------- | 170 | newConfig | [Configuration](js-apis-app-ability-configuration.md) | 是 | 发生全局配置变更时触发回调，当前全局配置包括系统语言、深浅色模式。 | 171 172**示例：** 173 174```ts 175import { AbilityStage, Configuration } from '@kit.AbilityKit'; 176 177export default class MyAbilityStage extends AbilityStage { 178 onConfigurationUpdate(config: Configuration) { 179 console.log(`MyAbilityStage.onConfigurationUpdate, language: ${config.language}`); 180 } 181} 182``` 183 184### onMemoryLevel 185 186onMemoryLevel(level: AbilityConstant.MemoryLevel): void 187 188该接口用于监听系统内存状态变化。当整机可用内存变化到指定程度时，系统会触发该回调。开发者可通过实现此接口，在收到内存紧张事件时，及时释放非必要资源（如缓存数据、临时对象等），以避免应用进程被系统强制终止。 189 190同步接口，不支持异步回调。 191 192**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 193 194**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 195 196**参数：** 197 198 | 参数名 | 类型 | 必填 | 说明 | 199 | -------- | -------- | -------- | -------- | 200 | level | [AbilityConstant.MemoryLevel](js-apis-app-ability-abilityConstant.md#memorylevel) | 是 | 回调返回内存微调级别，显示当前内存使用状态。<br>**说明：**<br>不同产品的触发条件可能存在差异。以12G内存的标准设备为例：<br>- 当可用内存下降至1700M~1800M时，会触发取值为0的onMemoryLevel回调。<br>- 当可用内存下降至1600M~1700M时，会触发取值为1的onMemoryLevel回调。<br>- 当可用内存下降至1600M以下时，会触发取值为2的onMemoryLevel回调。| 201 202**示例：** 203 204```ts 205import { AbilityStage, AbilityConstant } from '@kit.AbilityKit'; 206 207export default class MyAbilityStage extends AbilityStage { 208 onMemoryLevel(level: AbilityConstant.MemoryLevel) { 209 console.log(`MyAbilityStage.onMemoryLevel, level: ${JSON.stringify(level)}`); 210 } 211} 212``` 213 214### onDestroy<sup>12+<sup> 215 216onDestroy(): void 217 218在对应Module的最后一个Ability实例退出后会触发该回调。此方法将在正常的调度生命周期中调用，当应用程序异常退出或被终止时，将不会调用此方法。同步接口，不支持异步回调。 219 220**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 221 222**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 223 224**示例：** 225 226```ts 227import { AbilityStage } from '@kit.AbilityKit'; 228 229export default class MyAbilityStage extends AbilityStage { 230 onDestroy() { 231 console.log('MyAbilityStage.onDestroy is called'); 232 } 233} 234``` 235 236### onPrepareTermination<sup>15+<sup> 237 238onPrepareTermination(): AbilityConstant.PrepareTermination 239 240当应用被用户关闭时调用，可用于询问用户选择立即执行操作还是取消操作。同步接口，不支持异步回调。 241 242> **说明：** 243> 244> - 仅当应用正常退出（例如，通过doc栏/托盘关闭应用，或者应用随设备关机而退出）时会调用该接口。如果应用被强制关闭，则不会调用该接口。 245> 246> - 当[AbilityStage.onPrepareTerminationAsync](#onprepareterminationasync15)实现时，本回调函数将不执行。 247 248**需要权限**：ohos.permission.PREPARE_APP_TERMINATE 249 250**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 251 252**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 253 254**设备行为差异**： 255- 从API version 15开始，该接口仅在2in1设备中可正常执行回调，在其他设备上不执行回调。 256- 从API version 19开始，该接口仅在2in1和Tablet设备中可正常执行回调，在其他设备上不执行回调。 257 258**返回值：** 259 260| 类型 | 说明 | 261| -------- | -------- | 262| [AbilityConstant.PrepareTermination](js-apis-app-ability-abilityConstant.md#preparetermination15) | 用于返回用户的选择结果。 | 263 264**示例：** 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 281当应用被用户关闭时调用，可用于询问用户选择立即执行操作还是取消操作。使用Promise异步回调。 282 283> **说明：** 284> 285> - 仅当应用正常退出（例如，通过doc栏/托盘关闭应用，或者应用随设备关机而退出）时会调用该接口。如果应用被强制关闭，则不会调用该接口。 286> 287> - 若异步回调内发生crash，按超时处理，执行等待超过10秒未响应，应用将被强制关闭。 288 289**需要权限**：ohos.permission.PREPARE_APP_TERMINATE 290 291**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 292 293**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 294 295**设备行为差异**： 296- 从API version 15开始，该接口仅在2in1设备中可正常执行回调，在其他设备上不执行回调。 297- 从API version 19开始，该接口仅在2in1和Tablet设备中可正常执行回调，在其他设备上不执行回调。 298 299**返回值：** 300 301| 类型 | 说明 | 302| -------- | -------- | 303| Promise\<[AbilityConstant.PrepareTermination](js-apis-app-ability-abilityConstant.md#preparetermination15)> | Promise对象，返回用户的选择结果。 | 304 305**示例：** 306 307```ts 308import { AbilityConstant, AbilityStage } from '@kit.AbilityKit'; 309 310export default class MyAbilityStage extends AbilityStage { 311 async onPrepareTerminationAsync(): Promise<AbilityConstant.PrepareTermination> { 312 await new Promise<AbilityConstant.PrepareTermination>((res, rej) => { 313 setTimeout(res, 3000); // 延时3秒后执行 314 }); 315 return AbilityConstant.PrepareTermination.CANCEL; 316 } 317} 318``` 319 320### onAcceptWantAsync<sup>20+</sup> 321 322onAcceptWantAsync(want: Want): Promise\<string\> 323 324当启动模式配置为[specified](../../application-models/uiability-launch-type.md#specified启动模式)的UIAbility被拉起时，会触发该回调，并返回一个string作为待启动的UIAbility实例的唯一标识。使用Promise异步回调。 325 326如果系统中已经有相同标识的UIAbility实例存在，则复用已有实例，否则创建新的实例。 327 328**原子化服务API**：从API version 20开始，该接口支持在原子化服务中使用。 329 330**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 331 332**参数：** 333 334| 参数名 | 类型 | 必填 | 说明 | 335| -------- | -------- | -------- | -------- | 336| want | [Want](js-apis-app-ability-want.md) | 是 | Want类型参数，传入需要启动的UIAbility的信息，如UIAbility名称、Bundle名称等。 | 337 338**返回值：** 339 340 | 类型 | 说明 | 341 | -------- | -------- | 342 | Promise\<string\> | Promise对象，返回一个string作为待启动的UIAbility实例的唯一标识。如果系统中已经有该标识的UIAbility实例存在，则复用已有实例，否则创建新的实例。 | 343 344**示例：** 345 346```ts 347import { AbilityStage } from '@kit.AbilityKit'; 348 349class MyAbilityStage extends AbilityStage { 350 async onAcceptWantAsync(): Promise<string> { 351 await new Promise<string>((res, rej) => { 352 setTimeout(res, 1000); // 延时1秒后执行 353 }); 354 return 'default'; 355 } 356} 357``` 358 359### onNewProcessRequestAsync<sup>20+</sup> 360 361onNewProcessRequestAsync(want: Want): Promise\<string\> 362 363如果UIAbility或UIExtensionAbility配置了在独立进程中运行（即[module.json5配置文件](../../quick-start/module-configuration-file.md)中UIAbility或UIExtensionAbility的isolationProcess字段取值为true），当该UIAbility或UIExtensionAbility被拉起时，会触发该回调，并返回一个string作为进程唯一标识。使用Promise异步回调。 364 365如果该应用已有相同标识的进程存在，则待启动的UIAbility或UIExtensionAbility运行在此进程中，否则创建新的进程。 366 367<!--Del--> 368仅支持sys/commonUI类型的UIExtensionAbility组件在[module.json5配置文件](../../quick-start/module-configuration-file.md)中配置isolationProcess字段为true。 369<!--DelEnd--> 370 371**原子化服务API**：从API version 20开始，该接口支持在原子化服务中使用。 372 373**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 374 375**设备行为差异**：该接口仅在2in1和Tablet设备中可正常执行回调，在其他设备上不执行回调。 376 377**参数：** 378 379| 参数名 | 类型 | 必填 | 说明 | 380| -------- | -------- | -------- | -------- | 381| want | [Want](js-apis-app-ability-want.md) | 是 | Want类型参数，此处表示调用方传入的启动参数，如UIAbility或UIExtensionAbility名称、Bundle名称等。 | 382 383**返回值：** 384 385| 类型 | 说明 | 386| -------- | -------- | 387| Promise\<string\> | Promise对象，返回一个由开发者自定义的进程字符串标识。如果该应用已有相同标识的进程存在，则UIAbility或UIExtensionAbility在此进程中运行，否则创建新的进程。 | 388 389**示例：** 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); // 延时1秒后执行 398 }); 399 return ''; 400 } 401} 402``` 403