1# @ohos.app.ability.application (应用工具类) 2 3<!--Kit: Ability Kit--> 4<!--Subsystem: Ability--> 5<!--Owner: @li-weifeng2--> 6<!--Designer: @li-weifeng2--> 7<!--Tester: @lixueqing513--> 8<!--Adviser: @huipeizi--> 9 10开发者可以通过该模块管理和获取应用的上下文[Context](../../application-models/application-context-stage.md)，以及控制应用进程的状态。 11 12> **说明：** 13> 14> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15> 本模块接口仅可在Stage模型下使用。 16 17## 导入模块 18 19```ts 20import { application } from '@kit.AbilityKit'; 21``` 22 23## application.createModuleContext<sup>12+</sup> 24 25createModuleContext(context: Context, moduleName: string): Promise\<Context> 26 27创建指定模块的上下文。创建出的模块上下文中[resourceManager.Configuration](../apis-localization-kit/js-apis-resource-manager.md#configuration)资源继承自入参上下文，便于开发者获取[跨HAP/HSP包应用资源](../../quick-start/resource-categories-and-access.md#跨haphsp包应用资源)。 28 29**原子化服务API**：从API version 12开始，该接口支持在元服务中使用。 30 31**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 32 33**参数**： 34 35| 参数名 | 类型 | 必填 | 说明 | 36| --------- | ---------------------------------------- | ---- | -------------- | 37| context | [Context](js-apis-inner-application-context.md) | 是 | 表示应用上下文。 | 38| moduleName | string | 是 | 表示应用模块名。 | 39 40**返回值：** 41 42| 类型 | 说明 | 43| ------------------ | ------------------- | 44| Promise\<[Context](../../reference/apis-ability-kit/js-apis-inner-application-context.md)> | Promise对象。返回创建的Context。 | 45 46**错误码：** 47 48以下错误码详细介绍请参考[通用错误码说明文档](../errorcode-universal.md)。 49 50| 错误码ID | 错误信息 | 51| -------- | --------------- | 52| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 53 54**示例：** 55 56```ts 57import { AbilityConstant, UIAbility, application, common, Want } from '@kit.AbilityKit'; 58import { BusinessError } from '@kit.BasicServicesKit'; 59 60export default class EntryAbility extends UIAbility { 61 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 62 let moduleContext: common.Context; 63 try { 64 application.createModuleContext(this.context, 'entry').then((data: Context) => { 65 moduleContext = data; 66 console.info('createModuleContext success!'); 67 }).catch((error: BusinessError) => { 68 let code: number = (error as BusinessError).code; 69 let message: string = (error as BusinessError).message; 70 console.error(`createModuleContext failed, error.code: ${code}, error.message: ${message}`); 71 }); 72 } catch (error) { 73 let code: number = (error as BusinessError).code; 74 let message: string = (error as BusinessError).message; 75 console.error(`createModuleContext failed, error.code: ${code}, error.message: ${message}`); 76 } 77 } 78} 79``` 80 81## application.getApplicationContext<sup>14+</sup> 82 83getApplicationContext(): ApplicationContext 84 85获取应用上下文。开发者使用该接口时，无需依赖Context基类。 86 87**原子化服务API**：从API version 14开始，该接口支持在元服务中使用。 88 89**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 90 91**返回值：** 92 93| 类型 | 说明 | 94| ------------------------------------------------------------ | ------------------- | 95| [ApplicationContext](js-apis-inner-application-applicationContext.md) | 应用上下文。 | 96 97**错误码：** 98 99以下错误码详细介绍请参考[元能力子系统错误码](errorcode-ability.md)。 100 101| 错误码ID | 错误信息 | 102| -------- | --------------- | 103| 16000050 | Internal error. | 104 105**示例：** 106 107```ts 108import { AbilityConstant, UIAbility, application, Want } from '@kit.AbilityKit'; 109import { BusinessError } from '@kit.BasicServicesKit'; 110 111export default class EntryAbility extends UIAbility { 112 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 113 try { 114 let applicationContext = application.getApplicationContext(); 115 } catch (error) { 116 let code: number = (error as BusinessError).code; 117 let message: string = (error as BusinessError).message; 118 console.error(`getApplicationContext failed, error.code: ${code}, error.message: ${message}`); 119 } 120 } 121} 122``` 123 124## application.createPluginModuleContext<sup>19+</sup> 125 126createPluginModuleContext(context: Context, pluginBundleName: string, pluginModuleName: string): Promise\<Context> 127 128根据入参Context、指定的插件包名和插件模块名，创建本应用下插件的Context，用于获取插件的基本信息。使用Promise异步回调。 129 130**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 131 132**参数**： 133 134| 参数名 | 类型 | 必填 | 说明 | 135| --------- | ---------------------------------------- | ---- | -------------- | 136| context | [Context](js-apis-inner-application-context.md) | 是 | 表示应用上下文。 | 137| pluginBundleName | string | 是 | 表示应用的插件包名。 | 138| pluginModuleName | string | 是 | 表示应用的插件模块名。 | 139 140**返回值：** 141 142| 类型 | 说明 | 143| ------------------ | ------------------- | 144| Promise\<[Context](../../reference/apis-ability-kit/js-apis-inner-application-context.md)> | Promise对象。返回创建的Context。 | 145 146**示例：** 147 148```ts 149import { AbilityConstant, UIAbility, application, common, Want } from '@kit.AbilityKit'; 150import { BusinessError } from '@kit.BasicServicesKit'; 151 152export default class EntryAbility extends UIAbility { 153 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 154 let moduleContext: common.Context; 155 try { 156 application.createPluginModuleContext(this.context, 'com.example.pluginBundleName', 'pluginModuleName') 157 .then((data: Context) => { 158 moduleContext = data; 159 console.info('createPluginModuleContext success!'); 160 }) 161 .catch((error: BusinessError) => { 162 let code: number = (error as BusinessError).code; 163 let message: string = (error as BusinessError).message; 164 console.error(`createPluginModuleContext failed, error.code: ${code}, error.message: ${message}`); 165 }); 166 } catch (error) { 167 let code: number = (error as BusinessError).code; 168 let message: string = (error as BusinessError).message; 169 console.error(`createPluginModuleContext failed, error.code: ${code}, error.message: ${message}`); 170 } 171 } 172} 173``` 174 175## application.promoteCurrentToCandidateMasterProcess<sup>20+</sup> 176 177promoteCurrentToCandidateMasterProcess(insertToHead: boolean): Promise\<void> 178 179开发者可以调用该接口将当前进程放入[备选主控进程](../../application-models/ability-terminology.md#candidatemasterprocess备选主控进程)链表。使用Promise异步回调。 180 181当[主控进程](../../application-models/ability-terminology.md#masterprocess主控进程)销毁后，再次启动配置了isolationProcess为true的UIAbility/UIExtensionAbility组件时，系统会根据是否存在备选主控进程执行相应操作。 182 183- 如果存在备选主控进程，系统会将备选主控进程链表首节点的进程设置为主控进程，触发[onNewProcessRequest](js-apis-app-ability-abilityStage.md#onnewprocessrequest11)回调。 184- 如果不存在备选主控进程，系统会根据组件类型执行相应的操作。 185 - 对于UIAbility组件，系统将创建新的空进程作为主控进程。 186 - 对于UIExtensionAbility组件，系统会优先复用已有的UIExtensionAbility进程作为新的主控进程，无可用进程时则创建新的空进程作为主控进程。 187 188<!--Del--> 189> **说明：** 190> 191> 当前仅支持sys/commonUI类型的UIExtensionAbility组件在[module.json5配置文件](../../quick-start/module-configuration-file.md)中配置isolationProcess字段为true。 192<!--DelEnd--> 193 194**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 195 196**设备行为差异**：该接口在PC/2in1、Tablet中可正常调用，在其他设备类型中返回801错误码。 197 198**参数**： 199 200| 参数名 | 类型 | 必填 | 说明 | 201| --------- | ---------------------------------------- | ---- | -------------- | 202| insertToHead | boolean | 是 | 表示是否将当前进程放入备选主控进程链表的表头。true表示放入表头，false表示放入表尾。| 203 204**返回值：** 205 206| 类型 | 说明 | 207| ------------------ | ------------------- | 208|Promise\<void> | Promise对象。无返回结果。 | 209 210**错误码：** 211 212以下错误码详细介绍请参考[通用错误码说明文档](../errorcode-universal.md)和[元能力子系统错误码](./errorcode-ability.md)。 213 214| 错误码ID | 错误信息 | 215| -------- | --------------- | 216| 801 | Capability not supported.| 217| 16000115 | The current process is not running a component configured with "isolationProcess" and cannot be set as a candidate master process. | 218 219 220**示例：** 221 222```ts 223import { AbilityConstant, UIAbility, application, Want } from '@kit.AbilityKit'; 224import { BusinessError } from '@kit.BasicServicesKit'; 225 226export default class EntryAbility extends UIAbility { 227 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 228 try { 229 application.promoteCurrentToCandidateMasterProcess(true) 230 .then(() => { 231 console.info('promote succeed'); 232 }) 233 .catch((err: BusinessError) => { 234 console.error(`promote failed, code is ${err.code}, message is ${err.message}`); 235 }); 236 } catch (error) { 237 let code: number = (error as BusinessError).code; 238 let message: string = (error as BusinessError).message; 239 console.error(`promoteCurrentToCandidateMasterProcess failed, error.code: ${code}, error.message: ${message}`); 240 } 241 } 242} 243``` 244 245## application.demoteCurrentFromCandidateMasterProcess<sup>20+</sup> 246 247demoteCurrentFromCandidateMasterProcess(): Promise\<void> 248 249撤销当前进程的备选主控进程资格。使用Promise异步回调。 250 251**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 252 253**设备行为差异**：该接口在PC/2in1、Tablet中可正常调用，在其他设备类型中返回801错误码。 254 255**返回值：** 256 257| 类型 | 说明 | 258| ------------------ | ------------------- | 259|Promise\<void> | Promise对象。无返回结果。 | 260 261**错误码：** 262 263以下错误码详细介绍请参考[通用错误码说明文档](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 264 265| 错误码ID | 错误信息 | 266| -------- | --------------- | 267| 801 | Capability not supported.| 268| 16000116 | The current process is already a master process and does not support cancellation. | 269| 16000117 | The current process is not a candidate master process and does not support cancellation. | 270 271**示例：** 272 273```ts 274import { AbilityConstant, UIAbility, application, Want } from '@kit.AbilityKit'; 275import { BusinessError } from '@kit.BasicServicesKit'; 276 277export default class EntryAbility extends UIAbility { 278 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 279 try { 280 application.demoteCurrentFromCandidateMasterProcess() 281 .then(() => { 282 console.info('demote succeed'); 283 }) 284 .catch((err: BusinessError) => { 285 console.error(`demote failed, code is ${err.code}, message is ${err.message}`); 286 }); 287 } catch (error) { 288 let code: number = (error as BusinessError).code; 289 let message: string = (error as BusinessError).message; 290 console.error(`demoteCurrentFromCandidateMasterProcess failed, error.code: ${code}, error.message: ${message}`); 291 } 292 } 293} 294```