Managing ArkTS Widget Lifecycle

When creating an ArkTS widget, you need to implement the FormExtensionAbility lifecycle APIs.

Import related modules to EntryFormAbility.ets.

// entry/src/main/ets/entryformability/EntryFormAbility.ts
import { formBindingData, FormExtensionAbility, formInfo, formProvider } from '@kit.FormKit';
import { Configuration, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

In EntryFormAbility.ets, implement the FormExtensionAbility lifecycle API, including onAddForm, in which want can be used to obtain the widget information through FormParam.

// entry/src/main/ets/entryformability/EntryFormAbility.ts
const TAG: string = 'EntryFormAbility';
const DOMAIN_NUMBER: number = 0xFF00;

export default class EntryFormAbility extends FormExtensionAbility {
  onAddForm(want: Want): formBindingData.FormBindingData {
    hilog.info(DOMAIN_NUMBER, TAG, '[EntryFormAbility] onAddForm');
    hilog.info(DOMAIN_NUMBER, TAG, want.parameters?.[formInfo.FormParam.NAME_KEY] as string);
    // Called when the widget host creates a widget. The widget provider should return the widget data binding class.
    let obj: Record<string, string> = {
      'title': 'titleOnAddForm',
      'detail': 'detailOnAddForm'
    };
    let formData: formBindingData.FormBindingData = formBindingData.createFormBindingData(obj);
    return formData;
  }

  onCastToNormalForm(formId: string): void {
    // This callback function is not required for the widget host.
    hilog.info(DOMAIN_NUMBER, TAG, '[EntryFormAbility] onCastToNormalForm');
  }

  onUpdateForm(formId: string): void {
    // Override this method to support interval-based updates, time-specific updates, or updates requested by the widget host.
    hilog.info(DOMAIN_NUMBER, TAG, '[EntryFormAbility] onUpdateForm');
    let obj: Record<string, string> = {
      'title': 'titleOnUpdateForm',
      'detail': 'detailOnUpdateForm'
    };
    let formData: formBindingData.FormBindingData = formBindingData.createFormBindingData(obj);
    formProvider.updateForm(formId, formData).catch((error: BusinessError) => {
      hilog.info(DOMAIN_NUMBER, TAG, '[EntryFormAbility] updateForm, error:' + JSON.stringify(error));
    });
  }

  onChangeFormVisibility(newStatus: Record<string, number>): void {
    // Called when the widget host initiates an event about visibility changes. The widget provider should do something to respond to the notification. This callback takes effect only for system applications.
    hilog.info(DOMAIN_NUMBER, TAG, '[EntryFormAbility] onChangeFormVisibility');
  }

  onFormEvent(formId: string, message: string): void {
    // If the widget supports event triggering, override this method and implement the trigger.
    hilog.info(DOMAIN_NUMBER, TAG, `FormAbility onFormEvent, formId = ${formId}, message: ${message}`);
    // ···
  }

  onRemoveForm(formId: string): void {
    // Remove widget data.
    hilog.info(DOMAIN_NUMBER, TAG, '[EntryFormAbility] onRemoveForm');
    // Remove the persistent widget instance data.
    // Implement this API based on project requirements.
  }

  onConfigurationUpdate(config: Configuration) {
    // Called when the configuration of the environment where the formExtensionAbility is running is being updated.
    // The formExtensionAbility is cleared after 10 seconds of inactivity.
    hilog.info(DOMAIN_NUMBER, TAG, '[EntryFormAbility] onConfigurationUpdate:' + JSON.stringify(config));
  }

  onAcquireFormState(want: Want): formInfo.FormState {
    // Called upon a status query request from the widget. By default, the initial widget state is returned.
    return formInfo.FormState.READY;
  }
}

The FormExtensionAbility process cannot remain resident in the background. That is, long-running tasks cannot be processed in widget lifecycle callbacks. After lifecycle scheduling is complete, the process persists for 10 seconds. If no new lifecycle callback is received within 10 seconds, the process exits automatically. For business logic that may take more than 10 seconds to complete, you are advised to launch the main app for processing, and then use updateForm to notify the widget to refresh.

目录

Managing ArkTS Widget Lifecycle