harmony 鸿蒙Configuring Widget Configuration Files

2023-06-24
浏览 (528)

Configuring Widget Configuration Files

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.ets",
           "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 structure of the profile configuration file.

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 (initial value: see Table 2)| |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: following the system 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. If both are specified, the value specified by updateDuration is used.
- 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 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.
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. For details, see Metadata.|Object|Yes (initial value: left empty)| |dataProxyEnabled|Whether the widget supports the update-through-proxy feature.
- true: The widget supports the update-through-proxy feature.
- false: The widget does not support the update-through-proxy feature.
If this tag is set to true, the settings for the scheduled update time will still take effect, but the settings for the update interval and next update time will not.|Boolean|Yes (initial value: false)| |isDynamic|Whether the widget is a dynamic widget. This tag applies only to ArkTS widgets.
- true: The widget is a dynamic widget.
- false: The widget is a static widget.|Boolean|Yes (initial value: true)| |transparencyEnabled|Whether the widget host is allowed to set the background transparency of the widget. This tag applies only to ArkTS widgets.
- true: The widget host is allowed to set the background transparency of the widget.
- false: The widget host is not allowed to set the background transparency of the widget.
|Boolean|Yes (initial value: false)|

Table 2 Internal structure of the window object

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"
         ],
         "formConfigAbility": "",
         "formVisibleNotify": "",
         "dataProxyEnabled": false,
         "isDynamic": true,
         "transparencyEnabled": false,
         "metadata": {}
       }
     ]
   }