LiveFormExtensionContext (System API)

LiveFormExtensionContext, inherited from ExtensionContext, is the context of LiveFormExtensionAbility.

NOTE

The initial APIs of this module are supported since API version 20. Newly added APIs will be marked with a superscript to indicate their earliest API version.

This topic describes only system APIs provided by the module. For details about its public APIs, see LiveFormExtensionContext.

The APIs of this module can be used only in the stage model.

Modules to Import

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

NOTE

In versions earlier than API version 22, you need to import LiveFormExtensionContext with import LiveFormExtensionContext from 'application/LiveFormExtensionContext';. This import mode is marked in red in DevEco Studio, but does not affect compilation and running. You can use LiveFormExtensionContext directly.

In API version 22 and later versions, you can import LiveFormExtensionContext with import { common } from '@kit.AbilityKit'; and use it in the form of common.LiveFormExtensionContext.

How to Use

LiveFormExtensionContext is used to query information about its associated LiveFormExtensionAbility and access resources of the 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

Context of the LiveFormExtensionAbility.

connectServiceExtensionAbility²¹⁺

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

Connects the current LiveFormExtensionAbility client to a ServiceExtensionAbility server.

Before calling this API, you must implement the ConnectOptions API.

Upon successful connection, the LiveFormExtensionAbility can communicate with the ServiceExtensionAbility through the IRemoteObject returned by ConnectOptions, allowing access to capabilities exposed by the ServiceExtensionAbility.

ServiceExtensionAbility enables applications to run in the background and provide services. Third-party applications can connect to and communicate with this ExtensionAbility. A successful connection via this API will start the ServiceExtensionAbility. For details, see Component Startup Rules.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.Ability.Form

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information required for connecting to the ServiceExtensionAbility, including the ability name and bundle name.
connection	ConnectOptions	Yes	Callback used to return the information indicating connection success, failure, or disconnection. If the connection is successful, the IRemoteObject instance will be returned.

Return value

Type	Description
number	Connection ID. The client can call disconnectServiceExtensionAbility with this ID for disconnection.

Error codes

For details about the error codes, see Form Error Codes and Universal Error Codes.

ID	Error Message
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.

Example

// 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. Pass LiveFormExtensionContext to the widget page component.
    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. Obtain 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 {
    // Replace the Want information with the actual one.
    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) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`connectServiceExtensionAbility failed, code is ${code}, message is ${message}`);
    }
  }

  build() {
    Stack() {
      // Replace the page with the actual one.
    }
  }
}

disconnectServiceExtensionAbility²¹⁺

disconnectServiceExtensionAbility(connectionId: number): Promise<void>

Disconnects from a ServiceExtensionAbility. Once the connection is terminated, set the IRemoteObject, which is returned when the connection is established, to null. This API uses a promise to return the result.

ServiceExtensionAbility is a special type of ExtensionAbility provided by the system. It is designed to deliver background services for specific scenarios and does not support developer customization. ServiceExtensionAbility enables applications to run in the background and provide services. Third-party applications can connect to and communicate with this ExtensionAbility.