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

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

说明：

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

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

当前页面仅包含本模块的系统接口，其他公开接口参见@ohos.app.ability.UIExtensionContentSession (带界面扩展能力界面操作类)。

导入模块

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

UIExtensionContentSession.sendData

sendData(data: Record<string, Object>): void

发送数据给UIExtensionComponent控件。

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

系统接口：此接口为系统接口。

参数：

错误码：

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

UIExtensionContentSession.setReceiveDataCallback

setReceiveDataCallback(callback: (data: Record<string, Object>) => void): void

设置从UIExtensionComponent控件接收数据的回调方法。使用callback异步回调。

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

系统接口：此接口为系统接口。

参数：

错误码：

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

UIExtensionContentSession.setReceiveDataForResultCallback¹¹⁺

setReceiveDataForResultCallback(callback: (data: Record<string, Object>) => Record<string, Object>): void

设置从UIExtensionComponent控件接收数据带返回值的回调方法。使用callback异步回调。

系统接口：此接口为系统接口。

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

参数：

错误码：

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

UIExtensionContentSession.startAbility

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

启动Ability。使用callback异步回调。

说明：

组件启动规则详见：组件启动规则（Stage模型）。 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。

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

系统接口：此接口为系统接口。

参数：

错误码：

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

UIExtensionContentSession.startAbility

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

启动Ability。使用callback异步回调。

说明：

组件启动规则详见：组件启动规则（Stage模型）。 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。

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

系统接口：此接口为系统接口。

参数：

错误码：

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

UIExtensionContentSession.startAbility

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

启动Ability。使用Promise异步回调。

说明：

组件启动规则详见：组件启动规则（Stage模型）。 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。

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

系统接口：此接口为系统接口。

参数：

返回值：

错误码：

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

UIExtensionContentSession.startAbilityForResult

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

启动一个Ability，在Ability终止后返回结果给调用方。使用callback异步回调。

Ability的终止方式包括以下几种情况:

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

说明：

组件启动规则详见：组件启动规则（Stage模型）。 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。

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

系统接口：此接口为系统接口。

参数：

错误码：

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

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。

说明：

组件启动规则详见：组件启动规则（Stage模型）。 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。

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

系统接口：此接口为系统接口。

参数：

错误码：

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

UIExtensionContentSession.startAbilityForResult

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

启动一个Ability，在Ability终止后返回结果给调用方。使用Promise异步回调。

Ability的终止方式包括以下几种情况:

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

说明：

组件启动规则详见：组件启动规则（Stage模型）。 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。

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

系统接口：此接口为系统接口。

参数：

返回值：

错误码：

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

UIExtensionContentSession.setWindowBackgroundColor

setWindowBackgroundColor(color: string): void

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

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

系统接口：此接口为系统接口。

参数：

错误码：

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

UIExtensionContentSession.startAbilityAsCaller¹¹⁺

startAbilityAsCaller(want: Want, callback: AsyncCallback<void>): void

初始Ability将自己的caller信息（如BundleName、AbilityName等）置于want参数中，传递给中间层的ExtensionAbility。当ExtensionAbility通过该接口拉起另外一个Ability，被拉起的Ability可以从onCreate生命周期获取到初始Ability的caller信息。使用callback异步回调。

系统接口：此接口为系统接口。

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

参数：

错误码：

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

UIExtensionContentSession.startAbilityAsCaller¹¹⁺

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

初始Ability将自己的caller信息（如BundleName、AbilityName等）置于want参数中，传递给中间层的ExtensionAbility。当ExtensionAbility通过该接口拉起另外一个Ability，被拉起的Ability可以从onCreate生命周期获取到初始Ability的caller信息。使用callback异步回调。

系统接口：此接口为系统接口。

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

参数：

错误码：

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

UIExtensionContentSession.startAbilityAsCaller¹¹⁺

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

初始Ability将自己的caller信息（如BundleName、AbilityName等）置于want参数中，传递给中间层的ExtensionAbility。当ExtensionAbility通过该接口拉起另外一个Ability，被拉起的Ability可以从onCreate生命周期获取到初始Ability的caller信息。使用Promise异步回调。

系统接口：此接口为系统接口。

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

参数：

返回值：

错误码：

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

UIExtensionContentSession.getUIExtensionHostWindowProxy¹¹⁺

getUIExtensionHostWindowProxy(): uiExtensionHost.UIExtensionHostWindowProxy

获取当前UIExtension对应的窗口对象，用于通知宽高、位置、避让信息等。

系统接口：此接口为系统接口。

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

返回值：

错误码：

示例：

import UIExtensionAbility from '@ohos.app.ability.UIExtensionAbility'
import UIExtensionContentSession from '@ohos.app.ability.UIExtensionContentSession'
import Want from '@ohos.app.ability.Want';
import uiExtensionHost from '@ohos.uiExtensionHost';

const TAG: string = '[UIExtAbility]'
export default class UIExtAbility extends UIExtensionAbility {

  onCreate() {
    console.log(TAG, `UIExtAbility onCreate`)
  }

  onForeground() {
    console.log(TAG, `UIExtAbility onForeground`)
  }

  onBackground() {
    console.log(TAG, `UIExtAbility onBackground`)
  }

  onDestroy() {
    console.log(TAG, `UIExtAbility onDestroy`)
  }

  onSessionCreate(want: Want, session: UIExtensionContentSession) {
    let extensionHostWindow = session.getUIExtensionHostWindowProxy();
    let data: Record<string, UIExtensionContentSession | uiExtensionHost.UIExtensionHostWindowProxy> = {
        'session': session,
        'extensionHostWindow': extensionHostWindow
    }
    let storage: LocalStorage = new LocalStorage(data);
    session.loadContent('pages/extension', storage);
  }

  onSessionDestroy(session: UIExtensionContentSession) {
    console.log(TAG, `UIExtAbility onSessionDestroy`)
  }
}

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