1# @ohos.app.ability.UIExtensionContentSession (UI Operation Class for ExtensionAbilities with UI) 2 3**UIExtensionContentSession** is an instance created when the [UIExtensionAbility](js-apis-app-ability-uiExtensionAbility.md) loads UI content. When the UIExtensionComponent starts a UIExtensionAbility, the UIExtensionAbility creates a UIExtensionContentSession instance and returns it through the [onSessionCreate](js-apis-app-ability-uiExtensionAbility.md#uiextensionabilityonsessioncreate) callback. One UIExtensionComponent corresponds to one **UIExtensionContentSession** instance, which provides methods such as UI loading and result notification. The **UIExtensionContentSession** instances of multiple UIExtensionAbilities are operated separately. 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 UIExtensionContentSession from '@ohos.app.ability.UIExtensionContentSession'; 14``` 15 16## UIExtensionContentSession.sendData 17 18sendData(data: { [key: string]: Object }): void 19 20Sends data to the UIExtensionComponent. 21 22**System capability**: SystemCapability.Ability.AbilityRuntime.Core 23 24**System API**: This is a system API and cannot be called by third-party applications. 25 26**Parameters** 27 28| Name| Type| Mandatory| Description| 29| -------- | -------- | -------- | -------- | 30| data | {[key: string]: Object} | Yes| Data to send.| 31 32**Error codes** 33 34| ID| Error Message| 35| ------- | -------------------------------- | 36| 16000050 | Internal error. | 37 38For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 39 40## UIExtensionContentSession.setReceiveDataCallback 41 42setReceiveDataCallback(callback: (data: { [key: string]: Object }) => void): void 43 44Sets the callback used to receive data from the UIExtensionComponent. 45 46**System capability**: SystemCapability.Ability.AbilityRuntime.Core 47 48**System API**: This is a system API and cannot be called by third-party applications. 49 50**Parameters** 51 52| Name| Type| Mandatory| Description| 53| -------- | -------- | -------- | -------- | 54| callback | (data: { [key: string]: Object }) => void | Yes| Callback used to receive data.| 55 56**Error codes** 57 58| ID| Error Message| 59| ------- | -------------------------------- | 60| 16000050 | Internal error. | 61 62For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 63 64## UIExtensionContentSession.loadContent 65 66loadContent(path: string, storage?: LocalStorage): void; 67 68Loads content from a page associated with a local storage to the window corresponding to the current UIExtensionComponent. 69 70**System capability**: SystemCapability.Ability.AbilityRuntime.Core 71 72**Parameters** 73 74| Name | Type | Mandatory| Description | 75| ------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 76| path | string | Yes | Path of the page from which the content will be loaded. | 77| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | No | A storage unit, which provides storage for variable state properties and non-variable state properties of an application. This parameter is left blank by default.| 78 79**Error codes** 80 81| ID| Error Message| 82| ------- | -------------------------------- | 83| 16000050 | Internal error. | 84 85For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 86 87## UIExtensionContentSession.startAbility 88 89startAbility(want: Want, callback: AsyncCallback<void>): void; 90 91Starts an ability. This API uses an asynchronous callback to return the result. 92 93Observe the following when using this API: 94 - The application where the UIExtensionComponent is located must be running in the foreground and gain focus. 95 - 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. 96 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 97 - 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). 98 99**System capability**: SystemCapability.Ability.AbilityRuntime.Core 100 101**System API**: This is a system API and cannot be called by third-party applications. 102 103**Parameters** 104 105| Name| Type| Mandatory| Description| 106| -------- | -------- | -------- | -------- | 107| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 108| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 109 110**Error codes** 111 112| ID| Error Message| 113| ------- | -------------------------------- | 114| 16000001 | The specified ability does not exist. | 115| 16000002 | Incorrect ability type. | 116| 16000004 | Can not start invisible component. | 117| 16000005 | The specified process does not have the permission. | 118| 16000006 | Cross-user operations are not allowed. | 119| 16000008 | The crowdtesting application expires. | 120| 16000009 | An ability cannot be started or stopped in Wukong mode. | 121| 16000010 | The call with the continuation flag is forbidden. | 122| 16000011 | The context does not exist. | 123| 16000012 | The application is controlled. | 124| 16000013 | The application is controlled by EDM. | 125| 16000050 | Internal error. | 126| 16000053 | The ability is not on the top of the UI. | 127| 16000055 | Installation-free timed out. | 128| 16200001 | The caller has been released. | 129 130For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 131 132## UIExtensionContentSession.startAbility 133 134startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void; 135 136Starts an ability with **options** specified. This API uses an asynchronous callback to return the result. 137 138Observe the following when using this API: 139 - The application where the UIExtensionComponent is located must be running in the foreground and gain focus. 140 - 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. 141 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 142 - 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). 143 144**System capability**: SystemCapability.Ability.AbilityRuntime.Core 145 146**System API**: This is a system API and cannot be called by third-party applications. 147 148**Parameters** 149 150| Name| Type| Mandatory| Description| 151| -------- | -------- | -------- | -------- | 152| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 153| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| 154| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 155 156**Error codes** 157 158| ID| Error Message| 159| ------- | -------------------------------- | 160| 16000001 | The specified ability does not exist. | 161| 16000004 | Can not start invisible component. | 162| 16000005 | The specified process does not have the permission. | 163| 16000006 | Cross-user operations are not allowed. | 164| 16000008 | The crowdtesting application expires. | 165| 16000009 | An ability cannot be started or stopped in Wukong mode. | 166| 16000011 | The context does not exist. | 167| 16000012 | The application is controlled. | 168| 16000013 | The application is controlled by EDM. | 169| 16000050 | Internal error. | 170| 16000053 | The ability is not on the top of the UI. | 171| 16000055 | Installation-free timed out. | 172| 16200001 | The caller has been released. | 173 174For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 175 176## UIExtensionContentSession.startAbility 177 178startAbility(want: Want, options?: StartOptions): Promise<void>; 179 180Starts an ability. This API uses a promise to return the result. 181 182Observe the following when using this API: 183 - The application where the UIExtensionComponent is located must be running in the foreground and gain focus. 184 - 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. 185 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 186 - 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). 187 188**System capability**: SystemCapability.Ability.AbilityRuntime.Core 189 190**System API**: This is a system API and cannot be called by third-party applications. 191 192**Parameters** 193 194| Name| Type| Mandatory| Description| 195| -------- | -------- | -------- | -------- | 196| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 197| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| 198 199**Return value** 200 201| Type| Description| 202| -------- | -------- | 203| Promise<void> | Promise used to return the result.| 204 205**Error codes** 206 207| ID| Error Message| 208| ------- | -------------------------------- | 209| 16000001 | The specified ability does not exist. | 210| 16000002 | Incorrect ability type. | 211| 16000004 | Can not start invisible component. | 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| 16000009 | An ability cannot be started or stopped in Wukong mode. | 216| 16000010 | The call with the continuation flag is forbidden. | 217| 16000011 | The context does not exist. | 218| 16000012 | The application is controlled. | 219| 16000013 | The application is controlled by EDM. | 220| 16000050 | Internal error. | 221| 16000053 | The ability is not on the top of the UI. | 222| 16000055 | Installation-free timed out. | 223| 16200001 | The caller has been released. | 224 225For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 226 227## UIExtensionContentSession.startAbilityForResult 228 229startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): void; 230 231Starts an ability. This API uses an asynchronous callback to return the result to the caller after the ability is terminated. An ability can be terminated in the following ways: 232 - Normally, you can call [terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult) to terminate the ability. The result is returned to the caller. 233 - If an exception occurs, for example, the ability is killed, an error message, in which **resultCode** is **-1**, is returned to the caller. 234 - 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. 235 236Observe the following when using this API: 237 - The application where the UIExtensionComponent is located must be running in the foreground and gain focus. 238 - 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. 239 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 240 - 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). 241 242**System capability**: SystemCapability.Ability.AbilityRuntime.Core 243 244**System API**: This is a system API and cannot be called by third-party applications. 245 246**Parameters** 247 248| Name| Type| Mandatory| Description| 249| -------- | -------- | -------- | -------- | 250| want |[Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 251| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Yes| Callback used to return the result.| 252 253**Error codes** 254 255| ID| Error Message| 256| ------- | -------------------------------- | 257| 16000001 | The specified ability does not exist. | 258| 16000002 | Incorrect ability type. | 259| 16000004 | Can not start invisible component. | 260| 16000005 | The specified process does not have the permission. | 261| 16000006 | Cross-user operations are not allowed. | 262| 16000008 | The crowdtesting application expires. | 263| 16000009 | An ability cannot be started or stopped in Wukong mode. | 264| 16000010 | The call with the continuation flag is forbidden. | 265| 16000011 | The context does not exist. | 266| 16000012 | The application is controlled. | 267| 16000013 | The application is controlled by EDM. | 268| 16000050 | Internal error. | 269| 16000053 | The ability is not on the top of the UI. | 270| 16000055 | Installation-free timed out. | 271| 16200001 | The caller has been released. | 272 273For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 274 275## UIExtensionContentSession.startAbilityForResult 276 277startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback<AbilityResult>): void; 278 279Starts an ability with **options** specified. This API uses an asynchronous callback to return the result to the caller after the ability is terminated. An ability can be terminated in the following ways: 280 - Normally, you can call [terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult) to terminate the ability. The result is returned to the caller. 281 - If an exception occurs, for example, the ability is killed, an error message, in which **resultCode** is **-1**, is returned to the caller. 282 - 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. 283 284Observe the following when using this API: 285 - The application where the UIExtensionComponent is located must be running in the foreground and gain focus. 286 - 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. 287 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 288 - 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). 289 290**System capability**: SystemCapability.Ability.AbilityRuntime.Core 291 292**System API**: This is a system API and cannot be called by third-party applications. 293 294**Parameters** 295 296| Name| Type| Mandatory| Description| 297| -------- | -------- | -------- | -------- | 298| want |[Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 299| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| 300| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Yes| Callback used to return the result.| 301 302**Error codes** 303 304| ID| Error Message| 305| ------- | -------------------------------- | 306| 16000001 | The specified ability does not exist. | 307| 16000004 | Can not start invisible component. | 308| 16000005 | The specified process does not have the permission. | 309| 16000006 | Cross-user operations are not allowed. | 310| 16000008 | The crowdtesting application expires. | 311| 16000009 | An ability cannot be started or stopped in Wukong mode. | 312| 16000011 | The context does not exist. | 313| 16000012 | The application is controlled. | 314| 16000013 | The application is controlled by EDM. | 315| 16000050 | Internal error. | 316| 16000053 | The ability is not on the top of the UI. | 317| 16000055 | Installation-free timed out. | 318| 16200001 | The caller has been released. | 319 320For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 321 322## UIExtensionContentSession.startAbilityForResult 323 324startAbilityForResult(want: Want, options?: StartOptions): Promise<AbilityResult>; 325 326Starts an ability. This API uses a promise to return the result to the caller after the ability is terminated. An ability can be terminated in the following ways: 327 - Normally, you can call [terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult) to terminate the ability. The result is returned to the caller. 328 - If an exception occurs, for example, the ability is killed, an error message, in which **resultCode** is **-1**, is returned to the caller. 329 - 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. 330 331Observe the following when using this API: 332 - The application where the UIExtensionComponent is located must be running in the foreground and gain focus. 333 - 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. 334 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 335 - 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). 336 337**System capability**: SystemCapability.Ability.AbilityRuntime.Core 338 339**System API**: This is a system API and cannot be called by third-party applications. 340 341**Parameters** 342 343| Name| Type| Mandatory| Description| 344| -------- | -------- | -------- | -------- | 345| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 346| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| 347 348 349**Return value** 350 351| Type| Description| 352| -------- | -------- | 353| Promise<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Promise used to return the result.| 354 355**Error codes** 356 357| ID| Error Message| 358| ------- | -------------------------------- | 359| 16000001 | The specified ability does not exist. | 360| 16000002 | Incorrect ability type. | 361| 16000004 | Can not start invisible component. | 362| 16000005 | The specified process does not have the permission. | 363| 16000006 | Cross-user operations are not allowed. | 364| 16000008 | The crowdtesting application expires. | 365| 16000009 | An ability cannot be started or stopped in Wukong mode. | 366| 16000010 | The call with the continuation flag is forbidden. | 367| 16000011 | The context does not exist. | 368| 16000012 | The application is controlled. | 369| 16000013 | The application is controlled by EDM. | 370| 16000050 | Internal error. | 371| 16000053 | The ability is not on the top of the UI. | 372| 16000055 | Installation-free timed out. | 373| 16200001 | The caller has been released. | 374 375For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 376 377## UIExtensionContentSession.terminateSelf 378 379terminateSelf(callback: AsyncCallback<void>): void; 380 381Stops the window object corresponding to this **UIExtensionContentSession** instance. This API uses an asynchronous callback to return the result. 382 383**System capability**: SystemCapability.Ability.AbilityRuntime.Core 384 385**Parameters** 386 387| Name| Type| Mandatory| Description| 388| -------- | -------- | -------- | -------- | 389| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 390 391## UIExtensionContentSession.terminateSelf 392 393terminateSelf(): Promise<void>; 394 395Stops the window object corresponding to this **UIExtensionContentSession** instance. This API uses a promise to return the result. 396 397**System capability**: SystemCapability.Ability.AbilityRuntime.Core 398 399**Return value** 400 401| Type| Description| 402| -------- | -------- | 403| Promise<void> | Promise used to return the result.| 404 405## UIExtensionContentSession.terminateSelfWithResult 406 407terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void; 408 409Stops the window object corresponding to this **UIExtensionContentSession** instance and returns the result to the UIExtensionComponent. This API uses an asynchronous callback to return the result. 410 411**System capability**: SystemCapability.Ability.AbilityRuntime.Core 412 413**Parameters** 414 415| Name| Type| Mandatory| Description| 416| -------- | -------- | -------- | -------- | 417| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | Yes| Result returned to the UIExtensionComponent.| 418| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 419 420## UIExtensionContentSession.terminateSelfWithResult 421 422terminateSelfWithResult(parameter: AbilityResult): Promise<void>; 423 424Stops the window object corresponding to this **UIExtensionContentSession** instance and returns the result to the UIExtensionComponent. This API uses a promise to return the result. 425 426**System capability**: SystemCapability.Ability.AbilityRuntime.Core 427 428**Parameters** 429 430| Name| Type| Mandatory| Description| 431| -------- | -------- | -------- | -------- | 432| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | Yes| Result returned to the UIExtensionComponent.| 433 434**Return value** 435 436| Type| Description| 437| -------- | -------- | 438| Promise<void> | Promise used to return the result.| 439 440## UIExtensionContentSession.setWindowBackgroundColor 441 442setWindowBackgroundColor(color: string): void 443 444Sets the background color for the loading page of the UIExtensionAbility. This API must be used after [loadContent()](#uiextensioncontentsessionloadcontent) takes effect. 445 446**System capability**: SystemCapability.Ability.AbilityRuntime.Core 447 448**System API**: This is a system API and cannot be called by third-party applications. 449 450**Parameters** 451 452| Name| Type| Mandatory| Description| 453| -------- | -------- | -------- | -------- | 454| color | string | Yes| Background color to set. The value is a hexadecimal RGB or ARGB color code and is case insensitive, for example, **#00FF00** or **#FF00FF00**.| 455 456**Error codes** 457 458| ID| Error Message| 459| ------- | -------------------------------- | 460| 16000050 | Internal error. | 461 462For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 463 464## UIExtensionContentSession.setWindowPrivacyMode 465 466setWindowPrivacyMode(isPrivacyMode: boolean): Promise<void> 467 468Sets whether the window is in privacy mode. This API uses a promise to return the result. A window in privacy mode cannot be captured or recorded. 469 470**System capability**: SystemCapability.Ability.AbilityRuntime.Core 471 472**Required permissions**: ohos.permission.PRIVACY_WINDOW 473 474**Parameters** 475 476| Name| Type| Mandatory| Description| 477| ------------- | ------- | -- | ----------------------------------------------------- | 478| isPrivacyMode | boolean | Yes| Whether the window is in privacy mode. The value **true** means that the window is in privacy mode, and **false** means the opposite.| 479 480**Return value** 481 482| Type| Description| 483| ------------------- | ------------------------ | 484| Promise<void> | Promise that returns no value.| 485 486## UIExtensionContentSession.setWindowPrivacyMode 487 488setWindowPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void 489 490Sets whether the window is in privacy mode. This API uses an asynchronous callback to return the result. A window in privacy mode cannot be captured or recorded. 491 492**System capability**: SystemCapability.Ability.AbilityRuntime.Core 493 494**Required permissions**: ohos.permission.PRIVACY_WINDOW 495 496**Parameters** 497 498| Name| Type| Mandatory| Description| 499| ------------- | ------------------------- | -- | ------------------------------------------------------ | 500| isPrivacyMode | boolean | Yes| Whether the window is in privacy mode. The value **true** means that the window is in privacy mode, and **false** means the opposite. | 501| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 502