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

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

说明：

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

导入模块

import UIExtensionContentSession from '@ohos.app.ability.UIExtensionContentSession';

UIExtensionContentSession.sendData

sendData(data: { [key: string]: Object }): void

发送数据给UIExtensionComponent控件。

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

系统API：此接口为系统接口，三方应用不支持调用。

参数：

错误码：

错误码详细介绍请参考errcode-ability。

UIExtensionContentSession.setReceiveDataCallback

setReceiveDataCallback(callback: (data: { [key: string]: Object }) => void): void

设置从UIExtensionComponent控件接收数据的回调方法。

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

系统API：此接口为系统接口，三方应用不支持调用。

参数：

错误码：

错误码详细介绍请参考errcode-ability。

UIExtensionContentSession.loadContent

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

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

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

参数：

错误码：

错误码详细介绍请参考errcode-ability。

UIExtensionContentSession.startAbility

startAbility(want: Want, callback: AsyncCallback<void>): void;

启动Ability（callback形式）。

使用规则： - 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。 - 调用方应用位于后台时，使用该接口启动Ability需申请ohos.permission.START_ABILITIES_FROM_BACKGROUND权限。 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请ohos.permission.START_INVISIBLE_ABILITY权限。 - 组件启动规则详见：组件启动规则（Stage模型）。

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

系统API：此接口为系统接口，三方应用不支持调用。

参数：

错误码：

错误码详细介绍请参考errcode-ability。

UIExtensionContentSession.startAbility

startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void;

启动Ability（callback形式）。

使用规则： - 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。 - 调用方应用位于后台时，使用该接口启动Ability需申请ohos.permission.START_ABILITIES_FROM_BACKGROUND权限。 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请ohos.permission.START_INVISIBLE_ABILITY权限。 - 组件启动规则详见：组件启动规则（Stage模型）。

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

系统API：此接口为系统接口，三方应用不支持调用。

参数：

错误码：

错误码详细介绍请参考errcode-ability。

UIExtensionContentSession.startAbility

startAbility(want: Want, options?: StartOptions): Promise<void>;

启动Ability（promise形式）。

使用规则： - 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。 - 调用方应用位于后台时，使用该接口启动Ability需申请ohos.permission.START_ABILITIES_FROM_BACKGROUND权限。 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请ohos.permission.START_INVISIBLE_ABILITY权限。 - 组件启动规则详见：组件启动规则（Stage模型）。

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

系统API：此接口为系统接口，三方应用不支持调用。

参数：

返回值：

错误码：

错误码详细介绍请参考errcode-ability。

UIExtensionContentSession.startAbilityForResult

startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): void;

启动一个Ability，在Ability终止后返回结果给调用方(callback形式)。Ability的终止方式包括以下几种情况: - 正常情况下可通过调用terminateSelfWithResult接口使之终止并且返回结果给调用方。 - 异常情况下比如杀死Ability会返回异常信息给调用方, 异常信息中resultCode为-1。 - 如果被启动的Ability模式是单实例模式, 不同应用多次调用该接口启动这个Ability，当这个Ability调用terminateSelfWithResult接口使之终止时，只将正常结果返回给最后一个调用方, 其它调用方返回异常信息, 异常信息中resultCode为-1。

使用规则： - 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。 - 调用方应用位于后台时，使用该接口启动Ability需申请ohos.permission.START_ABILITIES_FROM_BACKGROUND权限。 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请ohos.permission.START_INVISIBLE_ABILITY权限。 - 组件启动规则详见：组件启动规则（Stage模型）。

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

系统API：此接口为系统接口，三方应用不支持调用。

参数：

错误码：

错误码详细介绍请参考errcode-ability。

UIExtensionContentSession.startAbilityForResult

startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback<AbilityResult>): void;

启动一个Ability，在Ability终止后返回结果给调用方(callback形式)。Ability的终止方式包括以下几种情况: - 正常情况下可通过调用terminateSelfWithResult接口使之终止并且返回结果给调用方。 - 异常情况下比如杀死Ability会返回异常信息给调用方，异常信息中resultCode为-1。 - 如果被启动的Ability模式是单实例模式, 不同应用多次调用该接口启动这个Ability，当这个Ability调用terminateSelfWithResult接口使之终止时，只将正常结果返回给最后一个调用方，其它调用方返回异常信息, 异常信息中resultCode为-1。

使用规则： - 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。 - 调用方应用位于后台时，使用该接口启动Ability需申请ohos.permission.START_ABILITIES_FROM_BACKGROUND权限。 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请ohos.permission.START_INVISIBLE_ABILITY权限。 - 组件启动规则详见：组件启动规则（Stage模型）。

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

系统API：此接口为系统接口，三方应用不支持调用。

参数：

错误码：

错误码详细介绍请参考errcode-ability。

UIExtensionContentSession.startAbilityForResult

startAbilityForResult(want: Want, options?: StartOptions): Promise<AbilityResult>;

启动一个Ability，在Ability终止后返回结果给调用方(promise形式)。Ability的终止方式包括以下几种情况: - 正常情况下可通过调用terminateSelfWithResult接口使之终止并且返回结果给调用方。 - 异常情况下比如杀死Ability会返回异常信息给调用方, 异常信息中resultCode为-1。 - 如果被启动的Ability模式是单实例模式, 不同应用多次调用该接口启动这个Ability，当这个Ability调用terminateSelfWithResult接口使之终止时，只将正常结果返回给最后一个调用方, 其它调用方返回异常信息, 异常信息中resultCode为-1。

使用规则： - 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。 - 调用方应用位于后台时，使用该接口启动Ability需申请ohos.permission.START_ABILITIES_FROM_BACKGROUND权限。 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请ohos.permission.START_INVISIBLE_ABILITY权限。 - 组件启动规则详见：组件启动规则（Stage模型）。

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

系统API：此接口为系统接口，三方应用不支持调用。

参数：

返回值：

错误码：

错误码详细介绍请参考errcode-ability。

UIExtensionContentSession.terminateSelf

terminateSelf(callback: AsyncCallback<void>): void;

停止UIExtensionContentSession对应的窗口界面对象（callback形式）。

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

参数：

UIExtensionContentSession.terminateSelf

terminateSelf(): Promise<void>;

停止UIExtensionContentSession对应的窗口界面对象（promise形式）。

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

返回值：

UIExtensionContentSession.terminateSelfWithResult

terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void;

停止UIExtensionContentSession对应的窗口界面对象，并将结果返回给UIExtensionComponent控件（callback形式）。

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

参数：

UIExtensionContentSession.terminateSelfWithResult

terminateSelfWithResult(parameter: AbilityResult): Promise<void>;

停止UIExtensionContentSession对应的窗口界面对象，并将结果返回给UIExtensionComponent控件（promise形式）。

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

参数：

返回值：

UIExtensionContentSession.setWindowBackgroundColor

setWindowBackgroundColor(color: string): void

设置UIExtensionAbility加载界面的背景色。该接口需要在loadContent()调用生效后使用。

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

系统API：此接口为系统接口，三方应用不支持调用。

参数：

错误码：

错误码详细介绍请参考errcode-ability。

UIExtensionContentSession.setWindowPrivacyMode

setWindowPrivacyMode(isPrivacyMode: boolean): Promise<void>

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

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

需要权限： ohos.permission.PRIVACY_WINDOW

参数：

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

返回值：

UIExtensionContentSession.setWindowPrivacyMode

setWindowPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void

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

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

需要权限： ohos.permission.PRIVACY_WINDOW

参数：

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

UIAbilityContext.startAbilityByType¹¹⁺

startAbilityByType(type: string, wantParam: Record, abilityStartCallback: AbilityStartCallback, callback: AsyncCallback<void>) : void;

通过type隐式启动UIExtensionAbility。使用callback异步回调。

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

参数：

错误码：

错误码详细介绍请参考errcode-ability。

UIAbilityContext.startAbilityByType¹¹⁺

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

通过type隐式启动UIExtensionAbility。使用Promise异步回调。

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

参数：

返回值：

错误码：

错误码详细介绍请参考errcode-ability。

你可能感兴趣的鸿蒙文章

harmony 鸿蒙接口

harmony 鸿蒙系统公共事件定义(待停用)

harmony 鸿蒙系统公共事件定义

harmony 鸿蒙开发说明

harmony 鸿蒙企业设备管理概述（仅对系统应用开放）

harmony 鸿蒙BundleStatusCallback

harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager模块)

harmony 鸿蒙@ohos.distributedBundle (分布式包管理)

harmony 鸿蒙@ohos.bundle (Bundle模块)

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (企业设备管理扩展能力)