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

UIExtensionContentSession

sendData

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

发送数据给UIExtensionComponent控件。

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

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

参数：

错误码：

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

示例：

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

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

  build() {
    RelativeContainer() {
      Button('SendData')
        .onClick(() => {
          let data: Record<string, Object> = {
            'number': 123456,
            'message': 'test'
          };

          try {
            this.session?.sendData(data);
          } catch (err) {
            console.log('sendData err:' + JSON.stringify(err));
          }
        })
    }
    .height('100%')
    .width('100%')
  }
}

setReceiveDataCallback

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

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

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

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

参数：

错误码：

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

示例：

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

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

  build() {
    RelativeContainer() {
      Button('SendData')
        .onClick(() => {
          this.session?.setReceiveDataCallback((data: Record<string, Object>) => {
            console.info(`Succeeded in setReceiveDataCallback, data: ${JSON.stringify(data)}`);
          });
        })
    }
    .height('100%')
    .width('100%')
  }
}

setReceiveDataForResultCallback¹¹⁺

setReceiveDataForResultCallback(callback: (data: Record) => Record): void

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

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

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

参数：

错误码：

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

示例：

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

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

  build() {
    RelativeContainer() {
      Button('SetReceiveDataForResultCallback')
        .onClick(() => {
          this.session?.setReceiveDataForResultCallback((data: Record<string, Object>) => {
            console.info(`Succeeded in setReceiveDataCallback, data: ${JSON.stringify(data)}`);
            return data;
          });
        })
    }
    .height('100%')
    .width('100%')
  }
}

startAbility

startAbility(want: Want, callback: AsyncCallback&lt;void&gt;): void

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

说明：

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

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

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

参数：

错误码：

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

示例：

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

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

  onSessionCreate(want: Want, session: UIExtensionContentSession): void {
    session.startAbility(want, (err: BusinessError) => {
      if (err) {
        console.error(`Failed to startAbility, code: ${err.code}, msg: ${err.message}`);
        return;
      }
      console.info(`Succeeded in startAbility`);
    })
  }

  // ...
}

startAbility

startAbility(want: Want, options: StartOptions, callback: AsyncCallback&lt;void&gt;): void

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

说明：

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

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

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

参数：

错误码：

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

示例：

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

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

  onSessionCreate(want: Want, session: UIExtensionContentSession): void {
    let starOptions: StartOptions = {
      displayId: 0
    };

    session.startAbility(want, starOptions, (err: BusinessError) => {
      if (err) {
        console.error(`Failed to startAbility, code: ${err.code}, msg: ${err.message}`);
        return;
      }
      console.info(`Succeeded in startAbility`);
    })
  }

  // ...
}

startAbility

startAbility(want: Want, options?: StartOptions): Promise&lt;void&gt;

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

说明：

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

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

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

参数：

返回值：

错误码：

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

示例：

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

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

  onSessionCreate(want: Want, session: UIExtensionContentSession): void {
    let starOptions: StartOptions = {
      displayId: 0
    };

    session.startAbility(want, starOptions)
      .then(() => {
        console.info(`Succeeded in startAbility`);
      })
      .catch((err: BusinessError) => {
        console.error(`Failed to startAbility, code: ${err.code}, msg: ${err.message}`);
      });
  }

  // ...
}

startAbilityForResult

startAbilityForResult(want: Want, callback: AsyncCallback&lt;AbilityResult&gt;): void

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

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

说明：

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

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

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

参数：

错误码：

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

示例：

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 {
    session.startAbilityForResult(want, (err: BusinessError, data: common.AbilityResult) => {
      if (err) {
        console.error(`Failed to startAbilityForResult, code: ${err.code}, msg: ${err.message}`);
        return;
      }
      console.info(`Succeeded in startAbilityForResult, data: ${JSON.stringify(data)}`);
    })
  }

  // ...
}

startAbilityForResult

startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback&lt;AbilityResult&gt;): void

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

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

说明：

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

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

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

参数：

错误码：

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

示例：

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

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

  onSessionCreate(want: Want, session: UIExtensionContentSession): void {
    let starOptions: StartOptions = {
      displayId: 0
    };

    session.startAbilityForResult(want, starOptions, (err: BusinessError, data: common.AbilityResult) => {
      if (err) {
        console.error(`Failed to startAbilityForResult, code: ${err.code}, msg: ${err.message}`);
        return;
      }
      console.info(`Succeeded in startAbilityForResult, data: ${JSON.stringify(data)}`);
    })
  }

  // ...
}

startAbilityForResult

startAbilityForResult(want: Want, options?: StartOptions): Promise&lt;AbilityResult&gt;

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

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

说明：

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

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

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

参数：

返回值：

错误码：

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

示例：

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

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

  onSessionCreate(want: Want, session: UIExtensionContentSession): void {
    let starOptions: StartOptions = {
      displayId: 0
    };

    session.startAbilityForResult(want, starOptions)
      .then((data: common.AbilityResult) => {
        console.info(`Succeeded in startAbilityForResult, data: ${JSON.stringify(data)}`);
      })
      .catch((err: BusinessError) => {
        console.error(`Failed to startAbilityForResult, code: ${err.code}, msg: ${err.message}`);
      });
  }

  // ...
}

setWindowBackgroundColor

setWindowBackgroundColor(color: string): void

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

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

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

参数：

错误码：

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

示例：

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);

    try {
      session.loadContent('pages/Extension', storage);
    } catch (err) {
      console.log('loadContent err:' + JSON.stringify(err));
    }

    try {
      session.setWindowBackgroundColor('#00FF00');
    } catch (err) {
      console.log('setWindowBackgroundColor err:' + JSON.stringify(err));
    }
  }

  // ...
}

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

参数：

错误码：

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

示例：

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 localWant: Want = want;
    localWant.bundleName = 'com.example.demo';
    localWant.moduleName = 'entry';
    localWant.abilityName = 'TestAbility';

    session.startAbilityAsCaller(localWant, (err: BusinessError) => {
      if (err) {
        console.error(`Failed to startAbilityAsCaller, code: ${err.code}, msg: ${err.message}`);
        return;
      }
      console.info(`Succeeded in startAbilityAsCaller`);
    })
  }

  // ...
}

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

参数：

错误码：

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

示例：

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

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

  onSessionCreate(want: Want, session: UIExtensionContentSession): void {
    let localWant: Want = want;
    localWant.bundleName = 'com.example.demo';
    localWant.moduleName = 'entry';
    localWant.abilityName = 'TestAbility';

    let startOptions: StartOptions = {
      displayId: 0
    };

    session.startAbilityAsCaller(localWant, startOptions, (err: BusinessError) => {
      if (err) {
        console.error(`Failed to startAbilityAsCaller, code: ${err.code}, msg: ${err.message}`);
        return;
      }
      console.info(`Succeeded in startAbilityAsCaller`);
    })
  }

  // ...
}

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

参数：

返回值：

错误码：

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

示例：

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

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

  onSessionCreate(want: Want, session: UIExtensionContentSession): void {
    let localWant: Want = want;
    localWant.bundleName = 'com.example.demo';
    localWant.moduleName = 'entry';
    localWant.abilityName = 'TestAbility';

    let startOptions: StartOptions = {
      displayId: 0
    };

    session.startAbilityAsCaller(localWant, startOptions)
      .then(() => {
        console.info(`Succeeded in startAbilityAsCaller`);
      })
      .catch((err: BusinessError) => {
        console.error(`Failed to startAbilityAsCaller, code: ${err.code}, msg: ${err.message}`);
      });
  }

  // ...
}

getUIExtensionHostWindowProxy¹¹⁺

getUIExtensionHostWindowProxy(): uiExtensionHost.UIExtensionHostWindowProxy

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

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

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

返回值：

错误码：

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

示例：

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

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);

    try {
      session.loadContent('pages/Extension', storage);
    } catch (err) {
      console.log('loadContent err:' + JSON.stringify(err));
    }
  }

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

你可能感兴趣的鸿蒙文章

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