1# UIExtensionContext (系统接口) 2 3UIExtensionContext是[UIExtensionAbility](js-apis-app-ability-uiExtensionAbility.md)的上下文环境，继承自[ExtensionContext](js-apis-inner-application-extensionContext.md)，提供UIExtensionAbility的相关配置信息以及操作UIAbility的方法，如启动UIAbility等。 4 5> **说明：** 6> 7> - 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> - 本模块接口仅可在Stage模型下使用。 9> - 本模块接口为系统接口。 10 11## 导入模块 12 13```ts 14import { common } from '@kit.AbilityKit'; 15``` 16 17## UIExtensionContext.startAbilityForResultAsCaller 18 19startAbilityForResultAsCaller(want: Want, options?: StartOptions): Promise<AbilityResult> 20 21使用设置的caller信息启动一个Ability，caller信息由want携带，在系统服务层识别，Ability可以在onCreate生命周期的want参数中获取到caller信息。使用该接口启动一个Ability时，want的caller信息不会被当前自身的应用信息覆盖，系统服务层可获取到初始caller的信息。使用Promise异步回调。 22 23 - 正常情况下可通过调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)接口使之终止并且返回结果给调用方。 24 - 异常情况下比如杀死Ability会返回异常信息给调用方，异常信息中resultCode为-1。 25 - 如果被启动的Ability模式是单实例模式，不同应用多次调用该接口启动这个Ability，当这个Ability调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)接口使之终止时，只将正常结果返回给最后一个调用方，其它调用方返回异常信息，异常信息中resultCode为-1。 26 27> **说明：** 28> 29> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 30 31**模型约束**：此接口仅可在Stage模型下使用。 32 33**系统接口**：此接口为系统接口。 34 35**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 36 37**参数：** 38 39| 参数名 | 类型 | 必填 | 说明 | 40| ------- | --------------------------------------------------- | ---- | ------------------------- | 41| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 42| options | [StartOptions](js-apis-app-ability-startOptions.md) | 否 | 启动Ability所携带的参数。 | 43 44**返回值：** 45 46| 类型 | 说明 | 47| ------------------------------------------------------------ | ------------------------- | 48| Promise<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Promise对象，返回Ability结果对象。 | 49 50**错误码：** 51 52以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 53 54| 错误码ID | 错误信息 | 55| -------- | ------------------------------------------------------- | 56| 401| Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 57| 16000001 | The specified ability does not exist. | 58| 16000004 | Failed to start the invisible ability. | 59| 16000050 | Internal error. | 60| 16000073 | The app clone index is invalid. | 61 62**示例：** 63 64```ts 65import { UIExtensionAbility } from '@kit.AbilityKit'; 66import { BusinessError } from '@kit.BasicServicesKit'; 67 68export default class UIExtension extends UIExtensionAbility { 69 onForeground() { 70 this.context.startAbilityForResultAsCaller({ 71 bundleName: 'com.example.startabilityforresultascaller', 72 abilityName: 'EntryAbility', 73 moduleName: 'entry' 74 }).then((data) => { 75 console.log('=======>startAbilityForResultAsCaller data Promise ======>' + JSON.stringify(data)); 76 }).catch((error: BusinessError) => { 77 console.log('=======>startAbilityForResultAsCaller error.code Promise ======>' + error.code); 78 }); 79 } 80} 81``` 82 83## UIExtensionContext.startServiceExtensionAbility<sup>18+</sup> 84 85startServiceExtensionAbility(want: Want): Promise\<void> 86 87启动一个ServiceExtensionAbility。使用Promise异步回调。 88 89**模型约束**：此接口仅可在Stage模型下使用。 90 91**系统接口**：此接口为系统接口。 92 93**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 94 95**参数：** 96 97| 参数名 | 类型 | 必填 | 说明 | 98| ------ | ------ | ------ | ------ | 99| want | [Want](js-apis-app-ability-want.md) | 是 | 启动ServiceExtensionAbility的Want信息。 | 100 101**返回值：** 102 103| 类型 | 说明 | 104| ------ | ------ | 105| Promise<void> | Promise对象。无返回结果的Promise对象。 | 106 107**错误码：** 108 109以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 110 111| 错误码ID | 错误信息 | 112| ------ | ------ | 113| 201 | The application does not have permission to call the interface. | 114| 202 | The application is not system-app, can not use system-api. | 115| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 116| 16000001 | The specified ability does not exist. | 117| 16000002 | Incorrect ability type. | 118| 16000004 | Failed to start the invisible ability. | 119| 16000005 | The specified process does not have the permission. | 120| 16000006 | Cross-user operations are not allowed. | 121| 16000008 | The crowdtesting application expires. | 122| 16000011 | The context does not exist. | 123| 16000012 | The application is controlled. | 124| 16000013 | The application is controlled by EDM. | 125| 16000019 | No matching ability is found. | 126| 16000050 | Internal error. | 127| 16200001 | The caller has been released. | 128 129**示例：** 130 131```ts 132import { UIExtensionAbility, Want } from '@kit.AbilityKit'; 133import { BusinessError } from '@kit.BasicServicesKit'; 134 135export default class UIExtAbility extends UIExtensionAbility { 136 onForeground() { 137 let want: Want = { 138 bundleName: 'com.example.myapplication', 139 moduleName: 'entry', 140 abilityName: 'ServiceExtensionAbility' 141 }; 142 143 try { 144 this.context.startServiceExtensionAbility(want) 145 .then(() => { 146 // 执行正常业务 147 console.info('startServiceExtensionAbility succeed'); 148 }) 149 .catch((err: BusinessError) => { 150 // 处理业务逻辑错误 151 console.error(`startServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`); 152 }); 153 } catch (err) { 154 // 处理入参错误异常 155 let code = (err as BusinessError).code; 156 let message = (err as BusinessError).message; 157 console.error(`startServiceExtensionAbility failed, code is ${code}, message is ${message}`); 158 } 159 } 160} 161``` 162 163## UIExtensionContext.startServiceExtensionAbilityWithAccount<sup>18+</sup> 164 165startServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise\<void> 166 167启动一个指定系统账号下的ServiceExtensionAbility。使用Promise异步回调。 168 169> **说明：** 170> 171> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 172> 173> 当accountId为当前用户时，无需进行权限校验。 174 175**模型约束**：此接口仅可在Stage模型下使用。 176 177**系统接口**：此接口为系统接口。 178 179**需要权限**：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 180 181**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 182 183**参数：** 184 185| 参数名 | 类型 | 必填 | 说明 | 186| ------ | ------ | ------ | ------ | 187| want | [Want](js-apis-app-ability-want.md) | 是 | 启动ServiceExtensionAbility的Want信息。 | 188| accountId | number | 是 | 系统账号的ID，详情参考[getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getosaccountcount9)。 | 189 190**返回值：** 191 192| 类型 | 说明 | 193| ------ | ------ | 194| Promise<void> | Promise对象。无返回结果的Promise对象。 | 195 196**错误码：** 197 198以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 199 200| 错误码ID | 错误信息 | 201| ------ | ------ | 202| 201 | The application does not have permission to call the interface. | 203| 202 | The application is not system-app, can not use system-api. | 204| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 205| 16000001 | The specified ability does not exist. | 206| 16000002 | Incorrect ability type. | 207| 16000004 | Failed to start the invisible ability. | 208| 16000005 | The specified process does not have the permission. | 209| 16000006 | Cross-user operations are not allowed. | 210| 16000008 | The crowdtesting application expires. | 211| 16000011 | The context does not exist. | 212| 16000012 | The application is controlled. | 213| 16000013 | The application is controlled by EDM. | 214| 16000019 | No matching ability is found. | 215| 16000050 | Internal error. | 216| 16200001 | The caller has been released. | 217 218**示例：** 219 220```ts 221import { UIExtensionAbility, Want } from '@kit.AbilityKit'; 222import { BusinessError } from '@kit.BasicServicesKit'; 223 224export default class UIExtAbility extends UIExtensionAbility { 225 onForeground() { 226 let want: Want = { 227 bundleName: 'com.example.myapplication', 228 moduleName: 'entry', 229 abilityName: 'ServiceExtensionAbility' 230 }; 231 let accountId = 100; 232 233 try { 234 this.context.startServiceExtensionAbilityWithAccount(want, accountId) 235 .then(() => { 236 // 执行正常业务 237 console.info('startServiceExtensionAbilityWithAccount succeed'); 238 }) 239 .catch((err: BusinessError) => { 240 // 处理业务逻辑错误 241 console.error(`startServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`); 242 }); 243 } catch (err) { 244 // 处理入参错误异常 245 let code = (err as BusinessError).code; 246 let message = (err as BusinessError).message; 247 console.error(`startServiceExtensionAbilityWithAccount failed, code is ${code}, message is ${message}`); 248 } 249 } 250} 251``` 252 253## UIExtensionContext.setHostPageOverlayForbidden<sup>15+</sup> 254 255setHostPageOverlayForbidden(isForbidden: boolean) : void 256 257是否允许[UIExtensionAbility](../apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md)拉起的页面被使用方的页面覆盖。 258 259> **说明：** 260> 261> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 262> 263> 该接口需要在窗口创建之前调用。建议在[UIExtensionAbility](../apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md)的[onCreate](../apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md#uiextensionabilityoncreate)生命周期内调用。 264 265**模型约束**：此接口仅可在Stage模型下使用。 266 267**系统接口**：此接口为系统接口。 268 269**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 270 271**参数**： 272 273| 参数名 | 类型 | 必填 | 说明 | 274| ------ | ------ | ------ | ------ | 275| isForbidden | boolean | 是 | 是否允许[UIExtensionAbility](../apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md)拉起的页面被使用方的页面覆盖。true表示不允许，false表示允许。 | 276 277 278**错误码**： 279 280以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 281 282| 错误码ID | 错误信息 | 283| ------ | ------ | 284| 202 | The application is not system-app, can not use system-api. | 285| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 286 287**示例**： 288 289```ts 290import { UIExtensionAbility } from '@kit.AbilityKit'; 291import { BusinessError } from '@kit.BasicServicesKit'; 292 293export default class UIExtAbility extends UIExtensionAbility { 294 OnCreate() { 295 try { 296 this.context.setHostPageOverlayForbidden(true) 297 } catch (err) { 298 // 处理入参错误异常 299 let code = (err as BusinessError).code; 300 let message = (err as BusinessError).message; 301 console.error(`setHostPageOverlayForbidden failed, code is ${code}, message is ${message}`); 302 } 303 } 304} 305``` 306