LiveFormExtensionContext

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.

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.

LiveFormExtensionContext

LiveFormExtensionContext, inherited from ExtensionContext, allows you to access resources specific to LiveFormExtensionAbility.

startAbilityByLiveForm

startAbilityByLiveForm(want: Want): Promise<void>

Starts the widget provider (application) page. This API uses a promise to return the result.

This API can only be used to start the page of the interactive widget provider (application). If this API is used to start the page of another application, error code 16501011 will be reported.

This API can only be called within the click event callback and must be called directly. Delayed calls are not supported. Otherwise, the error code 16501011 will be reported.

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

System capability: SystemCapability.Ability.Form

Atomic service API: This API can be used in atomic services since API version 20.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Information about the application page to be started. Only explicit Want is supported.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
801	Capability not supported due to limited device capabilities.
16500050	An IPC connection error happened.
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 { formInfo, 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);
  }
};

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

@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');
  }

   private startAbilityByLiveForm(): void {
    try {
      // Replace the Want information with the actual one.
      this.liveFormContext?.startAbilityByLiveForm({
        bundleName: 'com.example.liveformdemo',
        abilityName: 'EntryAbility',
      })
        .then(() => {
          console.info('startAbilityByLiveForm succeed');
        })
        .catch((err: BusinessError) => {
          console.error(`startAbilityByLiveForm failed, code is ${err?.code}, message is ${err?.message}`);
        });
    } catch (e) {
      console.error(`startAbilityByLiveForm failed, code is ${e?.code}, message is ${e?.message}`);
    }
  }

  build() {
    // Replace the page with the actual one.
    Stack() {
      Column()
        .width('50%')
        .height('50%')
        .backgroundColor('#2875F5')
    }
    .width('100%')
    .height('100%')
    .onClick(() => {
      // 3. Use the API in the click event callback.
      console.info('MyLiveFormPage click to start ability');
      if (!this.liveFormContext) {
        console.info('MyLiveFormPage liveFormContext is empty');
        return;
      }
      this.startAbilityByLiveForm();
    })
  }
}