• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Interval-based Widget Updates
2
3Form Kit provides the following methods for interval-based updates:
4
5- Setting the update interval: The widget content will be automatically updated at the specified interval by calling [onUpdateForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#onupdateform). The interval is specified by the `updateDuration` field in the [form_config.json](arkts-ui-widget-configuration.md) file. For example, if **updateDuration** is set to **2**, the widget is updated every hour.
6
7  ```json
8  {
9    "forms": [
10      {
11        "name": "UpdateDuration",
12        "description": "$string:widget_updateduration_desc",
13        "src": "./ets/updateduration/pages/UpdateDurationCard.ets",
14        "uiSyntax": "arkts",
15        "window": {
16          "designWidth": 720,
17          "autoDesignWidth": true
18        },
19        "colorMode": "auto",
20        "isDefault": true,
21        "updateEnabled": true,
22        "scheduledUpdateTime": "10:30",
23        "updateDuration": 2,
24        "defaultDimension": "2*2",
25        "supportDimensions": [
26          "2*2"
27        ]
28      }
29    ]
30  }
31  ```
32  > **NOTE**
33  >
34  > To use interval-based updates, set the **updateEnabled** field to **true** in the **form_config.json** file.
35  >
36  > To reduce the number of passive periodic update times and power consumption of widgets, the update interval can be set from the application market – for applications that are being or have been installed.
37  > - If an update interval is set from the application market, it is compared with the value of `updateDuration` in the **form_config.json** file. Whichever longer is used.
38  > - If no update interval is set from the application market, the value in the **form_config.json** file is used.
39  > - This rule does not apply when the interval-based update feature is disabled.
40  > - The update interval set from the application market ranges from 1 to 336, in the unit of 30 minutes. That is, the minimum update interval is half an hour (1 x 30 minutes) and the maximum update interval is one week (336 x 30 minutes).
41  > - This rule takes effect since API version 11. In earlier versions, the interval-based update follows the settings in the **form_config.json** file.
42
43- Setting the next update time: The widget will be updated next time at the specified time, which is specified by calling [setFormNextRefreshTime](../reference/apis-form-kit/js-apis-app-form-formProvider.md#setformnextrefreshtime), at the minimum of 5 minutes. For example, you can configure the widget to update within 5 minutes after the API is called.
44
45  ```ts
46  import { FormExtensionAbility, formProvider } from '@kit.FormKit';
47  import { hilog } from '@kit.PerformanceAnalysisKit';
48  import { BusinessError } from '@kit.BasicServicesKit';
49
50  const TAG: string = 'UpdateByTimeFormAbility';
51  const FIVE_MINUTE: number = 5;
52  const DOMAIN_NUMBER: number = 0xFF00;
53
54  export default class UpdateByTimeFormAbility extends FormExtensionAbility {
55    onFormEvent(formId: string, message: string): void {
56      // Called when a specified message event defined by the form provider is triggered.
57      hilog.info(DOMAIN_NUMBER, TAG, `FormAbility onFormEvent, formId = ${formId}, message: ${JSON.stringify(message)}`);
58      try {
59        // Configure the widget to update in 5 minutes.
60        formProvider.setFormNextRefreshTime(formId, FIVE_MINUTE, (err: BusinessError) => {
61          if (err) {
62            hilog.info(DOMAIN_NUMBER, TAG, `Failed to setFormNextRefreshTime. Code: ${err.code}, message: ${err.message}`);
63            return;
64          } else {
65            hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in setFormNextRefreshTiming.');
66          }
67        });
68      } catch (err) {
69        hilog.info(DOMAIN_NUMBER, TAG, `Failed to setFormNextRefreshTime. Code: ${(err as BusinessError).code}, message: ${(err as BusinessError).message}`);
70      }
71    }
72    // ...
73  }
74  ```
75
76When an interval-based update is triggered, the system calls the [onUpdateForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#onupdateform) lifecycle callback of the FormExtensionAbility. In the callback, [updateForm](../reference/apis-form-kit/js-apis-app-form-formProvider.md#updateform) can be used to update the widget. For details about how to use `onUpdateForm`, see [Widget Lifecycle Management](./arkts-ui-widget-lifecycle.md).
77
78**Constraints**
791. 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-form-kit/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.
802. A single timer is used for interval-based updates. Therefore, if a widget is configured to update at specified intervals, the first update may have a maximum deviation of 30 minutes. For example, if widget A (updated every half an hour) is added at 03:20 and widget B (also updated every half an hour) is added at 03:40, the first update of widget B has a deviation of 10 minutes to the expected time: The timer starts at 03:20 when widget A is added, triggers an update for widget A at 03:50, and triggers another update for widget B at 04:20 (instead of 04:10 as expected).
813. Interval-based updates are triggered only when the widget is visible. If the widget is invisible, the update action and data are recorded. The layout is refreshed once the widget becomes visible.
824. If the update-through-proxy feature is enabled, the settings for the update interval and next update time will not take effect.
83