wusongqingUpdate docs against 64604+64450+64575+64646+64108+63934+63780+63091+63807+63718+63472+61863+62337+62148+62113+61920+61864+62078+61392+61971+61895+61782+61780+61549+61673+60999+61417+61173+64604+64788+64774+64575+64616+64390

e46b2c1a创建于 2024年12月3日历史提交

@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 '@kit.AbilityKit';

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

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
16000050	Internal error.

Example

import { UIExtensionContentSession, UIExtensionAbility, Want } from '@kit.AbilityKit';

export default class UIExtAbility extends UIExtensionAbility {
  // ...

  onSessionCreate(want: Want, session: UIExtensionContentSession): void {
    let storage: LocalStorage = new LocalStorage();
    storage.setOrCreate('session', session);
    session.loadContent('pages/Extension', storage);
  }

  // ...
}

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.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { UIExtensionContentSession } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let storage = LocalStorage.getShared();

@Entry(storage)
@Component
struct Index {
  private session: UIExtensionContentSession | undefined =
    storage.get<UIExtensionContentSession>('session');

  build() {
    RelativeContainer() {
      Button('TerminateSelf')
        .onClick(() => {
          this.session?.terminateSelf((err: BusinessError) => {
            if (err) {
              console.error(`Failed to terminate self, code: ${err.code}, msg: ${err.message}`);
              return;
            }
            console.info(`Successed in terminating self.`);
          });

          storage.clear();
        })
    }
    .height('100%')
    .width('100%')
  }
}

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.

Example

import { UIExtensionContentSession } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let storage = LocalStorage.getShared();

@Entry(storage)
@Component
struct Index {
  private session: UIExtensionContentSession | undefined =
    storage.get<UIExtensionContentSession>('session');

  build() {
    RelativeContainer() {
      Button('TerminateSelf')
        .onClick(() => {
          this.session?.terminateSelf()
            .then(() => {
              console.info(`Successed in terminating self.`);
            })
            .catch((err: BusinessError) => {
              console.error(`Failed to terminate self, code: ${err.code}, msg: ${err.message}`);
            });

          storage.clear();
        })
    }
    .height('100%')
    .width('100%')
  }
}

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.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { UIExtensionContentSession, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let storage = LocalStorage.getShared();

@Entry(storage)
@Component
struct Index {
  private session: UIExtensionContentSession | undefined =
    storage.get<UIExtensionContentSession>('session');

  build() {
    RelativeContainer() {
      Button('TerminateSelfWithResult')
        .onClick(() => {
          let abilityResult: common.AbilityResult = {
            resultCode: 0,
            want: {
              bundleName: 'com.ohos.uiextensioncontentsession',
              parameters: {
                'result': 123456
              }
            }
          };

          this.session?.terminateSelfWithResult(abilityResult, (err: BusinessError) => {
            if (err) {
              console.error(`Failed to terminate self with result, code: ${err.code}, msg: ${err.message}`);
              return;
            }
            console.info(`Successed in terminating self with result.`);
          });

          storage.clear();
        })
    }
    .height('100%')
    .width('100%')
  }
}

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.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { UIExtensionContentSession, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let storage = LocalStorage.getShared();

@Entry(storage)
@Component
struct Index {
  private session: UIExtensionContentSession | undefined =
    storage.get<UIExtensionContentSession>('session');

  build() {
    RelativeContainer() {
      Button('TerminateSelfWithResult')
        .onClick(() => {
          let abilityResult: common.AbilityResult = {
            resultCode: 0,
            want: {
              bundleName: 'com.ohos.uiextensioncontentsession',
              parameters: {
                'result': 123456
              }
            }
          };

          this.session?.terminateSelfWithResult(abilityResult)
            .then(() => {
              console.info(`Successed in terminating self with result.`);
            })
            .catch((err: BusinessError) => {
              console.error(`Failed to terminate self with result, code: ${err.code}, msg: ${err.message}`);
            });

          storage.clear();
        })
    }
    .height('100%')
    .width('100%')
  }
}

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.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { UIExtensionContentSession, UIExtensionAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class UIExtAbility extends UIExtensionAbility {
  // ...

  onSessionCreate(want: Want, session: UIExtensionContentSession): void {
    let isPrivacyMode: boolean = true;
    try {
      session.setWindowPrivacyMode(isPrivacyMode)
        .then(() => {
          console.info(`Successed in setting window to privacy mode.`);
        })
        .catch((err: BusinessError) => {
          console.error(`Failed to set window to privacy mode, code: ${err.code}, msg: ${err.message}`);
        });
    } catch (e) {
      let code = (e as BusinessError).code;
      let msg = (e as BusinessError).message;
      console.error(`Failed to set window to privacy mode, code: ${code}, msg: ${msg}`);
    }
  }

  // ...
}

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.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { UIExtensionContentSession, UIExtensionAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class UIExtAbility extends UIExtensionAbility {
  // ...

  onSessionCreate(want: Want, session: UIExtensionContentSession): void {
    let isPrivacyMode: boolean = true;
    try {
      session.setWindowPrivacyMode(isPrivacyMode, (err: BusinessError) => {
        if (err) {
          console.error(`Failed to set window to privacy mode, code: ${err.code}, msg: ${err.message}`);
          return;
        }
        console.info(`Successed in setting window to privacy mode.`);
      });
    } catch (e) {
      let code = (e as BusinessError).code;
      let msg = (e as BusinessError).message;
      console.error(`Failed to set window to privacy mode, code: ${code}, msg: ${msg}`);
    }
  }

  // ...
}

UIExtensionContentSession.startAbilityByType¹¹⁺

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. It can be called only by applications running in the foreground.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Type of the UIExtensionAbility to start. For details, see Starting an Application of the Specified Type.
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

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
16000050	Internal error.

Example

import { UIExtensionContentSession, UIExtensionAbility, Want, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class UIExtAbility extends UIExtensionAbility {
  // ...

  onSessionCreate(want: Want, session: UIExtensionContentSession): void {
    let wantParams: Record<string, Object> = {
      'sceneType': 1
    };
    let abilityStartCallback: common.AbilityStartCallback = {
      onError: (code: number, name: string, message: string) => {
        console.error(`onError, code: ${code}, name: ${name}, msg: ${message}`);
      },
      onResult: (result: common.AbilityResult) => {
        console.info(`onResult, result: ${JSON.stringify(result)}`);
      }
    };

    session.startAbilityByType('test', wantParams, abilityStartCallback, (err: BusinessError) => {
      if (err) {
        console.error(`Failed to startAbilityByType, code: ${err.code}, msg: ${err.message}`);
        return;
      }
      console.info(`Successed in startAbilityByType`);
    });
  }

  // ...
}

UIExtensionContentSession.startAbilityByType¹¹⁺

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. It can be called only by applications running in the foreground.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Type of the UIExtensionAbility to start. For details, see Starting an Application of the Specified Type.
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

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
16000050	Internal error.

Example

import { UIExtensionContentSession, UIExtensionAbility, Want, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class UIExtAbility extends UIExtensionAbility {
  // ...

  onSessionCreate(want: Want, session: UIExtensionContentSession): void {
    let wantParams: Record<string, Object> = {
      'sceneType': 1
    };
    let abilityStartCallback: common.AbilityStartCallback = {
      onError: (code: number, name: string, message: string) => {
        console.error(`onError, code: ${code}, name: ${name}, msg: ${message}`);
      },
      onResult: (result: common.AbilityResult) => {
        console.info(`onResult, result: ${JSON.stringify(result)}`);
      }
    };

    session.startAbilityByType('test', wantParams, abilityStartCallback)
      .then(() => {
        console.info(`Successed in startAbilityByType`);
      })
      .catch((err: BusinessError) => {
        console.error(`Failed to startAbilityByType, code: ${err.code}, msg: ${err.message}`);
      });
  }

  // ...
}

UIExtensionContentSession.getUIExtensionWindowProxy¹²⁺

getUIExtensionWindowProxy(): uiExtension.WindowProxy

Obtains the window proxy of this UIExtensionAbility.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Return value

Type	Description
uiExtension.WindowProxy	Window proxy.

Error codes

For details about the error codes, see Ability Error Codes.

ID	Error Message
16000050	Internal error.

Example

// Index.ets
import { UIExtensionContentSession } from '@kit.AbilityKit';
import uiExtension from '@ohos.arkui.uiExtension';

let storage = LocalStorage.getShared();

@Entry(storage)
@Component
struct Extension {
  @State message: string = 'EmbeddedUIExtensionAbility Index';
  private session: UIExtensionContentSession | undefined = storage.get<UIExtensionContentSession>('session');
  private extensionWindow: uiExtension.WindowProxy | undefined = this.session?.getUIExtensionWindowProxy();

  aboutToAppear(): void {
    this.extensionWindow?.on('windowSizeChange', (size) => {
      console.info(`size = ${JSON.stringify(size)}`);
    });
    this.extensionWindow?.on('avoidAreaChange', (info) => {
      console.info(`type = ${JSON.stringify(info.type)}, area = ${JSON.stringify(info.area)}`);
    });
  }

  aboutToDisappear(): void {
    this.extensionWindow?.off('windowSizeChange');
    this.extensionWindow?.off('avoidAreaChange');
  }

  build() {
    Column() {
      Text(this.message)
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
    }
    .width('100%')
  }
}

@ohos.app.ability.UIExtensionContentSession (UI Operation Class for ExtensionAbilities with UI)

Modules to Import

UIExtensionContentSession.loadContent

UIExtensionContentSession.terminateSelf

UIExtensionContentSession.terminateSelf

UIExtensionContentSession.terminateSelfWithResult

UIExtensionContentSession.terminateSelfWithResult

UIExtensionContentSession.setWindowPrivacyMode

UIExtensionContentSession.setWindowPrivacyMode

UIExtensionContentSession.startAbilityByType11+

UIExtensionContentSession.startAbilityByType11+

UIExtensionContentSession.getUIExtensionWindowProxy12+

UIExtensionContentSession.startAbilityByType¹¹⁺

UIExtensionContentSession.startAbilityByType¹¹⁺

UIExtensionContentSession.getUIExtensionWindowProxy¹²⁺