1# UIExtensionContext (System API) 2 3**UIExtensionContext**, inherited from [ExtensionContext](js-apis-inner-application-extensionContext.md), provides the context environment for [UIExtensionAbility](js-apis-app-ability-uiExtensionAbility.md). It provides UIExtensionAbility-related configuration and APIs for operating the UIExtensionAbility. For example, you can use the APIs to start a UIExtensionAbility. 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> - The APIs of this module can be used only in the stage model. 9> - The APIs provided by this module are system APIs. 10 11## Modules to Import 12 13```ts 14import { common } from '@kit.AbilityKit'; 15``` 16 17## UIExtensionContext.startAbilityForResultAsCaller 18 19startAbilityForResultAsCaller(want: Want, options?: StartOptions): Promise<AbilityResult> 20 21Starts an ability with the caller information specified. This API uses a promise to return the result. 22 23The caller information is carried in **want** and identified at the system service layer. The ability can obtain the caller information from the **want** parameter in the **onCreate** lifecycle callback. 24 25When this API is used to start an ability, the caller information carried in **want** is not overwritten by the current application information. The system service layer can obtain the initial caller information. 26 27 - Normally, you can call [terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult) to terminate the ability. The result is returned to the caller. 28 - If an exception occurs, for example, the ability is killed, an error message, in which **resultCode** is **-1**, is returned to the caller. 29 - If different applications call this API to start an ability that uses the singleton mode and then call [terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult) to terminate the ability, the normal result is returned to the last caller, and an exception message, in which **resultCode** is **-1**, is returned to others. 30 31> **NOTE** 32> 33> For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 34 35**Model restriction**: This API can be used only in the stage model. 36 37**System API**: This is a system API. 38 39**System capability**: SystemCapability.Ability.AbilityRuntime.Core 40 41**Parameters** 42 43| Name | Type | Mandatory| Description | 44| ------- | --------------------------------------------------- | ---- | ------------------------- | 45| want | [Want](js-apis-app-ability-want.md) | Yes | Want information about the target ability. | 46| options | [StartOptions](js-apis-app-ability-startOptions.md) | No | Parameters used for starting the ability.| 47 48**Return value** 49 50| Type | Description | 51| ------------------------------------------------------------ | ------------------------- | 52| Promise<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Promise used to return the result.| 53 54**Error codes** 55 56For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 57 58| ID| Error Message | 59| -------- | ------------------------------------------------------- | 60| 401| Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 61| 16000001 | The specified ability does not exist. | 62| 16000004 | Failed to start the invisible ability. | 63| 16000050 | Internal error. | 64| 16000073 | The app clone index is invalid. | 65 66**Example** 67 68```ts 69import { UIExtensionAbility } from '@kit.AbilityKit'; 70import { BusinessError } from '@kit.BasicServicesKit'; 71 72export default class UIExtension extends UIExtensionAbility { 73 onForeground() { 74 this.context.startAbilityForResultAsCaller({ 75 bundleName: 'com.example.startabilityforresultascaller', 76 abilityName: 'EntryAbility', 77 moduleName: 'entry' 78 }).then((data) => { 79 console.log('=======>startAbilityForResultAsCaller data Promise ======>' + JSON.stringify(data)); 80 }).catch((error: BusinessError) => { 81 console.log('=======>startAbilityForResultAsCaller error.code Promise ======>' + error.code); 82 }); 83 } 84} 85``` 86 87## UIExtensionContext.startServiceExtensionAbility<sup>18+</sup> 88 89startServiceExtensionAbility(want: Want): Promise\<void> 90 91Starts a ServiceExtensionAbility. This API uses a promise to return the result. 92 93**Model restriction**: This API can be used only in the stage model. 94 95**System API**: This is a system API. 96 97**System capability**: SystemCapability.Ability.AbilityRuntime.Core 98 99**Parameters** 100 101| Name| Type| Mandatory| Description| 102| ------ | ------ | ------ | ------ | 103| want | [Want](js-apis-app-ability-want.md) | Yes| Want information for starting the ServiceExtensionAbility.| 104 105**Return value** 106 107| Type| Description| 108| ------ | ------ | 109| Promise<void> | Promise that returns no value.| 110 111**Error codes** 112 113For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 114 115| ID| Error Message| 116| ------ | ------ | 117| 201 | The application does not have permission to call the interface. | 118| 202 | The application is not system-app, can not use system-api. | 119| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 120| 16000001 | The specified ability does not exist. | 121| 16000002 | Incorrect ability type. | 122| 16000004 | Failed to start the invisible ability. | 123| 16000005 | The specified process does not have the permission. | 124| 16000006 | Cross-user operations are not allowed. | 125| 16000008 | The crowdtesting application expires. | 126| 16000011 | The context does not exist. | 127| 16000012 | The application is controlled. | 128| 16000013 | The application is controlled by EDM. | 129| 16000019 | No matching ability is found. | 130| 16000050 | Internal error. | 131| 16200001 | The caller has been released. | 132 133**Example** 134 135```ts 136import { UIExtensionAbility, Want } from '@kit.AbilityKit'; 137import { BusinessError } from '@kit.BasicServicesKit'; 138 139export default class UIExtAbility extends UIExtensionAbility { 140 onForeground() { 141 let want: Want = { 142 bundleName: 'com.example.myapplication', 143 moduleName: 'entry', 144 abilityName: 'ServiceExtensionAbility' 145 }; 146 147 try { 148 this.context.startServiceExtensionAbility(want) 149 .then(() => { 150 // Carry out normal service processing. 151 console.info('startServiceExtensionAbility succeed'); 152 }) 153 .catch((err: BusinessError) => { 154 // Process service logic errors. 155 console.error(`startServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`); 156 }); 157 } catch (err) { 158 // Process input parameter errors. 159 let code = (err as BusinessError).code; 160 let message = (err as BusinessError).message; 161 console.error(`startServiceExtensionAbility failed, code is ${code}, message is ${message}`); 162 } 163 } 164} 165``` 166 167## UIExtensionContext.startServiceExtensionAbilityWithAccount<sup>18+</sup> 168 169startServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise\<void> 170 171Starts a ServiceExtensionAbility under a specified system account. This API uses a promise to return the result. 172 173> **NOTE** 174> 175> For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 176> 177> Permission verification is not required when **accountId** specifies the current user. 178 179**Model restriction**: This API can be used only in the stage model. 180 181**System API**: This is a system API. 182 183**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 184 185**System capability**: SystemCapability.Ability.AbilityRuntime.Core 186 187**Parameters** 188 189| Name| Type| Mandatory| Description| 190| ------ | ------ | ------ | ------ | 191| want | [Want](js-apis-app-ability-want.md) | Yes| Want information for starting the ServiceExtensionAbility.| 192| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getosaccountcount9).| 193 194**Return value** 195 196| Type| Description| 197| ------ | ------ | 198| Promise<void> | Promise that returns no value.| 199 200**Error codes** 201 202For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 203 204| ID| Error Message| 205| ------ | ------ | 206| 201 | The application does not have permission to call the interface. | 207| 202 | The application is not system-app, can not use system-api. | 208| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 209| 16000001 | The specified ability does not exist. | 210| 16000002 | Incorrect ability type. | 211| 16000004 | Failed to start the invisible ability. | 212| 16000005 | The specified process does not have the permission. | 213| 16000006 | Cross-user operations are not allowed. | 214| 16000008 | The crowdtesting application expires. | 215| 16000011 | The context does not exist. | 216| 16000012 | The application is controlled. | 217| 16000013 | The application is controlled by EDM. | 218| 16000019 | No matching ability is found. | 219| 16000050 | Internal error. | 220| 16200001 | The caller has been released. | 221 222**Example** 223 224```ts 225import { UIExtensionAbility, Want } from '@kit.AbilityKit'; 226import { BusinessError } from '@kit.BasicServicesKit'; 227 228export default class UIExtAbility extends UIExtensionAbility { 229 onForeground() { 230 let want: Want = { 231 bundleName: 'com.example.myapplication', 232 moduleName: 'entry', 233 abilityName: 'ServiceExtensionAbility' 234 }; 235 let accountId = 100; 236 237 try { 238 this.context.startServiceExtensionAbilityWithAccount(want, accountId) 239 .then(() => { 240 // Carry out normal service processing. 241 console.info('startServiceExtensionAbilityWithAccount succeed'); 242 }) 243 .catch((err: BusinessError) => { 244 // Process service logic errors. 245 console.error(`startServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`); 246 }); 247 } catch (err) { 248 // Process input parameter errors. 249 let code = (err as BusinessError).code; 250 let message = (err as BusinessError).message; 251 console.error(`startServiceExtensionAbilityWithAccount failed, code is ${code}, message is ${message}`); 252 } 253 } 254} 255``` 256 257## UIExtensionContext.setHostPageOverlayForbidden<sup>15+</sup> 258 259setHostPageOverlayForbidden(isForbidden: boolean) : void 260 261Sets whether the page started by the [UIExtensionAbility](../apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md) can be overlaid by the page of the user. 262 263> **NOTE** 264> 265> For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 266> 267> This API must be called before a window is created. You are advised to call it within the [onCreate](../apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md#uiextensionabilityoncreate) lifecycle of the [UIExtensionAbility](../apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md). 268 269**Model restriction**: This API can be used only in the stage model. 270 271**System API**: This is a system API. 272 273**System capability**: SystemCapability.Ability.AbilityRuntime.Core 274 275**Parameters** 276 277| Name| Type| Mandatory| Description| 278| ------ | ------ | ------ | ------ | 279| isForbidden | boolean | Yes| Whether the page started by the [UIExtensionAbility](../apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md) can be overlaid by the page of the user. The value **true** means that the page can be overlaid, and **false** means the opposite.| 280 281 282**Error codes** 283 284For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 285 286| ID| Error Message| 287| ------ | ------ | 288| 202 | The application is not system-app, can not use system-api. | 289| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 290 291**Example** 292 293```ts 294import { UIExtensionAbility } from '@kit.AbilityKit'; 295import { BusinessError } from '@kit.BasicServicesKit'; 296 297export default class UIExtAbility extends UIExtensionAbility { 298 OnCreate() { 299 try { 300 this.context.setHostPageOverlayForbidden(true) 301 } catch (err) { 302 // Process input parameter errors. 303 let code = (err as BusinessError).code; 304 let message = (err as BusinessError).message; 305 console.error(`setHostPageOverlayForbidden failed, code is ${code}, message is ${message}`); 306 } 307 } 308} 309``` 310