docs/en/application-dev/form/js-ui-widget-development.md-代码预览-docs:基于 OpenHarmony 的开发者文档项目 - AtomGit

The stage model is supported since API version 9. It is the mainstream model with a long evolution plan. This model is object-oriented and provides open application components as classes. You can derive application components for capability expansion.

Available APIs

The FormExtensionAbility class has the following APIs. For details, see FormExtensionAbility.

Name	Description
onAddForm(want: Want): formBindingData.FormBindingData	Called to notify the widget provider that a widget is being created.
onCastToNormalForm(formId: string): void	Called to notify the widget provider that a temporary widget is being converted to a normal one.
onUpdateForm(formId: string, wantParams?: Record<string, Object>): void	Called to notify the widget provider that a widget is being updated.
onChangeFormVisibility(newStatus: Record<string, number>): void	Called to notify the widget provider that the widget visibility status is being changed.
onFormEvent(formId: string, message: string): void	Called to instruct the widget provider to process a widget event.
onRemoveForm(formId: string): void	Called to notify the widget provider that a widget is being destroyed.
onConfigurationUpdate(newConfig: Configuration): void	Called when the configuration of the environment where the widget is running is being updated.

The following table lists some APIs provided by the formProvider class. For details about the APIs, see API Reference.

Name	Description
setFormNextRefreshTime(formId: string, minute: number, callback: AsyncCallback<void>): void	Sets the next refresh time for a widget. This API uses an asynchronous callback to return the result.
setFormNextRefreshTime(formId: string, minute: number): Promise<void>	Sets the next refresh time for a widget. This API uses a promise to return the result.
updateForm(formId: string, formBindingData: formBindingData.FormBindingData, callback: AsyncCallback<void>): void	Updates a widget. This API uses an asynchronous callback to return the result.
updateForm(formId: string, formBindingData: formBindingData.FormBindingData): Promise<void>	Updates a widget. This API uses a promise to return the result.

The following table lists some APIs provided by the formBindingData class. For details about the APIs, see API Reference.

Name	Description
createFormBindingData(obj?: Object \| string): FormBindingData	Creates a FormBindingData object.

How to Develop

The widget provider development based on the stage model involves the following key steps:

Creating a FormExtensionAbility Instance: Develop the lifecycle callback functions of FormExtensionAbility.
Configuring the Widget Configuration Files: Configure the application configuration file module.json5 and profile configuration file.
Persistently Storing Widget Data: Manage widget data persistence.
Updating Widget Data: Call updateForm() to update the information displayed in a widget.
Developing the Widget UI Page: Use HML+CSS+JSON to develop a JS widget UI page.
Developing Widget Events: Add the router and message events for a widget.

Creating a FormExtensionAbility Instance

To create a widget in the stage model, you need to implement the lifecycle callbacks of FormExtensionAbility. Before that, generate a widget template by referring to Creating an ArkTS Widget.

Import related modules in JsCardFormAbility.ets.

// entry/src/main/ets/jscardformability/JsCardFormAbility.ets
import { common, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { formBindingData, FormExtensionAbility, formProvider } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { preferences } from '@kit.ArkData';

JsCardFormAbility.ets

Implement FormExtension lifecycle callbacks in JsCardFormAbility.ets.

// entry/src/main/ets/jscardformability/JsCardFormAbility.ets
const TAG: string = 'JsCardFormAbility';
const DATA_STORAGE_PATH: string = '/data/storage/el2/base/haps/form_store';
const DOMAIN_NUMBER: number = 0xFF00;
let storeFormInfo =
  async (formId: string, formName: string, tempFlag: boolean, context: common.FormExtensionContext): Promise<void> => {
    // Only the widget ID (formId), widget name (formName), and whether the widget is a temporary one (tempFlag) are persistently stored.
    let formInfo: Record<string, string | boolean | number> = {
      'formName': formName,
      'tempFlag': tempFlag,
      'updateCount': 0
    };
    try {
      const storage: preferences.Preferences = await preferences.getPreferences(context, DATA_STORAGE_PATH);
      // put form info
      await storage.put(formId, JSON.stringify(formInfo));
      hilog.info(DOMAIN_NUMBER, TAG, `[EntryFormAbility] storeFormInfo, put form info successfully, formId: ${formId}`);
      await storage.flush();
    } catch (err) {
      hilog.error(DOMAIN_NUMBER, TAG, `[EntryFormAbility] failed to storeFormInfo,
      err: ${JSON.stringify(err as BusinessError)}`);
    }
  }
let deleteFormInfo = async (formId: string, context: common.FormExtensionContext): Promise<void> => {
  try {
    const storage: preferences.Preferences = await preferences.getPreferences(context, DATA_STORAGE_PATH);
    // Delete the widget information.
    await storage.delete(formId);
    hilog.info(DOMAIN_NUMBER, TAG, `[EntryFormAbility] deleteFormInfo, del form info successfully, formId: ${formId}`);
    await storage.flush();
  } catch (err) {
    hilog.error(DOMAIN_NUMBER, TAG, `[EntryFormAbility] failed to deleteFormInfo,
      err: ${JSON.stringify(err as BusinessError)}`);
  }
};


export default class JsCardFormAbility extends FormExtensionAbility {
  onAddForm(want: Want): formBindingData.FormBindingData {
    hilog.info(DOMAIN_NUMBER, TAG, '[JsCardFormAbility] onAddForm');

    if (want.parameters) {
      let formId = JSON.stringify(want.parameters['ohos.extra.param.key.form_identity']);
      let formName = JSON.stringify(want.parameters['ohos.extra.param.key.form_name']);
      let tempFlag = want.parameters['ohos.extra.param.key.form_temporary'] as boolean;
      // Persistently store widget data for subsequent use, such as instance acquisition and update.
      storeFormInfo(formId, formName, tempFlag, this.context);
    }

    let obj: Record<string, string> = {
      'title': 'titleOnCreate',
      'detail': 'detailOnCreate'
    };
    let formData: formBindingData.FormBindingData = formBindingData.createFormBindingData(obj);
    return formData;
  }

  onRemoveForm(formId: string): void {
    // Delete widget data.
    hilog.info(DOMAIN_NUMBER, TAG, '[EntryFormAbility] onRemoveForm');
    // Delete the persistent widget instance data.
    deleteFormInfo(formId, this.context);
  }

  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': 'titleOnUpdate',
      'detail': 'detailOnUpdate'
    };
    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));
    });
  }

  onFormEvent(formId: string, message: string): void {
    // If the widget supports event triggering, override this method and implement the trigger.
    hilog.info(DOMAIN_NUMBER, TAG, '[EntryFormAbility] onFormEvent');
    // Obtain the detail parameter passed in the message event.
    let msg: Record<string, string> = JSON.parse(message);
    if (msg.detail === 'message detail') {
      // Implement the service logic.
      hilog.info(DOMAIN_NUMBER, TAG, 'message info:' + msg.detail);
    }
  }

}

JsCardFormAbility.ets

NOTE FormExtensionAbility cannot reside in the background. Therefore, continuous tasks cannot be processed in the widget lifecycle callbacks.

Configure ExtensionAbility information under extensionAbilities in the module.json5 file. For a FormExtensionAbility, you must specify metadata. Specifically, set name to ohos.extension.form (fixed), and set resource to the index of the widget configuration information. Example configuration:

{
  "module": {
    // ...
    "extensionAbilities": [
      {
        "name": "JsCardFormAbility",
        "srcEntry": "./ets/jscardformability/JsCardFormAbility.ets",
        "description": "$string:JSCardFormAbility_desc",
        "label": "$string:JSCardFormAbility_label",
        "type": "form",
        "metadata": [
          {
            "name": "ohos.extension.form",
            "resource": "$profile:form_jscard_config"
          }
        ]
      }
    ]
  }
}

module.json5

Configure the widget configuration information. In the metadata configuration item of FormExtensionAbility, you can specify the resource index of specific configuration information of the widget. For example, if resource is set to $profile:form_jscard_config, form_jscard_config.json in the resources/base/profile/ directory of the development view is used as the profile configuration file of the widget. The following table describes the internal structure of the profile configuration file.

Table 1 Widget profile configuration file

Field	Description	Data Type	Default Value Allowed
name	Class name of the widget. The value is a string with a maximum of 127 bytes.	String	No
description	Description of the widget. The value can be a string or a resource index to descriptions in multiple languages. The value is a string with a maximum of 255 bytes.	String	Yes (initial value: left empty)
src	Full path of the UI code corresponding to the widget.	String	No
window	Window-related configurations.	Object	Yes. For details about the default value, see the window field.
isDefault	Whether the widget is a default one. Each UIAbility has only one default widget. - true: The widget is the default one. - false: The widget is not the default one.	Boolean	No
colorMode^(deprecated)	Color mode of the widget. - auto: following the system color mode - dark: dark color mode - light: light color mode Note: 1. This configuration item is supported since API version 12 and deprecated since API version 20. The color mode follows the system color mode.	String	Yes (initial value: auto)
supportDimensions	Supported widget dimensions. The options are as follows: - *1 2: indicates a grid with one row and two columns. - 2 * 2: indicates a grid with two rows and two columns. - 2 * 4: indicates a grid with two rows and four columns. - 2 * 3: indicates a grid with two rows and three columns. - 3 * 3: indicates a grid with three rows and three columns. - 4 * 4: indicates a grid with four rows and four columns. - 6 * 4: indicates a grid with six rows and four columns. Note: 2 * 3 and 3 * 3** support only watches.	String array	No
defaultDimension	Default grid style of the widget. The value must be available in the supportDimensions array of the widget.	String	No
updateEnabled	Whether the widget can be updated periodically. - true: The widget can be updated at a specified interval (updateDuration) or at the scheduled time (scheduledUpdateTime). updateDuration takes precedence over scheduledUpdateTime. - false: The widget cannot be updated periodically.	Boolean	No
scheduledUpdateTime	Scheduled time to update the widget. The value is in 24-hour format and accurate to minute. updateDuration takes precedence over scheduledUpdateTime. If both are specified, the value specified by updateDuration is used.	String	Yes (initial value: 0). By default, the widget is not updated at the scheduled time.
updateDuration	Interval to update the widget. The value is a natural number, in the unit of 30 minutes. If the value is 0, this field does not take effect. If the value is a positive integer N, the interval is calculated by multiplying N and 30 minutes. updateDuration takes precedence over scheduledUpdateTime. If both are specified, the value specified by updateDuration is used.	Number	Yes (initial value: 0)
formConfigAbility	Link to a specific page of the application. The value is a URI.	String	Yes (initial value: left empty)
formVisibleNotify	Whether the widget is allowed to use the widget visibility notification.	String	Yes (initial value: left empty)
metaData	Metadata of the widget. This field contains the array of the customizeData field.	Object	Yes (initial value: left empty)

Example configuration:

{
  "forms": [
    {
      "name": "WidgetJS",
      "description": "$string:JSCardEntryAbility_desc",
      "src": "./js/WidgetJS/pages/index/index",
      "window": {
        "designWidth": 720,
        "autoDesignWidth": true
      },
      "isDefault": true,
      "updateEnabled": true,
      "scheduledUpdateTime": "10:30",
      "updateDuration": 1,
      "defaultDimension": "2*2",
      "supportDimensions": [
        "2*2"
      ]
    }
  ]
}

A widget provider is usually started when it is needed to provide information about a widget. The Widget Manager supports multi-instance management and uses the widget ID to identify an instance. If the widget provider supports widget data modification, it must persistently store the data based on the widget ID, so that it can access the data of the target widget when obtaining, updating, or starting a widget.

For details about how to import the code, see Creating a FormExtensionAbility Instance.

// entry/src/main/ets/jscardformability/JsCardFormAbility.ets
const TAG: string = 'JsCardFormAbility';
const DATA_STORAGE_PATH: string = '/data/storage/el2/base/haps/form_store';
const DOMAIN_NUMBER: number = 0xFF00;
let storeFormInfo =
  async (formId: string, formName: string, tempFlag: boolean, context: common.FormExtensionContext): Promise<void> => {
    // Only the widget ID (formId), widget name (formName), and whether the widget is a temporary one (tempFlag) are persistently stored.
    let formInfo: Record<string, string | boolean | number> = {
      'formName': formName,
      'tempFlag': tempFlag,
      'updateCount': 0
    };
    try {
      const storage: preferences.Preferences = await preferences.getPreferences(context, DATA_STORAGE_PATH);
      // put form info
      await storage.put(formId, JSON.stringify(formInfo));
      hilog.info(DOMAIN_NUMBER, TAG, `[EntryFormAbility] storeFormInfo, put form info successfully, formId: ${formId}`);
      await storage.flush();
    } catch (err) {
      hilog.error(DOMAIN_NUMBER, TAG, `[EntryFormAbility] failed to storeFormInfo,
      err: ${JSON.stringify(err as BusinessError)}`);
    }
  }
// ...

export default class JsCardFormAbility extends FormExtensionAbility {
  onAddForm(want: Want): formBindingData.FormBindingData {
    hilog.info(DOMAIN_NUMBER, TAG, '[JsCardFormAbility] onAddForm');

    if (want.parameters) {
      let formId = JSON.stringify(want.parameters['ohos.extra.param.key.form_identity']);
      let formName = JSON.stringify(want.parameters['ohos.extra.param.key.form_name']);
      let tempFlag = want.parameters['ohos.extra.param.key.form_temporary'] as boolean;
      // Persistently store widget data for subsequent use, such as instance acquisition and update.
      storeFormInfo(formId, formName, tempFlag, this.context);
    }

    let obj: Record<string, string> = {
      'title': 'titleOnCreate',
      'detail': 'detailOnCreate'
    };
    let formData: formBindingData.FormBindingData = formBindingData.createFormBindingData(obj);
    return formData;
  }

  // ...
}

JsCardFormAbility.ets

You should override onRemoveForm to implement widget data deletion.

// entry/src/main/ets/jscardformability/JsCardFormAbility.ets
const TAG: string = 'JsCardFormAbility';
const DATA_STORAGE_PATH: string = '/data/storage/el2/base/haps/form_store';
const DOMAIN_NUMBER: number = 0xFF00;
// ...
let deleteFormInfo = async (formId: string, context: common.FormExtensionContext): Promise<void> => {
  try {
    const storage: preferences.Preferences = await preferences.getPreferences(context, DATA_STORAGE_PATH);
    // Delete the widget information.
    await storage.delete(formId);
    hilog.info(DOMAIN_NUMBER, TAG, `[EntryFormAbility] deleteFormInfo, del form info successfully, formId: ${formId}`);
    await storage.flush();
  } catch (err) {
    hilog.error(DOMAIN_NUMBER, TAG, `[EntryFormAbility] failed to deleteFormInfo,
      err: ${JSON.stringify(err as BusinessError)}`);
  }
};


export default class JsCardFormAbility extends FormExtensionAbility {
  // ...
  onRemoveForm(formId: string): void {
    // Delete widget data.
    hilog.info(DOMAIN_NUMBER, TAG, '[EntryFormAbility] onRemoveForm');
    // Delete the persistent widget instance data.
    deleteFormInfo(formId, this.context);
  }

  // ...
}

JsCardFormAbility.ets

For details about how to implement persistent data storage, see Application Data Persistence.

The Want object passed in by the widget host to the widget provider contains a flag that specifies whether the requested widget is normal or temporary.

Normal widget: a widget persistently used by the widget host
Temporary widget: a widget temporarily used by the widget host. (Currently, there is no temporary widget scenario.)

Data of a temporary widget will be deleted on the Widget Manager if the widget framework is killed and restarted. The widget provider, however, is not notified of the deletion and still keeps the data. Therefore, the widget provider needs to clear the data of temporary widgets proactively if the data has been kept for a long period of time. If the widget host has converted a temporary widget into a normal one, the widget provider should change the widget data from temporary storage to persistent storage. Otherwise, the widget data may be deleted by mistake.

When an application initiates a scheduled or periodic update, the application obtains the latest data and calls updateForm() to update the widget.

For details about how to import the code, see Creating a FormExtensionAbility Instance.

// entry/src/main/ets/jscardformability/JsCardFormAbility.ets
const TAG: string = 'JsCardFormAbility';
// ...
const DOMAIN_NUMBER: number = 0xFF00;
// ...

export default class JsCardFormAbility extends FormExtensionAbility {
  // ...
  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': 'titleOnUpdate',
      'detail': 'detailOnUpdate'
    };
    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));
    });
  }

  // ...
}

JsCardFormAbility.ets

You can use the web-like paradigm (HML+CSS+JSON) to develop JS widget pages. This section describes how to develop a page shown below.

WidgetCardPage

HML: uses web-like paradigm components to describe the widget page information.

<div class="container">
  <stack>
    <div class="container-img">
      <image src="/common/widget.png" class="bg-img"></image>
    </div>
    <div class="container-inner">
      <text class="title">{{title}}</text>
      <text class="detail_text" onclick="routerEvent">{{detail}}</text>
    </div>
  </stack>
</div>

CSS: defines style information about the web-like paradigm components in HML.

.container {
  flex-direction: column;
  justify-content: center;
  align-items: center;
}

.bg-img {
  flex-shrink: 0;
  height: 100%;
}

.container-inner {
  flex-direction: column;
  justify-content: flex-end;
  align-items: flex-start;
  height: 100%;
  width: 100%;
  padding: 12px;
}

.title {
  font-size: 19px;
  font-weight: bold;
  color: white;
  text-overflow: ellipsis;
  max-lines: 1;
}

.detail_text {
  font-size: 16px;
  color: white;
  opacity: 0.66;
  text-overflow: ellipsis;
  max-lines: 1;
  margin-top: 6px;
}

JSON: defines data and event interaction on the widget UI page.

{
  "data": {
    "title": "TitleDefault",
    "detail": "TextDefault"
  },
  "actions": {
    "routerEvent": {
      "action": "router",
      "abilityName": "EntryAbility",
      "params": {
        "message": "add detail"
      }
    }
  }
}

You can set router and message events for components on a widget. The router event applies to UIAbility redirection, and the message event applies to custom click events.

The key steps are as follows:

Set the onclick field in the HML file to routerEvent or messageEvent, depending on the actions settings in the JSON file.
Set the router event.
- action: "router", which indicates a router event.
- abilityName: name of the UIAbility to redirect to (PageAbility component in the FA model and UIAbility component in the stage model). For example, the default UIAbility name of the stage model created by DevEco Studio is EntryAbility.
- params: custom parameters passed to the target UIAbility. Set them as required. The value can be obtained from parameters in want used for starting the target UIAbility. For example, in the lifecycle function onCreate of the MainAbility in the stage model, you can obtain want and its parameters field.
Set the message event.
- action: "message", which indicates a message event.
- params: custom parameters of the message event. Set them as required. The value can be obtained from message in the widget lifecycle function onFormEvent().

The following are examples:

HML file:

<div class="container">
    <stack>
        <div class="container-img">
            <image src="/common/CardWebImg.png" class="bg-img"></image>
            <image src="/common/CardWebImgMatrix.png"
                   class="bottom-img"/>
        </div>
        <div class="container-inner">
            <text class="title" onclick="routerEvent">{{ title }}</text>
            <text class="detail_text" onclick="messageEvent">{{ detail }}</text>
        </div>
    </stack>
</div>

CSS file:

.container {
    flex-direction: column;
    justify-content: center;
    align-items: center;
}

.bg-img {
    flex-shrink: 0;
    height: 100%;
    z-index: 1;
}

.bottom-img {
    position: absolute;
    width: 150px;
    height: 56px;
    top: 63%;
    background-color: rgba(216, 216, 216, 0.15);
    filter: blur(20px);
    z-index: 2;
}

.container-inner {
    flex-direction: column;
    justify-content: flex-end;
    align-items: flex-start;
    height: 100%;
    width: 100%;
    padding: 12px;
}

.title {
    font-family: HarmonyHeiTi-Medium;
    font-size: 14px;
    color: rgba(255, 255, 255, 0.90);
    letter-spacing: 0.6px;
    font-weight: 500;
    width: 100%;
    text-overflow: ellipsis;
    max-lines: 1;
}

.detail_text {
    font-family: HarmonyHeiTi;
    font-size: 12px;
    color: rgba(255, 255, 255, 0.60);
    letter-spacing: 0.51px;
    font-weight: 400;
    text-overflow: ellipsis;
    max-lines: 1;
    margin-top: 6px;
    width: 100%;
}

JSON file:

{
  "data": {
    "title": "TitleDefault",
    "detail": "TextDefault"
  },
  "actions": {
    "routerEvent": {
      "action": "router",
      "abilityName": "JSCardEntryAbility",
      "params": {
        "info": "router info",
        "message": "router message"
      }
    },
    "messageEvent": {
      "action": "message",
      "params": {
        "detail": "message detail"
      }
    }
  }
}

NOTE

The JSON value of data supports multi-level nested data. When updating data, ensure that complete data is carried.

Suppose a widget displays Mr. Zhang's course information for July 18, as shown in the following code snippet.

"data": {
    "Day": "07.18",
    "teacher": {
        "name": "Mr.Zhang",
        "course": "Math"
    }
}

To update the widget content to the course information of Mr. Li on July 18, you must pass the complete data as follows, instead of only a single date item such as name or course:

"teacher": {
    "name": "Mr.Li",
    "course": "English"
}

Receive the router event in UIAbility and obtain parameters.

// entry/src/main/ets/entryability/EntryAbility.ets
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';

const TAG: string = 'EntryAbility';
const DOMAIN_NUMBER: number = 0xFF00;
// ...
export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    if (want?.parameters?.params) {
      let params: Record<string, Object> = JSON.parse(JSON.stringify(want.parameters.params));
      // Obtain the info parameter passed in the router event.
      if (params.info === 'router info') {
        // Implement the service logic.
        hilog.info(DOMAIN_NUMBER, TAG, `router info: ${params.info}`);
      }
      // Obtain the message parameter passed in the router event.
      if (params.message === 'router message') {
        // Implement the service logic.
        hilog.info(DOMAIN_NUMBER, TAG, `router message: ${params.message}`);
      }
    }
  }

  // ...
}

EntryAbility.ets

Receive the message event in FormExtensionAbility and obtain the parameters. For details about how to import the code, see Creating a FormExtensionAbility Instance.

// entry/src/main/ets/jscardformability/JsCardFormAbility.ets
const TAG: string = 'JsCardFormAbility';
// ...
const DOMAIN_NUMBER: number = 0xFF00;
// ...

export default class JsCardFormAbility extends FormExtensionAbility {
  // ...
  onFormEvent(formId: string, message: string): void {
    // If the widget supports event triggering, override this method and implement the trigger.
    hilog.info(DOMAIN_NUMBER, TAG, '[EntryFormAbility] onFormEvent');
    // Obtain the detail parameter passed in the message event.
    let msg: Record<string, string> = JSON.parse(message);
    if (msg.detail === 'message detail') {
      // Implement the service logic.
      hilog.info(DOMAIN_NUMBER, TAG, 'message info:' + msg.detail);
    }
  }

}

JsCardFormAbility.ets

Developing a JS Widget (Stage Model)

Available APIs

How to Develop

Creating a FormExtensionAbility Instance

Configuring the Widget Configuration Files

Persistently Storing Widget Data

Updating Widget Data

Developing the Widget UI Page

Developing Widget Events