1# UIExtensionContext (系统接口) 2 3<!--Kit: Ability Kit--> 4<!--Subsystem: Ability--> 5<!--Owner: @zhangyafei-echo--> 6<!--Designer: @li-weifeng2--> 7<!--Tester: @lixueqing513--> 8<!--Adviser: @huipeizi--> 9 10UIExtensionContext是[UIExtensionAbility](js-apis-app-ability-uiExtensionAbility.md)的上下文环境，继承自[ExtensionContext](js-apis-inner-application-extensionContext.md)，提供UIExtensionAbility的相关配置信息以及操作UIAbility的方法，如启动UIAbility等。 11 12> **说明：** 13> 14> - 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15> - 本模块接口仅可在Stage模型下使用。 16> - 本模块接口为系统接口。 17 18## 导入模块 19 20```ts 21import { common } from '@kit.AbilityKit'; 22``` 23 24## UIExtensionContext 25 26### startAbilityForResultAsCaller 27 28startAbilityForResultAsCaller(want: Want, options?: StartOptions): Promise<AbilityResult> 29 30使用设置的caller信息启动一个Ability，caller信息由want携带，在系统服务层识别，Ability可以在onCreate生命周期的want参数中获取到caller信息。使用该接口启动一个Ability时，want的caller信息不会被当前自身的应用信息覆盖，系统服务层可获取到初始caller的信息。使用Promise异步回调。 31 32 - 正常情况下可通过调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#terminateselfwithresult)接口使之终止并且返回结果给调用方。 33 - 异常情况下比如杀死Ability会返回异常信息给调用方，异常信息中resultCode为-1。 34 - 如果被启动的Ability模式是单实例模式，不同应用多次调用该接口启动这个Ability，当这个Ability调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#terminateselfwithresult)接口使之终止时，只将正常结果返回给最后一个调用方，其它调用方返回异常信息，异常信息中resultCode为-1。 35 36> **说明：** 37> 38> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 39 40**模型约束**：此接口仅可在Stage模型下使用。 41 42**系统接口**：此接口为系统接口。 43 44**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 45 46**参数：** 47 48| 参数名 | 类型 | 必填 | 说明 | 49| ------- | --------------------------------------------------- | ---- | ------------------------- | 50| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 51| options | [StartOptions](js-apis-app-ability-startOptions.md) | 否 | 启动Ability所携带的参数。 | 52 53**返回值：** 54 55| 类型 | 说明 | 56| ------------------------------------------------------------ | ------------------------- | 57| Promise<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Promise对象，返回Ability结果对象。 | 58 59**错误码：** 60 61以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 62 63| 错误码ID | 错误信息 | 64| -------- | ------------------------------------------------------- | 65| 401| Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 66| 16000001 | The specified ability does not exist. | 67| 16000004 | Cannot start an invisible component. | 68| 16000050 | Internal error. | 69| 16000073 | The app clone index is invalid. | 70 71**示例：** 72 73```ts 74import { UIExtensionAbility } from '@kit.AbilityKit'; 75import { BusinessError } from '@kit.BasicServicesKit'; 76 77export default class UIExtension extends UIExtensionAbility { 78 onForeground() { 79 this.context.startAbilityForResultAsCaller({ 80 bundleName: 'com.example.startabilityforresultascaller', 81 abilityName: 'EntryAbility', 82 moduleName: 'entry' 83 }).then((data) => { 84 console.log(`StartAbilityForResultAsCaller success, data: ${JSON.stringify(data)}.`); 85 }).catch((error: BusinessError) => { 86 console.error(`StartAbilityForResultAsCaller failed, err code: ${error.code}, err msg: ${error.message}.`); 87 }); 88 } 89} 90``` 91 92### startServiceExtensionAbility<sup>18+</sup> 93 94startServiceExtensionAbility(want: Want): Promise\<void> 95 96启动一个ServiceExtensionAbility。使用Promise异步回调。 97 98**模型约束**：此接口仅可在Stage模型下使用。 99 100**系统接口**：此接口为系统接口。 101 102**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 103 104**参数：** 105 106| 参数名 | 类型 | 必填 | 说明 | 107| ------ | ------ | ------ | ------ | 108| want | [Want](js-apis-app-ability-want.md) | 是 | 启动ServiceExtensionAbility的Want信息。 | 109 110**返回值：** 111 112| 类型 | 说明 | 113| ------ | ------ | 114| Promise<void> | Promise对象。无返回结果的Promise对象。 | 115 116**错误码：** 117 118以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 119 120| 错误码ID | 错误信息 | 121| ------ | ------ | 122| 201 | The application does not have permission to call the interface. | 123| 202 | The application is not system-app, can not use system-api. | 124| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 125| 16000001 | The specified ability does not exist. | 126| 16000002 | Incorrect ability type. | 127| 16000004 | Cannot start an invisible component. | 128| 16000005 | The specified process does not have the permission. | 129| 16000006 | Cross-user operations are not allowed. | 130| 16000008 | The crowdtesting application expires. | 131| 16000011 | The context does not exist. | 132| 16000012 | The application is controlled. | 133| 16000013 | The application is controlled by EDM. | 134| 16000019 | No matching ability is found. | 135| 16000050 | Internal error. | 136| 16200001 | The caller has been released. | 137 138**示例：** 139 140```ts 141import { UIExtensionAbility, Want } from '@kit.AbilityKit'; 142import { BusinessError } from '@kit.BasicServicesKit'; 143 144export default class UIExtAbility extends UIExtensionAbility { 145 onForeground() { 146 let want: Want = { 147 bundleName: 'com.example.myapplication', 148 moduleName: 'entry', 149 abilityName: 'ServiceExtensionAbility' 150 }; 151 152 try { 153 this.context.startServiceExtensionAbility(want) 154 .then(() => { 155 // 执行正常业务 156 console.info('startServiceExtensionAbility succeed'); 157 }) 158 .catch((err: BusinessError) => { 159 // 处理业务逻辑错误 160 console.error(`startServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`); 161 }); 162 } catch (err) { 163 // 处理入参错误异常 164 let code = (err as BusinessError).code; 165 let message = (err as BusinessError).message; 166 console.error(`startServiceExtensionAbility failed, code is ${code}, message is ${message}`); 167 } 168 } 169} 170``` 171 172### startServiceExtensionAbilityWithAccount<sup>18+</sup> 173 174startServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise\<void> 175 176启动一个指定系统账号下的ServiceExtensionAbility。使用Promise异步回调。 177 178> **说明：** 179> 180> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 181> 182> 当accountId为当前用户时，无需进行权限校验。 183 184**模型约束**：此接口仅可在Stage模型下使用。 185 186**系统接口**：此接口为系统接口。 187 188**需要权限**：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 189 190**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 191 192**参数：** 193 194| 参数名 | 类型 | 必填 | 说明 | 195| ------ | ------ | ------ | ------ | 196| want | [Want](js-apis-app-ability-want.md) | 是 | 启动ServiceExtensionAbility的Want信息。 | 197| accountId | number | 是 | 系统账号的ID，详情参考[getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getosaccountcount9)。 | 198 199**返回值：** 200 201| 类型 | 说明 | 202| ------ | ------ | 203| Promise<void> | Promise对象。无返回结果的Promise对象。 | 204 205**错误码：** 206 207以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 208 209| 错误码ID | 错误信息 | 210| ------ | ------ | 211| 201 | The application does not have permission to call the interface. | 212| 202 | The application is not system-app, can not use system-api. | 213| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 214| 16000001 | The specified ability does not exist. | 215| 16000002 | Incorrect ability type. | 216| 16000004 | Cannot start an invisible component. | 217| 16000005 | The specified process does not have the permission. | 218| 16000006 | Cross-user operations are not allowed. | 219| 16000008 | The crowdtesting application expires. | 220| 16000011 | The context does not exist. | 221| 16000012 | The application is controlled. | 222| 16000013 | The application is controlled by EDM. | 223| 16000019 | No matching ability is found. | 224| 16000050 | Internal error. | 225| 16200001 | The caller has been released. | 226 227**示例：** 228 229```ts 230import { UIExtensionAbility, Want } from '@kit.AbilityKit'; 231import { BusinessError } from '@kit.BasicServicesKit'; 232 233export default class UIExtAbility extends UIExtensionAbility { 234 onForeground() { 235 let want: Want = { 236 bundleName: 'com.example.myapplication', 237 moduleName: 'entry', 238 abilityName: 'ServiceExtensionAbility' 239 }; 240 let accountId = 100; 241 242 try { 243 this.context.startServiceExtensionAbilityWithAccount(want, accountId) 244 .then(() => { 245 // 执行正常业务 246 console.info('startServiceExtensionAbilityWithAccount succeed'); 247 }) 248 .catch((err: BusinessError) => { 249 // 处理业务逻辑错误 250 console.error(`startServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`); 251 }); 252 } catch (err) { 253 // 处理入参错误异常 254 let code = (err as BusinessError).code; 255 let message = (err as BusinessError).message; 256 console.error(`startServiceExtensionAbilityWithAccount failed, code is ${code}, message is ${message}`); 257 } 258 } 259} 260``` 261 262### setHostPageOverlayForbidden<sup>15+</sup> 263 264setHostPageOverlayForbidden(isForbidden: boolean) : void 265 266是否允许[UIExtensionAbility](../apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md)拉起的页面被使用方的页面覆盖。 267 268> **说明：** 269> 270> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 271> 272> 该接口需要在窗口创建之前调用。建议在[UIExtensionAbility](../apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md)的[onCreate](../apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md#oncreate)生命周期内调用。 273 274**模型约束**：此接口仅可在Stage模型下使用。 275 276**系统接口**：此接口为系统接口。 277 278**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 279 280**参数**： 281 282| 参数名 | 类型 | 必填 | 说明 | 283| ------ | ------ | ------ | ------ | 284| isForbidden | boolean | 是 | 是否允许[UIExtensionAbility](../apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md)拉起的页面被使用方的页面覆盖。true表示不允许，false表示允许。 | 285 286 287**错误码**： 288 289以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 290 291| 错误码ID | 错误信息 | 292| ------ | ------ | 293| 202 | The application is not system-app, can not use system-api. | 294| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 295 296**示例**： 297 298```ts 299import { UIExtensionAbility } from '@kit.AbilityKit'; 300import { BusinessError } from '@kit.BasicServicesKit'; 301 302export default class UIExtAbility extends UIExtensionAbility { 303 OnCreate() { 304 try { 305 this.context.setHostPageOverlayForbidden(true) 306 } catch (err) { 307 // 处理入参错误异常 308 let code = (err as BusinessError).code; 309 let message = (err as BusinessError).message; 310 console.error(`setHostPageOverlayForbidden failed, code is ${code}, message is ${message}`); 311 } 312 } 313} 314``` 315 316### startUIAbilities<sup>20+</sup> 317 318startUIAbilities(wantList: Array\<Want>): Promise\<void> 319 320同时启动多个UIAbility。使用Promise异步回调。 321 322开发者可以传入多个UIAbility对应的Want信息，这些UIAbility可以指向一个或多个应用。当所有的UIAbility都能启动成功时，系统会通过多个窗口同时展示这些UIAbility。根据窗口的处理，不同设备上可能会有不同的展示效果（包括窗口形态、数量和排版布局）。 323 324> **说明：** 325> 326> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 327 328**系统接口**：此接口为系统接口。 329 330**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 331 332**设备行为差异**：该接口仅在Phone和Tablet设备中可正常调用，在其他设备中返回801错误码。 333 334**参数**： 335 336| 参数名 | 类型 | 必填 | 说明 | 337| ------ | ------ | ------ | ------ | 338| wantList | Array\<[Want](js-apis-app-ability-want.md)> | 是 | 需要被同时拉起的多个UIAbility的启动参数列表，最多支持传入4个Want。启动参数Want不支持隐式启动、跨用户启动、分布式、免安装和按需加载，不指明分身的情况下默认启动主应用。| 339 340**返回值：** 341 342| 类型 | 说明 | 343| -------- | -------- | 344| Promise<void> | Promise对象，无返回结果。| 345 346**错误码**： 347 348以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 349 350| 错误码ID | 错误信息 | 351| ------ | ------ | 352| 201 | The application does not have permission to call the interface. | 353| 202 | Not system application. | 354| 801 | Capability not supported. | 355| 16000001 | The specified ability does not exist. | 356| 16000004 | Cannot start an invisible component. | 357| 16000005 | The specified process does not have the permission. | 358| 16000006 | Cross-user operations are not allowed. | 359| 16000008 | The crowdtesting application expires. | 360| 16000009 | An ability cannot be started or stopped in Wukong mode. | 361| 16000011 | The context does not exist. | 362| 16000050 | Internal error. | 363| 16200001 | The caller has been released. | 364| 16000073 | The app clone index is invalid. | 365| 16000076 | The app instance key is invalid. | 366| 16000080 | Creating a new instance is not supported. | 367| 16000120 | A maximum of four UIAbility instances can be started simultaneously. The current parameter exceeds the maximum number or is less than 1.| 368| 16000121 | The target component type is not a UIAbility. | 369| 16000122 | The target component is blocked by the system module and does not support startup. | 370| 16000123 | Implicit startup is not supported. | 371| 16000124 | Starting a remote UIAbility is not supported. | 372| 16000125 | Starting a plugin UIAbility is not supported. | 373| 16000126 | Starting DLP files is not supported. | 374 375**示例**： 376 377```ts 378import { UIExtensionAbility, Want } from '@kit.AbilityKit'; 379import { BusinessError } from '@kit.BasicServicesKit'; 380 381export default class EntryUIExtAbility extends UIExtensionAbility { 382 onForeground() { 383 let want1: Want = { 384 bundleName: 'com.example.myapplication1', 385 abilityName: 'EntryAbility' 386 }; 387 let want2: Want = { 388 bundleName: 'com.example.myapplication2', 389 abilityName: 'EntryAbility' 390 }; 391 let wantList: Array<Want> = [want1, want2]; 392 try { 393 this.context.startUIAbilities(wantList).then(() => { 394 console.info(`TestTag:: start succeeded.`); 395 }).catch((error: BusinessError) => { 396 console.info(`TestTag:: startUIAbilities failed: ${JSON.stringify(error)}`); 397 }); 398 } catch (paramError) { 399 // 处理入参错误异常 400 console.error(`error.code: ${paramError.code}, error.message: ${paramError.message}`); 401 } 402 } 403} 404```