• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# ArkTS卡片被动刷新
2<!--Kit: Form Kit-->
3<!--Subsystem: Ability-->
4<!--Owner: @cx983299475-->
5<!--Designer: @xueyulong-->
6<!--Tester: @chenmingze-->
7<!--Adviser: @Brilliantry_Rui-->
8
9本文主要提供被动刷新的开发指导，刷新流程请参考[被动刷新概述](./arkts-ui-widget-interaction-overview.md#被动刷新)。
10
11## 卡片定时刷新
12
13当前卡片框架提供了如下两种按时间刷新卡片的方式：
14
15- 定时刷新：表示在一定时间间隔内调用[onUpdateForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#formextensionabilityonupdateform)的生命周期回调函数自动刷新卡片内容。可以在[form_config.json](arkts-ui-widget-configuration.md#配置文件字段说明)配置文件的`updateDuration`字段中进行设置。例如，可以将`updateDuration`字段的值设置为2，表示刷新时间间隔为2个30分钟，即1小时。
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 > **说明：**
43  >
44  > 在使用定时刷新时，需要在form_config.json配置文件中设置`updateEnabled`字段为`true`，以启用周期性刷新功能。
45
46- 下次刷新：表示指定卡片的下一次刷新时间。可以通过调用[setFormNextRefreshTime](../reference/apis-form-kit/js-apis-app-form-formProvider.md#formprovidersetformnextrefreshtime)接口来实现。最短刷新时间为5分钟。例如，可以在接口调用后的5分钟内刷新卡片内容。
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        // 设置过5分钟后更新卡片内容
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
79在触发定时、下次刷新后，系统会调用FormExtensionAbility的[onUpdateForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#formextensionabilityonupdateform)生命周期回调，在回调中，可以使用[updateForm](../reference/apis-form-kit/js-apis-app-form-formProvider.md#formproviderupdateform)进行提供方刷新卡片。`onUpdateForm`生命周期回调的使用请参见[卡片生命周期管理](./arkts-ui-widget-lifecycle.md)。
80
81**约束限制：**
821. 定时刷新有配额限制，每张卡片每天最多通过定时方式触发刷新50次，定时刷新次数可以通过修改[卡片配置项updateDuration字段](arkts-ui-widget-configuration.md#配置文件字段说明)、或调用[setFormNextRefreshTime](../reference/apis-form-kit/js-apis-app-form-formProvider.md#formprovidersetformnextrefreshtime)接口两种方式进行设置，当达到50次配额后，无法通过定时方式再次触发刷新，刷新次数会在每天的0点重置。
83>
842. 当前定时刷新使用同一个计时器进行计时，因此卡片定时刷新的第一次刷新会有最多30分钟的偏差。比如第一张卡片A（每隔半小时刷新一次）在3点20分添加成功，定时器启动并每隔半小时触发一次事件，第二张卡片B(每隔半小时刷新一次)在3点40分添加成功，在3点50分定时器事件触发时，卡片A触发定时刷新，卡片B会在下次事件（4点20分）中才会触发。
85>
863. 定时刷新在卡片可见情况下才会触发，在卡片不可见时仅会记录刷新动作和刷新数据，待可见时统一刷新布局。
87>
884. 如果使能了卡片代理刷新，定时刷新和下次刷新不生效。
89
90## 卡片定点刷新
91
92当前卡片框架提供了如下两种定点刷新卡片的方式：
93
94- 单定点刷新：表示在每天的某个特定时间点自动刷新卡片内容。可以在form_config.json配置文件中的`scheduledUpdateTime`字段中进行设置。例如，可以将刷新时间设置为每天的上午10点30分。
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- 多定点刷新：表示在每天的多个特定时间点自动刷新卡片内容。可以在form_config.json配置文件中的`multiScheduledUpdateTime`字段中进行设置，例如，可以将刷新时间设置为每天的上午11点30分和下午4点30分。
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
151在触发定点刷新后，系统会调用FormExtensionAbility的[onUpdateForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#formextensionabilityonupdateform)生命周期回调，在回调中，可以使用[updateForm](../reference/apis-form-kit/js-apis-app-form-formProvider.md#formproviderupdateform)进行提供方刷新卡片。`onUpdateForm`生命周期回调的使用请参见[卡片生命周期管理](./arkts-ui-widget-lifecycle.md)。
152
153> **说明：**
154> 1. 当同时配置了定时刷新`updateDuration`和定点刷新`scheduledUpdateTime`时，定时刷新的优先级更高且定点刷新不会执行。如果想要配置定点刷新，则需要将`updateDuration`配置为0。
155> 2. `multiScheduledUpdateTime`的配置最多可设置24个时间。
156> 3. 同时配置了单定点和多定点刷新，多定点刷新配置生效，单定点刷新配置不生效。
157> 4. 考虑到向前兼容的问题，尽量保留`scheduledUpdateTime`字段，不要直接删除。
158
159**约束限制：**
1601. 定点刷新在卡片可见情况下才会触发，在卡片不可见时仅会记录刷新动作和刷新数据，待可见时统一刷新布局。
161<!--Del-->
162
163## 卡片条件刷新
164
165当前卡片框架提供了如下按条件刷新卡片的方式：
166
167- 网络刷新：表示在网络变化的场景下调用[onUpdateForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#formextensionabilityonupdateform)的生命周期回调函数自动刷新卡片内容。可以在[form_config.json](arkts-ui-widget-configuration.md)配置文件的`conditionUpdate`字段中进行设置，设置字段为network。
168
169> **说明：**
170> 1. 当从无网络到有网络连接时会触发刷新。而网络间切换（例如：WiFi间切换，WiFi到流量，流量到WiFi），或从有网络连接到无网络连接时不会触发刷新。
171>
172> 2. 为减少卡片在频繁开关网络场景进程启动次数，无网判定需要网络连续断开十分钟后，才会认为无网，下次联网后触发网络刷新。
173>
174> 3. 仅对系统应用的卡片生效。
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-->