1# Passive Update of ArkTS Widgets 2<!--Kit: Form Kit--> 3<!--Subsystem: Ability--> 4<!--Owner: @cx983299475--> 5<!--Designer: @xueyulong--> 6<!--Tester: @chenmingze--> 7<!--Adviser: @Brilliantry_Rui--> 8 9This section provides the development guidelines for passive update. For details about the update process, see [Passive Update](./arkts-ui-widget-interaction-overview.md#passive-update). 10 11## Interval-based Update 12 13Form Kit provides the following methods for interval-based update: 14 15- 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#formextensionabilityonupdateform). The interval is specified by the `updateDuration` field in the [form_config.json](arkts-ui-widget-configuration.md#fields-in-configuration-file) file. For example, the value of the `updateDuration` field can be set to **2**, indicating that the update interval is 1 hour (2 periods of 30 minutes). 16 17 ```json 18 { 19 "forms": [ 20 { 21 "name": "UpdateDuration", 22 "description": "$string:widget_updateduration_desc", 23 "src": "./ets/updateduration/pages/UpdateDurationCard.ets", 24 "uiSyntax": "arkts", 25 "window": { 26 "designWidth": 720, 27 "autoDesignWidth": true 28 }, 29 "colorMode": "auto", 30 "isDefault": true, 31 "updateEnabled": true, 32 "scheduledUpdateTime": "10:30", 33 "updateDuration": 2, 34 "defaultDimension": "2*2", 35 "supportDimensions": [ 36 "2*2" 37 ] 38 } 39 ] 40 } 41 ``` 42 > **NOTE** 43 > 44 > To use interval-based update, set the `updateEnabled` field to `true` in the **form_config.json** file. 45 46- Setting the next update time: The widget will be updated at the next specified time, which is specified by calling [setFormNextRefreshTime](../reference/apis-form-kit/js-apis-app-form-formProvider.md#formprovidersetformnextrefreshtime), at the minimum of 5 minutes. For example, you can configure the widget to update within 5 minutes after the API is called. 47 48 ```ts 49 import { FormExtensionAbility, formProvider } from '@kit.FormKit'; 50 import { hilog } from '@kit.PerformanceAnalysisKit'; 51 import { BusinessError } from '@kit.BasicServicesKit'; 52 53 const TAG: string = 'UpdateByTimeFormAbility'; 54 const FIVE_MINUTE: number = 5; 55 const DOMAIN_NUMBER: number = 0xFF00; 56 57 export default class UpdateByTimeFormAbility extends FormExtensionAbility { 58 onFormEvent(formId: string, message: string): void { 59 // Called when a specified message event defined by the form provider is triggered. 60 hilog.info(DOMAIN_NUMBER, TAG, `FormAbility onFormEvent, formId = ${formId}, message: ${JSON.stringify(message)}`); 61 try { 62 // Configure the widget to update in 5 minutes. 63 formProvider.setFormNextRefreshTime(formId, FIVE_MINUTE, (err: BusinessError) => { 64 if (err) { 65 hilog.info(DOMAIN_NUMBER, TAG, `Failed to setFormNextRefreshTime. Code: ${err.code}, message: ${err.message}`); 66 return; 67 } else { 68 hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in setFormNextRefreshTiming.'); 69 } 70 }); 71 } catch (err) { 72 hilog.info(DOMAIN_NUMBER, TAG, `Failed to setFormNextRefreshTime. Code: ${(err as BusinessError).code}, message: ${(err as BusinessError).message}`); 73 } 74 } 75 // ... 76 } 77 ``` 78 79When interval-based update or next update is triggered, the system calls the [onUpdateForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#formextensionabilityonupdateform) lifecycle callback of the FormExtensionAbility. In the callback, [updateForm](../reference/apis-form-kit/js-apis-app-form-formProvider.md#formproviderupdateform) can be used to update the widget. For details about how to use `onUpdateForm`, see [Widget Lifecycle Management](./arkts-ui-widget-lifecycle.md). 80 81**Constraints** 821. Each widget can be updated at the specified interval for a maximum of 50 times every day, including updates triggered by modifying the [updateDuration](arkts-ui-widget-configuration.md#fields-in-configuration-file) field or calling [setFormNextRefreshTime](../reference/apis-form-kit/js-apis-app-form-formProvider.md#formprovidersetformnextrefreshtime). 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. 83> 842. 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). 85> 863. 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. 87> 884. If the update-through-proxy feature is enabled, the settings for the update interval and next update time will not take effect. 89 90## Time-specific Update 91 92Form Kit provides the following methods for time-specific widget update: 93 94- Setting a single update time: The widget content will be automatically updated at a designated time every day. This time is specified by the `scheduledUpdateTime` field in the **form_config.json** file. For example, you can configure the widget to update at 10:30 every day. 95 96 97 ```json 98 { 99 "forms": [ 100 { 101 "name": "ScheduledUpdateTime", 102 "description": "$string:widget_scheupdatetime_desc", 103 "src": "./ets/scheduledupdatetime/pages/ScheduledUpdateTimeCard.ets", 104 "uiSyntax": "arkts", 105 "window": { 106 "designWidth": 720, 107 "autoDesignWidth": true 108 }, 109 "colorMode": "auto", 110 "isDefault": true, 111 "updateEnabled": true, 112 "scheduledUpdateTime": "10:30", 113 "updateDuration": 0, 114 "defaultDimension": "2*2", 115 "supportDimensions": [ 116 "2*2" 117 ] 118 } 119 ] 120 } 121 ``` 122 123- Setting multiple update times: The widget content will be automatically updated at several specific times every day. These times are specified by the `multiScheduledUpdateTime` field in the **form_config.json** file. For example, you can configure the widget to update at 11:30 and 16:30 every day. 124 ```json 125 { 126 "forms": [ 127 { 128 "name": "ScheduledUpdateTime", 129 "description": "$string:widget_scheupdatetime_desc", 130 "src": "./ets/scheduledupdatetime/pages/ScheduledUpdateTimeCard.ets", 131 "uiSyntax": "arkts", 132 "window": { 133 "designWidth": 720, 134 "autoDesignWidth": true 135 }, 136 "colorMode": "auto", 137 "isDefault": true, 138 "updateEnabled": true, 139 "scheduledUpdateTime": "10:30", 140 "multiScheduledUpdateTime": "11:30,16:30,", 141 "updateDuration": 0, 142 "defaultDimension": "2*2", 143 "supportDimensions": [ 144 "2*2" 145 ] 146 } 147 ] 148 } 149 ``` 150 151When a time-specific update is triggered, the system calls the [onUpdateForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#formextensionabilityonupdateform) lifecycle callback of the FormExtensionAbility. In the callback, [updateForm](../reference/apis-form-kit/js-apis-app-form-formProvider.md#formproviderupdateform) can be used to update the widget. For details about how to use `onUpdateForm`, see [Widget Lifecycle Management](./arkts-ui-widget-lifecycle.md). 152 153> **NOTE** 154> 1. If both interval-based update (`updateDuration`) and time-specific update (`scheduledUpdateTime`) are configured, the interval-based update takes precedence, and the time-specific update will not be executed. To enable time-specific updates, set `updateDuration` to **0**. 155> 2. A maximum of 24 times can be set for `multiScheduledUpdateTime`. 156> 3. If both update at a single time and update at multiple times are configured, only the update at multiple times takes effect. 157> 4. To ensure forward compatibility, retain the `scheduledUpdateTime` field. 158 159**Constraints** 1601. 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. 161<!--Del--> 162 163## Conditional Update 164 165Form Kit provides the following methods for conditional updates: 166 167- Network-triggered update: The widget content will be automatically updated by calling [onUpdateForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#formextensionabilityonupdateform) when the network changes. This can be configured by setting the `conditionUpdate` field in the [form_config.json](arkts-ui-widget-configuration.md) file to **network**. 168 169> **NOTE** 170> 1. A widget update is triggered when the device transitions from a no-network state to a connected state. However, an update is not triggered when a user switches between networks (for example, switching between different Wi-Fi networks or between Wi-Fi and cellular data) or goes from Internet connection to no Internet connection. 171> 172> 2. To minimize the frequency of widget process initiations during frequent network on/off scenarios, a no-network condition is determined after the network has been continuously unavailable for 10 minutes. Upon reconnection, a network-based update is then triggered. 173> 174> 3. This functionality is valid only for widgets of system applications. 175 176 177 ```json 178 { 179 "forms": [ 180 { 181 "name": "UpdateDuration", 182 "description": "$string:widget_updateduration_desc", 183 "src": "./ets/updateduration/pages/UpdateDurationCard.ets", 184 "uiSyntax": "arkts", 185 "window": { 186 "designWidth": 720, 187 "autoDesignWidth": true 188 }, 189 "colorMode": "auto", 190 "isDefault": true, 191 "updateEnabled": true, 192 "scheduledUpdateTime": "10:30", 193 "updateDuration": 2, 194 "defaultDimension": "2*2", 195 "supportDimensions": [ 196 "2*2" 197 ], 198 "conditionUpdate": [ 199 "network" 200 ] 201 } 202 ] 203 } 204 ``` 205 <!--DelEnd--> 206