LiveFormExtensionContext (系统接口)

LiveFormExtensionContext是LiveFormExtensionAbility的上下文，继承自ExtensionContext。

说明：

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

当前页面仅包含本模块的系统接口，其他公共接口参见LiveFormExtensionContext。

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

导入模块

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

说明：

在API version 22以前，需要通过import LiveFormExtensionContext from 'application/LiveFormExtensionContext'; 导入LiveFormExtensionContext。该导入方式在DevEco Studio中标红，但不影响编译运行，可以直接使用LiveFormExtensionContext。

在API version 22及以后，支持通过import { common } from '@kit.AbilityKit'; 导入LiveFormExtensionContext，并通过common.LiveFormExtensionContext的方式使用。

使用说明

LiveFormExtensionContext主要用于查询所属LiveFormExtensionAbility的信息，提供访问特定LiveFormExtensionAbility资源的能力。

import { LiveFormInfo, LiveFormExtensionAbility } from '@kit.FormKit';
import { UIExtensionContentSession } from '@kit.AbilityKit';

export default class MyLiveFormExtensionAbility extends LiveFormExtensionAbility {
  onLiveFormCreate(liveFormInfo: LiveFormInfo, session: UIExtensionContentSession) {
    let storage: LocalStorage = new LocalStorage();
    storage.setOrCreate('context', this.context);
    session.loadContent('pages/MyLiveFormPage', storage);
    session.sendData({ ['isFormReady']: true });
    console.info("current language is: ", this.context.config.language);
  }
};

LiveFormExtensionContext

LiveFormExtensionContext是LiveFormExtensionAbility的上下文环境。

connectServiceExtensionAbility²¹⁺

connectServiceExtensionAbility(want: Want, connection: ConnectOptions): number

将当前LiveFormExtensionAbility客户端连接到一个ServiceExtensionAbility服务端。

调用该接口前，必须实现ConnectOptions接口。

通过本接口连接成功后，LiveFormExtensionAbility可以通过ConnectOptions返回的IRemoteObject与ServiceExtensionAbility进行通信，以使用ServiceExtensionAbility对外提供的能力。

ServiceExtensionAbility是一类特殊的ExtensionAbility组件，这类组件由系统提供，通常用于提供指定场景后台服务能力，不支持开发者自定义。

ServiceExtensionAbility提供后台服务扩展能力，支持后台运行并对外提供相应能力。三方应用可以连接该ExtensionAbility，并进行通信。

通过本接口连接成功后，会启动ServiceExtensionAbility组件，具体请参考组件启动规则。

模型约束： 此接口仅可在Stage模型下使用。

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

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
want	Want	是	连接ServiceExtensionAbility的Want信息，包括Ability名称、Bundle名称等。
connection	ConnectOptions	是	ConnectOptions类型的回调函数，返回服务连接成功、连接失败、断开的信息，连接成功会返回IRemoteObject实例。

返回值：

类型	说明
number	返回连接id，客户端可以通过disconnectServiceExtensionAbility传入该连接id来断开连接。

错误码：

以下错误码的详细介绍请参见卡片错误码和通用错误码。

错误码ID	错误信息
202	Permission verification failed, application which is not a system application uses system API.
16500100	Failed to obtain the configuration information.
16501000	An internal functional error occurred.
16501011	The form can not support this operation.

示例：

// MyLiveFormExtensionAbility.ets
import { LiveFormInfo, LiveFormExtensionAbility } from '@kit.FormKit';
import { UIExtensionContentSession } from '@kit.AbilityKit';

export default class MyLiveFormExtensionAbility extends LiveFormExtensionAbility {
  onLiveFormCreate(liveFormInfo: LiveFormInfo, session: UIExtensionContentSession) {
    // 1.将LiveFormExtensionContext传给互动卡片的页面组件
    let storage: LocalStorage = new LocalStorage();
    storage.setOrCreate('context', this.context);
    session.loadContent('pages/MyLiveFormPage', storage);
    session.sendData({['isFormReady']: true});
  }
};

// pages/MyLiveFormPage.ets
import { Want, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { rpc } from '@kit.IPCKit';

@Entry
@Component
struct MyLiveFormPage {
  private storageForMyLiveFormPage: LocalStorage | undefined = undefined;
  private liveFormContext: common.LiveFormExtensionContext | undefined = undefined;

  aboutToAppear(): void {
    // 2.获取LiveFormExtensionContext
    this.storageForMyLiveFormPage = this.getUIContext().getSharedLocalStorage();
    this.liveFormContext = this.storageForMyLiveFormPage?.get<common.LiveFormExtensionContext>('context');
    if (!this.liveFormContext) {
        console.info('MyLiveFormPage liveFormContext is empty');
        return;
      }
    this.connectServiceExtensionAbility();
  }

  private connectServiceExtensionAbility(): void {
    // 请开发者替换为实际want
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'ServiceExtensionAbility'
    };
    let commRemote: rpc.IRemoteObject;
    let options: common.ConnectOptions = {
      onConnect(elementName, remote) {
        commRemote = remote;
        console.info('onConnect...');
      },
      onDisconnect(elementName) {
        console.info('onDisconnect...');
      },
      onFailed(code) {
        console.error(`onFailed, err code: ${code}.`);
      }
    };
    let connection: number | undefined;
    try {
      connection = this.liveFormContext?.connectServiceExtensionAbility(want, options);
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`connectServiceExtensionAbility failed, code is ${code}, message is ${message}`);
    }
  }

  build() {
    Stack() {
      // 请开发者替换为实际的页面
    }
  }
}

disconnectServiceExtensionAbility²¹⁺

disconnectServiceExtensionAbility(connectionId: number): Promise<void>

断开与ServiceExtensionAbility的连接，断开连接之后开发者需要将连接成功时返回的IRemoteObject对象置空。使用Promise异步回调。

ServiceExtensionAbility是一类特殊的ExtensionAbility组件，这类组件由系统提供，通常用于提供指定场景后台服务能力，不支持开发者自定义。ServiceExtensionAbility提供后台服务扩展能力，支持后台运行并对外提供相应能力。三方应用可以连接该ExtensionAbility，并进行通信。