# @ohos.app.ability.UIExtensionContentSession (UIExtensionAbility界面操作类) UIExtensionContentSession是[UIExtensionAbility](js-apis-app-ability-uiExtensionAbility.md)组件的界面操作类,提供页面加载、设置宿主应用(UIExtensionAbility组件的拉起方)窗口隐私模式等功能。当宿主应用拉起指定的UIExtensionAbility组件时,系统创建UIExtensionContentSession对象,并通过[onSessionCreate](js-apis-app-ability-uiExtensionAbility.md#onsessioncreate)回调传递给开发者。一个UIExtensionAbility组件对应一个UIExtensionContentSession对象,每个UIExtensionAbility组件的UIExtensionContentSession对象之间互不影响。 > **说明:** > > 本模块首批接口从API version 10 开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 > > 本模块接口仅可在Stage模型下使用。 ## 导入模块 ```ts import { UIExtensionContentSession } from '@kit.AbilityKit'; ``` ## UIExtensionContentSession UIExtensionAbility组件的界面操作类,提供页面加载、设置宿主应用窗口隐私模式等功能。 ### loadContent loadContent(path: string, storage?: LocalStorage): void 为[UIExtensionAbility](./js-apis-app-ability-uiExtensionAbility.md)组件加载页面,支持通过[LocalStorage](../../ui/state-management/arkts-localstorage.md)传递状态属性给被加载的页面。该接口用于开发者在UIExtensionAbility组件的[onSessionCreate](./js-apis-app-ability-uiExtensionAbility.md#onsessioncreate)生命周期中加载页面。 **系统能力**:SystemCapability.Ability.AbilityRuntime.Core **参数:** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | path | string | 是 | 要加载的页面所在的路径,该路径通过[module.json5配置文件](../../quick-start/module-configuration-file.md)中的[pages标签](../../quick-start/module-configuration-file.md#pages标签)配置。 | | storage | [LocalStorage](../../ui/state-management/arkts-localstorage.md) | 否 | 页面级UI状态存储单元,开发者可通过该参数为加载的页面传递状态属性。 | **错误码:** 以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 | 错误码ID | 错误信息 | | -------- | -------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 16000050 | Internal error. | **示例:** ```ts // UIExtensionAbility组件不支持三方应用直接继承,故以派生类ShareExtensionAbility举例说明。 import { UIExtensionContentSession, ShareExtensionAbility, Want } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; export default class ShareExtAbility extends ShareExtensionAbility { // ... onSessionCreate(want: Want, session: UIExtensionContentSession): void { try { let storage: LocalStorage = new LocalStorage(); storage.setOrCreate('session', session); session.loadContent('pages/Extension', storage); } catch (error) { let code = (error as BusinessError).code; let message = (error as BusinessError).message; console.error(`Failed to load content, code: ${code}, msg: ${message}`); } } // ... } ``` ### loadContentByName18+ loadContentByName(name: string, storage?: LocalStorage): void 为[UIExtensionAbility](./js-apis-app-ability-uiExtensionAbility.md)组件加载[命名路由](../../ui/arkts-routing.md#命名路由)页面,支持通过[LocalStorage](../../ui/state-management/arkts-localstorage.md)传递状态属性给被加载的页面。该接口用于开发者在UIExtensionAbility组件的[onSessionCreate](./js-apis-app-ability-uiExtensionAbility.md#onsessioncreate)生命周期中加载命名路由页面。 **系统能力**:SystemCapability.Ability.AbilityRuntime.Core **参数:** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ------ | ------ | | name | string | 是 | 命名路由页面的名称。 | | storage | [LocalStorage](../../ui/state-management/arkts-localstorage.md) | 否 | 页面级UI状态存储单元,开发者可通过该参数为加载的页面传递状态属性。 | **错误码:** 以下错误码详细介绍请参考[元能力子系统错误码](errorcode-ability.md)。 | 错误码ID | 错误信息 | | ------ | ------ | | 16000050 | Internal error. | **示例:** UIExtensionAbility组件的实现: ```ts // UIExtensionAbility组件不支持三方应用直接继承,故以派生类ShareExtensionAbility举例说明。 import { UIExtensionContentSession, ShareExtensionAbility, Want } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; import './pages/UIExtensionPage'; // 导入命名路由页面,示例代码以“./pages/UIExtensionPage.ets”文件为例,在实际代码开发过程中修改为真实路径和文件名称。 export default class ShareExtAbility extends ShareExtensionAbility { // 其他生命周期和实现 onSessionCreate(want: Want, session: UIExtensionContentSession): void { let storage: LocalStorage = new LocalStorage(); storage.setOrCreate('session', session); let name: string = 'UIExtPage'; // 命名路由页面的名字。 try { session.loadContentByName(name, storage); } catch (error) { let code = (error as BusinessError).code; let message = (error as BusinessError).message; console.error(`Failed to load content by name ${name}, code: ${code}, msg: ${message}`); } } // 其他生命周期和实现 } ``` UIExtensionAbility组件加载的命名路由页面的实现: ```ts // “./pages/UIExtensionPage.ets”文件的实现。 import { UIExtensionContentSession } from '@kit.AbilityKit'; @Entry({ routeName: 'UIExtPage' }) // 通过“routeName”定义命名路由页面的名字。 @Component struct UIExtensionPage { @State message: string = 'Hello world'; storage: LocalStorage | undefined = this.getUIContext().getSharedLocalStorage(); private session: UIExtensionContentSession | undefined = this.storage?.get('session'); build() { Row() { Column() { Text(this.message) .fontSize(20) .fontWeight(FontWeight.Bold) } .width('100%') } .height('100%') } } ``` ### terminateSelf terminateSelf(callback: AsyncCallback<void>): void 销毁UIExtensionAbility组件自身,同时关闭对应的宿主应用窗口界面。使用callback异步回调。 **系统能力**:SystemCapability.Ability.AbilityRuntime.Core **参数:** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | callback | AsyncCallback<void> | 是 | 回调函数。当接口调用成功,err为undefined,否则为错误对象。 | **错误码:** 以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | **示例:** ```ts import { UIExtensionContentSession } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry() @Component struct Index { storage: LocalStorage | undefined = this.getUIContext().getSharedLocalStorage(); private session: UIExtensionContentSession | undefined = this.storage?.get('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(`Succeeded in terminating self.`); }); this.storage?.clear(); }) } .height('100%') .width('100%') } } ``` ### terminateSelf terminateSelf(): Promise<void> 销毁UIExtensionAbility组件自身,同时关闭对应的宿主应用窗口界面。使用Promise异步回调。 **系统能力**:SystemCapability.Ability.AbilityRuntime.Core **返回值:** | 类型 | 说明 | | -------- | -------- | | Promise<void> | Promise对象,无返回结果。 | **示例:** ```ts import { UIExtensionContentSession } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry() @Component struct Index { storage: LocalStorage | undefined = this.getUIContext().getSharedLocalStorage(); private session: UIExtensionContentSession | undefined = this.storage?.get('session'); build() { RelativeContainer() { Button('TerminateSelf') .onClick(() => { this.session?.terminateSelf() .then(() => { console.info(`Succeeded in terminating self.`); }) .catch((err: BusinessError) => { console.error(`Failed to terminate self, code: ${err.code}, msg: ${err.message}`); }); this.storage?.clear(); }) } .height('100%') .width('100%') } } ``` ### terminateSelfWithResult terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void 销毁UIExtensionAbility组件自身,关闭对应的宿主应用窗口界面,并将结果返回给宿主应用。使用callback异步回调。 **系统能力**:SystemCapability.Ability.AbilityRuntime.Core **参数:** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | 是 | 返回给宿主应用的信息。 | | callback | AsyncCallback<void> | 是 | 回调函数。当接口调用成功,err为undefined,否则为错误对象。 | **错误码:** 以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | **示例:** ```ts import { UIExtensionContentSession, common } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry() @Component struct Index { storage: LocalStorage | undefined = this.getUIContext().getSharedLocalStorage(); private session: UIExtensionContentSession | undefined = this.storage?.get('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(`Succeeded in terminating self with result.`); }); this.storage?.clear(); }) } .height('100%') .width('100%') } } ``` ### terminateSelfWithResult terminateSelfWithResult(parameter: AbilityResult): Promise<void> 销毁UIExtensionAbility组件自身,关闭对应的宿主应用窗口界面,并将结果返回给宿主应用。使用Promise异步回调。 **系统能力**:SystemCapability.Ability.AbilityRuntime.Core **参数:** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | 是 | 返回给宿主应用的信息。 | **返回值:** | 类型 | 说明 | | -------- | -------- | | Promise<void> | Promise对象,无返回结果。 | **错误码:** 以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 | 错误码ID | 错误信息 | | ------- | -------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | **示例:** ```ts import { UIExtensionContentSession, common } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry() @Component struct Index { storage: LocalStorage | undefined = this.getUIContext().getSharedLocalStorage(); private session: UIExtensionContentSession | undefined = this.storage?.get('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(`Succeeded in terminating self with result.`); }) .catch((err: BusinessError) => { console.error(`Failed to terminate self with result, code: ${err.code}, msg: ${err.message}`); }); this.storage?.clear(); }) } .height('100%') .width('100%') } } ``` ### setWindowPrivacyMode setWindowPrivacyMode(isPrivacyMode: boolean): Promise<void> 设置宿主应用窗口的隐私模式开启或关闭。设置为隐私模式的窗口,窗口内容将无法被截屏或录屏。使用Promise异步回调。 **系统能力**:SystemCapability.Ability.AbilityRuntime.Core **需要权限**:ohos.permission.PRIVACY_WINDOW **参数:** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | isPrivacyMode | boolean | 是 | 表示是否开启隐私模式。true表示开启;false表示关闭。 | **返回值:** | 类型 | 说明 | | -------- | -------- | | Promise<void> | Promise对象,无返回结果。 | **错误码:** 以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 | 错误码ID | 错误信息 | | -------- | -------- | | 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. | **示例:** ```ts // UIExtensionAbility组件不支持三方应用直接继承,故以派生类ShareExtensionAbility举例说明。 import { UIExtensionContentSession, ShareExtensionAbility, Want } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; export default class ShareExtAbility extends ShareExtensionAbility { // ... onSessionCreate(want: Want, session: UIExtensionContentSession): void { let isPrivacyMode: boolean = true; try { session.setWindowPrivacyMode(isPrivacyMode) .then(() => { console.info(`Succeeded 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}`); } } // ... } ``` ### setWindowPrivacyMode setWindowPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void 设置宿主应用窗口的隐私模式开启或关闭。设置为隐私模式的窗口,窗口内容将无法被截屏或录屏。使用callback异步回调。 **系统能力**:SystemCapability.Ability.AbilityRuntime.Core **需要权限**:ohos.permission.PRIVACY_WINDOW **参数:** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | isPrivacyMode | boolean | 是 | 表示是否开启隐私模式。true表示开启;false表示关闭。 | | callback | AsyncCallback<void> | 是 | 回调函数。当设置成功,err为undefined,否则为错误对象。 | **错误码:** 以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 | 错误码ID | 错误信息 | | -------- | -------- | | 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. | **示例:** ```ts // UIExtensionAbility组件不支持三方应用直接继承,故以派生类ShareExtensionAbility举例说明。 import { UIExtensionContentSession, ShareExtensionAbility, Want } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; export default class ShareExtAbility extends ShareExtensionAbility { // ... 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(`Succeeded 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}`); } } // ... } ``` ### startAbilityByType11+ startAbilityByType(type: string, wantParam: Record, abilityStartCallback: AbilityStartCallback, callback: AsyncCallback\): void 通过type隐式启动UIExtensionAbility。使用callback异步回调。仅支持处于前台的应用调用。 **系统能力**:SystemCapability.Ability.AbilityRuntime.Core **参数:** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | type | string | 是 | UIExtensionAbility组件类型,取值详见[通过startAbilityByType接口拉起垂类面板](../../application-models/start-intent-panel.md#匹配规则)。 | | wantParam | Record | 是 | 表示启动UIExtensionAbility组件时传递的参数。 | | abilityStartCallback | [AbilityStartCallback](js-apis-inner-application-abilityStartCallback.md) | 是 | 表示启动UIExtensionAbility组件的执行结果。 | | callback | AsyncCallback\ | 是 | 回调函数。当接口调用成功,err为undefined,否则为错误对象。 | **错误码:** 以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 | 错误码ID | 错误信息 | | -------- | -------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 16000050 | Internal error. | **示例:** ```ts // UIExtensionAbility组件不支持三方应用直接继承,故以派生类ShareExtensionAbility举例说明。 import { UIExtensionContentSession, ShareExtensionAbility, Want, common } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; export default class ShareExtAbility extends ShareExtensionAbility { // ... onSessionCreate(want: Want, session: UIExtensionContentSession): void { let wantParams: Record = { '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('navigation', wantParams, abilityStartCallback, (err: BusinessError) => { if (err) { console.error(`Failed to startAbilityByType, code: ${err.code}, msg: ${err.message}`); return; } console.info(`Succeeded in startAbilityByType`); }); } // ... } ``` ### startAbilityByType11+ startAbilityByType(type: string, wantParam: Record, abilityStartCallback: AbilityStartCallback): Promise\ 通过type隐式启动UIExtensionAbility组件。使用Promise异步回调。仅支持处于前台的应用调用。 **系统能力**:SystemCapability.Ability.AbilityRuntime.Core **参数:** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | type | string | 是 | UIExtensionAbility组件类型,取值详见[通过startAbilityByType接口拉起垂类面板](../../application-models/start-intent-panel.md#匹配规则)。 | | wantParam | Record | 是 | 表示启动UIExtensionAbility组件时传递的参数。 | | abilityStartCallback | [AbilityStartCallback](js-apis-inner-application-abilityStartCallback.md) | 是 | 表示启动UIExtensionAbility组件的执行结果。 | **返回值:** | 类型 | 说明 | | -------- | -------- | | Promise\ | Promise对象,无返回结果。 | **错误码:** 以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 | 错误码ID | 错误信息 | | -------- | -------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 16000050 | Internal error. | **示例:** ```ts // UIExtensionAbility组件不支持三方应用直接继承,故以派生类ShareExtensionAbility举例说明。 import { UIExtensionContentSession, ShareExtensionAbility, Want, common } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; export default class ShareExtAbility extends ShareExtensionAbility { // ... onSessionCreate(want: Want, session: UIExtensionContentSession): void { let wantParams: Record = { '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(`Succeeded in startAbilityByType`); }) .catch((err: BusinessError) => { console.error(`Failed to startAbilityByType, code: ${err.code}, msg: ${err.message}`); }); } // ... } ``` ### getUIExtensionWindowProxy12+ getUIExtensionWindowProxy(): uiExtension.WindowProxy 获取UIExtension窗口代理。 **系统能力**:SystemCapability.Ability.AbilityRuntime.Core **返回值:** | 类型 | 说明 | | -------- | -------- | | [uiExtension.WindowProxy](../apis-arkui/js-apis-arkui-uiExtension.md#windowproxy) | UIExtensionAbility组件的宿主应用窗口代理。 | **错误码:** 以下错误码详细介绍请参考[元能力子系统错误码](errorcode-ability.md)。 | 错误码ID | 错误信息 | | -------- | -------- | | 16000050 | Internal error. | **示例:** ```ts // Index.ets import { UIExtensionContentSession } from '@kit.AbilityKit'; import uiExtension from '@ohos.arkui.uiExtension'; @Entry() @Component struct Extension { storage: LocalStorage | undefined = this.getUIContext().getSharedLocalStorage(); @State message: string = 'EmbeddedUIExtensionAbility Index'; private session: UIExtensionContentSession | undefined = this.storage?.get('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%') } } ```