OpenHarmony @CnapData

Widget-related configuration includes FormExtensionAbility configuration and widget configuration.

Configure FormExtensionAbility 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": "EntryFormAbility",
        "srcEntry": "./ets/entryformability/EntryFormAbility.ts",
        "label": "$string:EntryFormAbility_label",
        "description": "$string:EntryFormAbility_desc",
        "type": "form",
        "metadata": [
          {
            "name": "ohos.extension.form",
            "resource": "$profile:form_config"
          }
        ]
      }
    ]
  }
}

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_config, form_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 field structure.

Table 1 form_config.json 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. For an ArkTS widget, the full path must contain the widget file name extension, for example, ./ets/widget/pages/WidgetCard.ets. For a JS widget, the full path does not need to contain the widget file name extension, for example, ./js/widget/pages/WidgetCard.	String	No
uiSyntax	Type of the widget. - arkts: ArkTS widget - hml: JS widget	String	Yes (initial value: hml)
window	Window-related configurations.	Object	Yes
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	Color mode of the widget. - auto: auto-adaptive color mode - dark: dark color mode - light: light color mode	String	Yes (initial value: auto)
supportDimensions	Grid styles supported by the widget. - *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. - 4 * 4**: indicates a grid with four rows and four columns.	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. NOTE updateDuration takes precedence over scheduledUpdateTime. If both are specified, the value specified by updateDuration is used.	String	Yes (initial value: The widget cannot be updated periodically.）
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. NOTE 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": "widget",
      "description": "This is a service widget.",
      "src": "./ets/widget/pages/WidgetCard.ets",
      "uiSyntax": "arkts",
      "window": {
        "designWidth": 720,
        "autoDesignWidth": true
      },
      "colorMode": "auto",
      "isDefault": true,
      "updateEnabled": true,
      "scheduledUpdateTime": "10:30",
      "updateDuration": 1,
      "defaultDimension": "2*2",
      "supportDimensions": [
        "2*2"
      ]
    }
  ]
}

Configuring Widget Configuration Files