• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Configuring a Widget to Update Periodically
2
3Before configuring a widget to update periodically, enable the periodic update feature by setting the **updateEnabled** field to **true** in the **form_config.json** file.
4
5The widget framework provides the following modes of updating widgets periodically:
6
7
8- Set the update interval: The widget will be updated at the specified interval. You can specify the interval by setting the [updateDuration](arkts-ui-widget-configuration.md) field in the **form_config.json** file. For example, you can configure the widget to update once an hour.
9
10  > **NOTE**
11  >
12  > **updateDuration** takes precedence over **scheduledUpdateTime**. If both are specified, the value specified by **updateDuration** is used.
13
14  ```json
15  {
16    "forms": [
17      {
18        "name": "widget",
19        "description": "This is a service widget.",
20        "src": "./ets/widget/pages/WidgetCard.ets",
21        "uiSyntax": "arkts",
22        "window": {
23          "designWidth": 720,
24          "autoDesignWidth": true
25        },
26        "colorMode": "auto",
27        "isDefault": true,
28        "updateEnabled": true, // Enable the periodic update feature.
29        "scheduledUpdateTime": "10:30",
30        "updateDuration": 2, // Set the interval to update the widget. The value is a natural number, in the unit of 30 minutes.
31        "defaultDimension": "2*2",
32        "supportDimensions": ["2*2"]
33      }
34    ]
35  }
36  ```
37
38- Set the scheduled update time: The widget will be updated at the scheduled time every day. You can specify the time by setting the [scheduledUpdateTime](arkts-ui-widget-configuration.md) field in the **form_config.json** file. For example, you can configure the widget to update at 10:30 a.m. every day.
39
40  > **NOTE**
41  >
42  > **updateDuration** takes precedence over **scheduledUpdateTime**. For the **scheduledUpdateTime** settings to take effect, set **updateDuration** to **0**.
43
44
45  ```json
46  {
47    "forms": [
48      {
49        "name": "widget",
50        "description": "This is a service widget.",
51        "src": "./ets/widget/pages/WidgetCard.ets",
52        "uiSyntax": "arkts",
53        "window": {
54          "designWidth": 720,
55          "autoDesignWidth": true
56        },
57        "colorMode": "auto",
58        "isDefault": true,
59        "updateEnabled": true, // Enable the periodic update feature.
60        "scheduledUpdateTime": "10:30", // Set the scheduled time to update the widget.
61        "updateDuration": 0,
62        "defaultDimension": "2*2",
63        "supportDimensions": ["2*2"]
64      }
65    ]
66  }
67  ```
68
69- Set the next update time: The widget will be updated next time at the specified time. You can specify the time by calling the [setFormNextRefreshTime()](../reference/apis/js-apis-app-form-formProvider.md#setformnextrefreshtime) API. The minimum update interval is 5 minutes. For example, you can configure the widget to update within 5 minutes after the API is called.
70
71  ```ts
72  import formProvider from '@ohos.app.form.formProvider';
73
74  let formId = '123456789'; // Use the actual widget ID in real-world scenarios.
75  try {
76    // Configure the widget to update in 5 minutes.
77    formProvider.setFormNextRefreshTime(formId, 5, (err, data) => {
78      if (err) {
79        console.error(`Failed to setFormNextRefreshTime. Code: ${err.code}, message: ${err.message}`);
80        return;
81      } else {
82        console.info('Succeeded in setFormNextRefreshTimeing.');
83      }
84    });
85  } catch (err) {
86    console.error(`Failed to setFormNextRefreshTime. Code: ${err.code}, message: ${err.message}`);
87  }
88  ```
89
90
91When periodic update is triggered, the system calls the [onUpdateForm()](../reference/apis/js-apis-app-form-formExtensionAbility.md#onupdateform) lifecycle callback of the FormExtensionAbility. In the callback, [updateForm()](../reference/apis/js-apis-app-form-formProvider.md#updateform) can be used to update the widget by the provider. For details about how to use **onUpdateForm()**, see [Updating Widget Content Through FormExtensionAbility](arkts-ui-widget-event-formextensionability.md).
92
93
94> **NOTE**
95> 1. Each widget can be updated at the specified interval for a maximum of 50 times every day, including updates triggered by setting [updateDuration](arkts-ui-widget-configuration.md) or calling [setFormNextRefreshTime()](../reference/apis/js-apis-app-form-formProvider.md#setformnextrefreshtime). When the limit is reached, the widget cannot be updated in this mode again. The number of update times is reset at 00:00 every day.
96>
97> 2. The same timer is used for timing updates at the specified interval. Therefore, the first scheduled update of widgets may have a maximum deviation of 30 minutes. For example, the first widget A (updated every half an hour) is added at 03:20. The timer starts and triggers an update every half an hour. The second widget B (updated every half an hour) is added at 03:40. When the timer event is triggered at 03:50, widget A is updated, and widget B will be updated at 04:20 next time.
98>
99> 3. Updates at the specified interval and updates at the scheduled time are triggered only when the screen is on. When the screen is off, the update action is merely recorded. When the screen is on, the update action is performed.
100