@ohos.app.ability.UIExtensionContentSession (UI Operation Class for ExtensionAbilities with UI)
UIExtensionContentSession is an instance created when the UIExtensionAbility loads UI content. When the UIExtensionComponent starts a UIExtensionAbility, the UIExtensionAbility creates a UIExtensionContentSession instance and returns it through the onSessionCreate 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.
NOTE
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.
The APIs of this module can be used only in the stage model.
Modules to Import
import UIExtensionContentSession from '@ohos.app.ability.UIExtensionContentSession';
UIExtensionContentSession.loadContent
loadContent(path: string, storage?: LocalStorage): void
Loads content from a page associated with a local storage to the window corresponding to the current UIExtensionComponent.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| path | string | Yes | Path of the page from which the content will be loaded. |
| storage | LocalStorage | 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. |
Error codes
| ID | Error Message |
|---|---|
| 16000050 | Internal error. |
For details about the error codes, see Ability Error Codes.
UIExtensionContentSession.terminateSelf
terminateSelf(callback: AsyncCallback<void>): void
Stops the window object corresponding to this UIExtensionContentSession instance. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the window object is stopped, err is undefined; otherwise, err is an error object. |
UIExtensionContentSession.terminateSelf
terminateSelf(): Promise<void>
Stops the window object corresponding to this UIExtensionContentSession instance. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Return value
| Type | Description |
|---|---|
| Promise<void> | Promise that returns no value. |
UIExtensionContentSession.terminateSelfWithResult
terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void
Stops 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.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| parameter | AbilityResult | Yes | Result returned to the UIExtensionComponent. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the window object is stopped, err is undefined; otherwise, err is an error object. |
UIExtensionContentSession.terminateSelfWithResult
terminateSelfWithResult(parameter: AbilityResult): Promise<void>
Stops the window object corresponding to this UIExtensionContentSession instance and returns the result to the UIExtensionComponent. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| parameter | AbilityResult | Yes | Result returned to the UIExtensionComponent. |
Return value
| Type | Description |
|---|---|
| Promise<void> | Promise that returns no value. |
UIExtensionContentSession.setWindowPrivacyMode
setWindowPrivacyMode(isPrivacyMode: boolean): Promise<void>
Sets whether the window is in privacy mode. A window in privacy mode cannot be captured or recorded. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Required permissions: ohos.permission.PRIVACY_WINDOW
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| 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. |
Return value
| Type | Description |
|---|---|
| Promise<void> | Promise that returns no value. |
UIExtensionContentSession.setWindowPrivacyMode
setWindowPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void
Sets whether the window is in privacy mode. A window in privacy mode cannot be captured or recorded. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Required permissions: ohos.permission.PRIVACY_WINDOW
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| 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. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the setting is successful, err is undefined. Otherwise, err is an error object. |
UIExtensionContentSession.startAbilityByType11+
startAbilityByType(type: string, wantParam: Record<string, Object>, abilityStartCallback: AbilityStartCallback, callback: AsyncCallback<void>): void
Implicitly starts a given type of UIExtensionAbility. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| type | string | Yes | Type of the UIExtensionAbility to start. |
| wantParam | Record<string, Object> | Yes | Extended parameter. |
| abilityStartCallback | AbilityStartCallback | Yes | Callback used to return the detailed error information if the startup fails. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the ability is started, err is undefined; otherwise, err is an error object. |
Error codes
| ID | Error Message |
|---|---|
| 16000001 | The specified ability does not exist. |
| 16000002 | Incorrect ability type. |
| 16000004 | Can not start invisible component. |
| 16000050 | Internal error. |
| 16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
UIExtensionContentSession.startAbilityByType11+
startAbilityByType(type: string, wantParam: Record<string, Object>, abilityStartCallback: AbilityStartCallback): Promise<void>
Implicitly starts a given type of UIExtensionAbility. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| type | string | Yes | Type of the UIExtensionAbility to start. |
| wantParam | Record<string, Object> | Yes | Extended parameter. |
| abilityStartCallback | AbilityStartCallback | Yes | Callback used to return the detailed error information if the startup fails. |
Return value
| Type | Description |
|---|---|
| Promise<void> | Promise that returns no value. |
Error codes
| ID | Error Message |
|---|---|
| 16000001 | The specified ability does not exist. |
| 16000002 | Incorrect ability type. |
| 16000004 | Can not start invisible component. |
| 16000050 | Internal error. |
| 16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.