harmony 鸿蒙@ohos.app.ability.UIExtensionContentSession (带界面扩展能力界面操作类)

  • 2025-06-12
  • 浏览 (4)

@ohos.app.ability.UIExtensionContentSession (带界面扩展能力界面操作类)

UIExtensionContentSession是UIExtensionAbility加载界面内容时创建的实例对象，当UIExtensionComponent控件拉起指定的UIExtensionAbility时，UIExtensionAbility会创建UIExtensionContentSession对象，并通过onSessionCreate回调传递给开发者。一个UIExtensionComponent控件对应一个UIExtensionContentSession对象，提供界面加载，结果通知等方法。每个UIExtensionAbility的UIExtensionContentSession之间互不影响，可以各自进行操作。

说明：

本模块首批接口从API version 10 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

本模块接口仅可在Stage模型下使用。

导入模块

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

UIExtensionContentSession

loadContent

loadContent(path: string, storage?: LocalStorage): void

为当前UIExtensionComponent控件对应的窗口加载与LocalStorage相关联的具体页面内容。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名 类型 必填 说明
path string 是 设置加载页面的路径。
storage LocalStorage 否 存储单元，为应用程序范围内的可变状态属性和非可变状态属性提供存储。默认为空。

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
16000050 Internal error.

示例：

// UIExtensionAbility不支持三方应用直接继承，故以派生类ShareExtensionAbility举例说明。
import { UIExtensionContentSession, ShareExtensionAbility, Want } from '@kit.AbilityKit';

export default class ShareExtAbility extends ShareExtensionAbility {
  // ...

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

  // ...
}

loadContentByName18+

loadContentByName(name: string, storage?: LocalStorage): void

为UIExtensionAbility加载命名路由页面，支持通过LocalStorage传递状态属性给被加载的页面。该接口用于开发者在UIExtensionAbility的onSessionCreate生命周期加载命名路由页面。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名 类型 必填 说明
name string 是 命名路由页面的名称。
storage LocalStorage 否 页面级UI状态存储单元，用于为加载的的页面传递状态属性，默认值为空。

错误码：

以下错误码详细介绍请参考元能力子系统错误码。

错误码ID 错误信息
16000050 Internal error.

示例：

UIExtensionAbility的实现：

// 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加载的命名路由页面的实现：

// “./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<UIExtensionContentSession>('session');

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

terminateSelf

terminateSelf(callback: AsyncCallback&lt;void&gt;): void

停止UIExtensionContentSession对应的窗口界面对象。使用callback异步回调。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名 类型 必填 说明
callback AsyncCallback&lt;void&gt; 是 回调函数。当停止UIExtensionContentSession对应的窗口界面对象成功，err为undefined，否则为错误对象。

错误码：

以下错误码详细介绍请参考通用错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

示例：

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<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(`Succeeded in terminating self.`);
          });

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

terminateSelf

terminateSelf(): Promise&lt;void&gt;

停止UIExtensionContentSession对应的窗口界面对象。使用Promise异步回调。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

返回值：

类型 说明
Promise&lt;void&gt; Promise对象。无返回结果的Promise对象。

示例：

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<UIExtensionContentSession>('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&lt;void&gt;): void

停止UIExtensionContentSession对应的窗口界面对象，并将结果返回给UIExtensionComponent控件。使用callback异步回调。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名 类型 必填 说明
parameter AbilityResult 是 返回给UIExtensionComponent控件的信息。
callback AsyncCallback&lt;void&gt; 是 回调函数。当停止成功，err为undefined，否则为错误对象。

错误码：

以下错误码详细介绍请参考通用错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

示例：

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<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(`Succeeded in terminating self with result.`);
          });

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

terminateSelfWithResult

terminateSelfWithResult(parameter: AbilityResult): Promise&lt;void&gt;

停止UIExtensionContentSession对应的窗口界面对象，并将结果返回给UIExtensionComponent控件。使用Promise异步回调。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名 类型 必填 说明
parameter AbilityResult 是 返回给UIExtensionComponent控件的信息。

返回值：

类型 说明
Promise&lt;void&gt; Promise对象。无返回结果的Promise对象。

错误码：

以下错误码详细介绍请参考通用错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

示例：

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<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(`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&lt;void&gt;

设置窗口是否为隐私模式。设置为隐私模式的窗口，窗口内容将无法被截屏或录屏。使用Promise异步回调。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

需要权限：ohos.permission.PRIVACY_WINDOW

参数：

|参数名|类型|必填|说明| |————-|——-|–|—————————————————–| |isPrivacyMode|boolean|是|窗口是否为隐私模式。true表示模式开启；false表示模式关闭。|

返回值：

类型 说明
Promise&lt;void&gt; Promise对象。无返回结果的Promise对象。

错误码：

以下错误码详细介绍请参考通用错误码。

错误码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.

示例：

// 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&lt;void&gt;): void

设置窗口是否为隐私模式。设置为隐私模式的窗口，窗口内容将无法被截屏或录屏。使用callback异步回调。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

需要权限：ohos.permission.PRIVACY_WINDOW

参数：

|参数名|类型|必填|说明| |————-|————————-|–|——————————————————| |isPrivacyMode|boolean |是|窗口是否为隐私模式。true表示模式开启；false表示模式关闭。| |callback |AsyncCallback&lt;void&gt;|是|回调函数。当设置成功，err为undefined，否则为错误对象。|

错误码：

以下错误码详细介绍请参考通用错误码。

错误码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.

示例：

// 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>): void

通过type隐式启动UIExtensionAbility。使用callback异步回调。仅支持处于前台的应用调用。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名 类型 必填 说明
type string 是 显示拉起的UIExtensionAbility类型，取值详见通过startAbilityByType接口拉起垂类面板。
wantParam Record 是 表示扩展参数。
abilityStartCallback AbilityStartCallback 是 回调函数，返回启动失败后的详细错误信息。
callback AsyncCallback<void> 是 回调函数。当启动Ability成功，err为undefined，否则为错误对象。

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
16000050 Internal error.

示例：

// 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<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(`Succeeded in startAbilityByType`);
    });
  }

  // ...
}

startAbilityByType11+

startAbilityByType(type: string, wantParam: Record, abilityStartCallback: AbilityStartCallback): Promise<void>

通过type隐式启动UIExtensionAbility。使用Promise异步回调。仅支持处于前台的应用调用。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名 类型 必填 说明
type string 是 显示拉起的UIExtensionAbility类型，取值详见通过startAbilityByType接口拉起垂类面板。
wantParam Record 是 表示扩展参数。
abilityStartCallback AbilityStartCallback 是 回调函数，返回启动失败后的详细错误信息。

返回值：

类型 说明
Promise<void> Promise对象。无返回结果的Promise对象。

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
16000050 Internal error.

示例：

// 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<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(`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 返回UIExtension的窗口代理。

错误码：

以下错误码详细介绍请参考元能力子系统错误码。

错误码ID 错误信息
16000050 Internal error.

示例：

// 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<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%')
  }
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Ability Kit（程序框架服务）

harmony 鸿蒙AbilityBase

harmony 鸿蒙AbilityBase_Element

harmony 鸿蒙AbilityRuntime

harmony 鸿蒙bundle

harmony 鸿蒙OH_NativeBundle_ApplicationInfo

harmony 鸿蒙OH_NativeBundle_ElementName

harmony 鸿蒙ability_base_common.h

harmony 鸿蒙ability_runtime_common.h

harmony 鸿蒙application_context.h

0  赞
  • 所属分类： 后端技术
  • 本文标签：
  • 版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/RsbLDT
热门推荐
标签云
Linux Java Spring Spring Boot docker 大数据 前端 生活 maven golang 软件 spring cloud fintech mac vscode 其他 区块链 以太坊 V神 开发者 技术 股票 git greenplum 分布式事务 chrome mysql flink kafka 设计模式 原理 鸿蒙 seo
最新文章
本文目录