1# UIExtensionContext 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 10. 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 10## Modules to Import 11 12```ts 13import common from '@ohos.app.ability.common'; 14``` 15 16## UIExtensionContext.startAbility 17 18startAbility(want: Want, callback: AsyncCallback<void>): void; 19 20Starts an ability. This API uses an asynchronous callback to return the result. 21 22Observe the following when using this API: 23 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 24 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 25 - 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). 26 27**System capability**: SystemCapability.Ability.AbilityRuntime.Core 28 29**Parameters** 30 31| Name| Type| Mandatory| Description| 32| -------- | -------- | -------- | -------- | 33| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 34| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 35 36**Error codes** 37 38| ID| Error Message| 39| ------- | -------------------------------- | 40| 16000001 | The specified ability does not exist. | 41| 16000002 | Incorrect ability type. | 42| 16000004 | Can not start invisible component. | 43| 16000005 | The specified process does not have the permission. | 44| 16000006 | Cross-user operations are not allowed. | 45| 16000008 | The crowdtesting application expires. | 46| 16000009 | An ability cannot be started or stopped in Wukong mode. | 47| 16000010 | The call with the continuation flag is forbidden. | 48| 16000011 | The context does not exist. | 49| 16000012 | The application is controlled. | 50| 16000013 | The application is controlled by EDM. | 51| 16000050 | Internal error. | 52| 16000053 | The ability is not on the top of the UI. | 53| 16000055 | Installation-free timed out. | 54| 16200001 | The caller has been released. | 55 56For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 57 58## UIExtensionContext.startAbility 59 60startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void; 61 62Starts an ability with the start options specified. This API uses an asynchronous callback to return the result. 63 64Observe the following when using this API: 65 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 66 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 67 - 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). 68 69**System capability**: SystemCapability.Ability.AbilityRuntime.Core 70 71**Parameters** 72 73| Name| Type| Mandatory| Description| 74| -------- | -------- | -------- | -------- | 75| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 76| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| 77| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 78 79**Error codes** 80 81| ID| Error Message| 82| ------- | -------------------------------- | 83| 16000001 | The specified ability does not exist. | 84| 16000004 | Can not start invisible component. | 85| 16000005 | The specified process does not have the permission. | 86| 16000006 | Cross-user operations are not allowed. | 87| 16000008 | The crowdtesting application expires. | 88| 16000009 | An ability cannot be started or stopped in Wukong mode. | 89| 16000011 | The context does not exist. | 90| 16000012 | The application is controlled. | 91| 16000013 | The application is controlled by EDM. | 92| 16000050 | Internal error. | 93| 16000053 | The ability is not on the top of the UI. | 94| 16000055 | Installation-free timed out. | 95| 16200001 | The caller has been released. | 96 97For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 98 99## UIExtensionContext.startAbility 100 101startAbility(want: Want, options?: StartOptions): Promise<void>; 102 103Starts an ability. This API uses a promise to return the result. 104 105Observe the following when using this API: 106 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 107 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 108 - 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). 109 110**System capability**: SystemCapability.Ability.AbilityRuntime.Core 111 112**Parameters** 113 114| Name| Type| Mandatory| Description| 115| -------- | -------- | -------- | -------- | 116| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 117| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| 118 119**Return value** 120 121| Type| Description| 122| -------- | -------- | 123| Promise<void> | Promise used to return the result.| 124 125**Error codes** 126 127| ID| Error Message| 128| ------- | -------------------------------- | 129| 16000001 | The specified ability does not exist. | 130| 16000002 | Incorrect ability type. | 131| 16000004 | Can not start invisible component. | 132| 16000005 | The specified process does not have the permission. | 133| 16000006 | Cross-user operations are not allowed. | 134| 16000008 | The crowdtesting application expires. | 135| 16000009 | An ability cannot be started or stopped in Wukong mode. | 136| 16000010 | The call with the continuation flag is forbidden. | 137| 16000011 | The context does not exist. | 138| 16000012 | The application is controlled. | 139| 16000013 | The application is controlled by EDM. | 140| 16000050 | Internal error. | 141| 16000053 | The ability is not on the top of the UI. | 142| 16000055 | Installation-free timed out. | 143| 16200001 | The caller has been released. | 144 145For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 146 147## UIExtensionContext.startAbilityForResult 148 149startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): void; 150 151Starts an ability. This API uses an asynchronous callback to return the result when the ability is terminated. The following situations may be possible for a started ability: 152 - Normally, you can call [terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult) to terminate the ability. The result is returned to the caller. 153 - If an exception occurs, for example, the ability is killed, an error message, in which **resultCode** is **-1**, is returned to the caller. 154 - 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. 155 156Observe the following when using this API: 157 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 158 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 159 - 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). 160 161**System capability**: SystemCapability.Ability.AbilityRuntime.Core 162 163**Parameters** 164 165| Name| Type| Mandatory| Description| 166| -------- | -------- | -------- | -------- | 167| want |[Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 168| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Yes| Callback used to return the result.| 169 170**Error codes** 171 172| ID| Error Message| 173| ------- | -------------------------------- | 174| 16000001 | The specified ability does not exist. | 175| 16000002 | Incorrect ability type. | 176| 16000004 | Can not start invisible component. | 177| 16000005 | The specified process does not have the permission. | 178| 16000006 | Cross-user operations are not allowed. | 179| 16000008 | The crowdtesting application expires. | 180| 16000009 | An ability cannot be started or stopped in Wukong mode. | 181| 16000010 | The call with the continuation flag is forbidden. | 182| 16000011 | The context does not exist. | 183| 16000012 | The application is controlled. | 184| 16000013 | The application is controlled by EDM. | 185| 16000050 | Internal error. | 186| 16000053 | The ability is not on the top of the UI. | 187| 16000055 | Installation-free timed out. | 188| 16200001 | The caller has been released. | 189 190For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 191 192## UIExtensionContext.startAbilityForResult 193 194startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback<AbilityResult>): void; 195 196Starts an ability with the start options specified. This API uses an asynchronous callback to return the result when the ability is terminated. The following situations may be possible for a started ability: 197 - Normally, you can call [terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult) to terminate the ability. The result is returned to the caller. 198 - If an exception occurs, for example, the ability is killed, an error message, in which **resultCode** is **-1**, is returned to the caller. 199 - 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. 200 201Observe the following when using this API: 202 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 203 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 204 - 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). 205 206**System capability**: SystemCapability.Ability.AbilityRuntime.Core 207 208**Parameters** 209 210| Name| Type| Mandatory| Description| 211| -------- | -------- | -------- | -------- | 212| want |[Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 213| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| 214| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Yes| Callback used to return the result.| 215 216**Error codes** 217 218| ID| Error Message| 219| ------- | -------------------------------- | 220| 16000001 | The specified ability does not exist. | 221| 16000004 | Can not start invisible component. | 222| 16000005 | The specified process does not have the permission. | 223| 16000006 | Cross-user operations are not allowed. | 224| 16000008 | The crowdtesting application expires. | 225| 16000009 | An ability cannot be started or stopped in Wukong mode. | 226| 16000011 | The context does not exist. | 227| 16000012 | The application is controlled. | 228| 16000013 | The application is controlled by EDM. | 229| 16000050 | Internal error. | 230| 16000053 | The ability is not on the top of the UI. | 231| 16000055 | Installation-free timed out. | 232| 16200001 | The caller has been released. | 233 234For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 235 236## UIExtensionContext.startAbilityForResult 237 238startAbilityForResult(want: Want, options?: StartOptions): Promise<AbilityResult>; 239 240Starts an ability. This API uses a promise to return the result when the ability is terminated. The following situations may be possible for a started ability: 241 - Normally, you can call [terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult) to terminate the ability. The result is returned to the caller. 242 - If an exception occurs, for example, the ability is killed, an error message, in which **resultCode** is **-1**, is returned to the caller. 243 - 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. 244 245Observe the following when using this API: 246 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 247 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 248 - 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). 249 250**System capability**: SystemCapability.Ability.AbilityRuntime.Core 251 252**Parameters** 253 254| Name| Type| Mandatory| Description| 255| -------- | -------- | -------- | -------- | 256| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 257| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| 258 259 260**Return value** 261 262| Type| Description| 263| -------- | -------- | 264| Promise<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Promise used to return the result.| 265 266**Error codes** 267 268| ID| Error Message| 269| ------- | -------------------------------- | 270| 16000001 | The specified ability does not exist. | 271| 16000002 | Incorrect ability type. | 272| 16000004 | Can not start invisible component. | 273| 16000005 | The specified process does not have the permission. | 274| 16000006 | Cross-user operations are not allowed. | 275| 16000008 | The crowdtesting application expires. | 276| 16000009 | An ability cannot be started or stopped in Wukong mode. | 277| 16000010 | The call with the continuation flag is forbidden. | 278| 16000011 | The context does not exist. | 279| 16000012 | The application is controlled. | 280| 16000013 | The application is controlled by EDM. | 281| 16000050 | Internal error. | 282| 16000053 | The ability is not on the top of the UI. | 283| 16000055 | Installation-free timed out. | 284| 16200001 | The caller has been released. | 285 286For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 287 288 289## UIExtensionContext.connectServiceExtensionAbility 290 291connectServiceExtensionAbility(want: Want, options: ConnectOptions): number; 292 293Connects this ability to an ability that uses the **AbilityInfo.AbilityType.SERVICE** template. 294 295**System capability**: SystemCapability.Ability.AbilityRuntime.Core 296 297**Parameters** 298 299| Name| Type| Mandatory| Description| 300| -------- | -------- | -------- | -------- | 301| want | [Want](js-apis-app-ability-want.md) | Yes| Want information for connecting to the ServiceExtensionAbility.| 302| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | Yes| Instance of the callback function after the connection to the ServiceExtensionAbility is set up.| 303 304**Return value** 305 306| Type| Description| 307| -------- | -------- | 308| number | Result code of the ability connection.| 309 310**Error codes** 311 312| ID| Error Message| 313| ------- | -------------------------------- | 314| 16000001 | The specified ability does not exist. | 315| 16000002 | Incorrect ability type. | 316| 16000004 | Can not start invisible component. | 317| 16000005 | The specified process does not have the permission. | 318| 16000006 | Cross-user operations are not allowed. | 319| 16000008 | The crowdtesting application expires. | 320| 16000053 | The ability is not on the top of the UI. | 321| 16000055 | Installation-free timed out. | 322| 16000011 | The context does not exist. | 323| 16000050 | Internal error. | 324 325For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 326 327 328## UIExtensionContext.disconnectServiceExtensionAbility 329 330disconnectServiceExtensionAbility(connection: number): Promise\<void>; 331 332Disconnects this ability from a ServiceExtensionAbility and after the successful disconnection, sets the remote object returned upon the connection to void. This API uses a promise to return the result. 333 334**System capability**: SystemCapability.Ability.AbilityRuntime.Core 335 336**Parameters** 337 338| Name| Type| Mandatory| Description| 339| -------- | -------- | -------- | -------- | 340| connection | number | Yes| Digital code of the connected ServiceExtensionAbility, that is, connectionId returned by **connectServiceExtensionAbility**.| 341 342**Return value** 343 344| Type| Description| 345| -------- | -------- | 346| Promise\<void> | Promise used to return the result.| 347 348**Error codes** 349 350| ID| Error Message| 351| ------- | -------------------------------- | 352| 16000011 | The context does not exist. | 353| 16000050 | Internal error. | 354 355For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 356 357## UIExtensionContext.disconnectServiceExtensionAbility 358 359disconnectServiceExtensionAbility(connection: number, callback:AsyncCallback\<void>): void; 360 361Disconnects this ability from a ServiceExtensionAbility and after the successful disconnection, sets the remote object returned upon the connection to void. This API uses an asynchronous callback to return the result. 362 363**System capability**: SystemCapability.Ability.AbilityRuntime.Core 364 365**Parameters** 366 367| Name| Type| Mandatory| Description| 368| -------- | -------- | -------- | -------- | 369| connection | number | Yes| Digital code of the connected ServiceExtensionAbility, that is, connectionId returned by **connectServiceExtensionAbility**.| 370| callback | AsyncCallback\<void> | Yes| Callback used to return the result.| 371 372**Error codes** 373 374| ID| Error Message| 375| ------- | -------------------------------- | 376| 16000011 | The context does not exist. | 377| 16000050 | Internal error. | 378 379For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 380