Configuring ArkTS Widget Configuration Files

Widget-related configuration includes FormExtensionAbility configuration and widget configuration. A standalone widget package includes the standalone widget package configuration.

NOTE

• The widget five-tuple comprises the unique identifiers of a widget, including bundleName, moduleName, abilityName, formName, and formDimension. Specifically, bundleName maps to the bundleName tag in the app.json5 file, moduleName corresponds to the name tag in the module.json5 file, abilityName refers to the name property in the abilities tag, formName denotes the name field specified in the widget configuration file, and formDimension refers to the supportDimensions field in the widget configuration file.
• Importing the five-tuple configuration via resource files is not recommended. Should the IDs of new fields in the resource file change, the five-tuple will be deemed modified as a result.
• If the five-tuple is modified following an application upgrade, the corresponding system widget will be deleted and disappear.

FormExtensionAbility Configuration

Configure FormExtensionAbility information under extensionAbilities in the module.json5 file. For 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:

{
  "module": {
    // ...
    "extensionAbilities": [
      {
        "name": "EntryFormAbility",
        "srcEntry": "./ets/entryformability/EntryFormAbility.ets",
        "label": "$string:EntryFormAbility_label",
        "description": "$string:EntryFormAbility_desc",
        "type": "form",
        "metadata": [
          {
            "name": "ohos.extension.form",
            "resource": "$profile:form_config"
          }
        ]
      }
    ],
    // This configuration is only applicable to the standalone widget package form and is used to associate the corresponding widget package module.
    "formWidgetModule": "library"
  }
}

Standalone Widget Package Configuration

In the module.json5 file of a widget package, the formExtensionModule field is used to associate with the module of the application bundle.
Example:

{
  "module": {
    "name": "library",
    "type": "shared",
    "description": "$string:shared_desc",
    "deviceTypes": [
      "phone"
    ],
    "deliveryWithInstall": true,
    // This configuration is only applicable to the standalone widget package form and is used to associate the corresponding application bundle module.
    "formExtensionModule": "entry"
  }
}

Widget Configuration

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 form_config.json configuration file is automatically generated when you create a widget.

Fields in Configuration File

Table 1 form_config.json file

supportDeviceTypes Field

Specifies the device type supported by the widget.

supportDevicePerformanceClasses Field

Specifies the device performance class supported by the widget.

window Field

Defines the internal structure of the window object. This field is supported only in JS widgets.

funInteractionParams Field

Specifies a fun-based widget. If funInteractionParams and sceneAnimationParams are both configured, the interactive widget is a fun-based widget.

{
  "forms": [
    {
       // ...
      "funInteractionParams": {
         "targetBundleName": "com.example.funInteraction",
         "subBundleName": "com.example.subFunInteraction"
      }
    }
  ]
}

sceneAnimationParams Field

Specifies a scene-based widget. If funInteractionParams and sceneAnimationParams are both configured, the interactive widget is a fun-based widget.

{
  "forms": [
    {
       // ...
      "sceneAnimationParams": {
         "abilityName": "MyLiveFormExtensionAbility",
         "disabledDesktopBehaviors": [
           "SWIPE_DESKTOP",
           "PULL_DOWN_SEARCH",
           "LONG_CLICK",
           "DRAG"
         ]
      }          
    }
  ]
}

standby Field

Defines the internal structure of the standby object. Widgets can be displayed in landscape standby mode only when the application obtains the required open capability and the isSupported property is set to true.

{
  "forms": [
    {
      // ...
      "standby": {
        "isSupported": true,
        "isAdapted": false,
        "isPrivacySensitive": false
      }          
    }
  ]
}

Configuration File Example

{
  "forms": [
    {
      "name": "widget",
      "displayName": "$string:widget_display_name",
      "description": "$string:widget_desc",
      "src": "./ets/widget/pages/WidgetCard.ets",
      "uiSyntax": "arkts",
      "window": {
        "designWidth": 720,
        "autoDesignWidth": true
      },
      "renderingMode": "fullColor",
      "isDefault": true,
      "updateEnabled": true,
      "scheduledUpdateTime": "10:30",
      "updateDuration": 1,
      "defaultDimension": "2*2",
      "supportDimensions": [
        "2*2"
      ],
      "formConfigAbility": "ability://EntryAbility",
      "isDynamic": true,
      "metadata": []
    }
  ]
}