• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 卡片定时刷新和定点刷新
2
3当前卡片框架提供了如下几种按时间刷新卡片的方式：
4
5- 定时刷新：表示在一定时间间隔内调用[onUpdateForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#onupdateform)的生命周期回调函数自动刷新卡片内容。可以在[form_config.json](arkts-ui-widget-configuration.md)配置文件的`updateDuration`字段中进行设置。例如，可以将刷新时间设置为每小时一次。
6
7  > **说明：**
8  >
9  > 1. 在使用定时和定点刷新功能之前，需要在form_config.json配置文件中设置`updateEnabled`字段为`true`，以启用周期性刷新功能。
10  > 当配置了`updateDuration`（定时刷新）后，该设置会优先于`scheduledUpdateTime`（定点刷新）生效，即使同时配置了两者，定点刷新也会被忽略。
11  >
12  > 2. 为减少卡片被动周期刷新进程启动次数，降低卡片刷新功耗，应用市场在安装应用时可以为该应用配置刷新周期，
13  > 也可以为已经安装的应用动态配置刷新周期，用来限制卡片刷新周期的时长，以达到降低周期刷新进程启动次数的目的。
14  > <br/> ● 当配置了`updateDuration`（定时刷新）后，若应用市场动态配置了该应用的刷新周期，
15  > 卡片框架会将form_config.json文件中配置的刷新周期与应用市场配置的刷新周期进行比较，取较长的刷新周期做为该卡片的定时刷新周期。
16  > <br/> ● 若应用市场未动态配置该应用的刷新周期，则以form_config.json文件中配置的刷新周期为准。
17  > <br/> ● 若该卡片取消定时刷新功能，该规则将无效。
18  > <br/> ● 卡片定时刷新的更新周期单位为30分钟。应用市场配置的刷新周期范围是1~336，即最短为半小时(1 * 30min)刷新一次，最长为一周(336 * 30min)刷新一次。
19  > <br/> ● 该规则从API11开始生效。若小于API11，则以form_config.json文件中配置的刷新周期为准。
20
21  ```json
22  {
23    "forms": [
24      {
25        "name": "UpdateDuration",
26        "description": "$string:widget_updateduration_desc",
27        "src": "./ets/updateduration/pages/UpdateDurationCard.ets",
28        "uiSyntax": "arkts",
29        "window": {
30          "designWidth": 720,
31          "autoDesignWidth": true
32        },
33        "colorMode": "auto",
34        "isDefault": true,
35        "updateEnabled": true,
36        "scheduledUpdateTime": "10:30",
37        "updateDuration": 2,
38        "defaultDimension": "2*2",
39        "supportDimensions": [
40          "2*2"
41        ]
42      }
43    ]
44  }
45  ```
46
47- 定点刷新：表示在每天的某个特定时间点自动刷新卡片内容。可以在form_config.json配置文件中的`scheduledUpdateTime`字段中进行设置。例如，可以将刷新时间设置为每天的上午10点30分。
48
49  > **说明：**
50  >
51  > 当同时配置了定时刷新`updateDuration`和定点刷新`scheduledUpdateTime`时，定时刷新的优先级更高。如果想要配置定点刷新，则需要将`updateDuration`配置为0。
52
53  ```json
54  {
55    "forms": [
56    	{
57        "name": "ScheduledUpdateTime",
58        "description": "$string:widget_scheupdatetime_desc",
59        "src": "./ets/scheduledupdatetime/pages/ScheduledUpdateTimeCard.ets",
60        "uiSyntax": "arkts",
61        "window": {
62          "designWidth": 720,
63          "autoDesignWidth": true
64        },
65        "colorMode": "auto",
66        "isDefault": true,
67        "updateEnabled": true,
68        "scheduledUpdateTime": "10:30",
69        "updateDuration": 0,
70        "defaultDimension": "2*2",
71        "supportDimensions": [
72          "2*2"
73        ]
74      }
75    ]
76  }
77  ```
78
79- 下次刷新：表示指定卡片的下一次刷新时间。可以通过调用[setFormNextRefreshTime](../reference/apis-form-kit/js-apis-app-form-formProvider.md#setformnextrefreshtime)接口来实现。最短刷新时间为5分钟。例如，可以在接口调用后的5分钟内刷新卡片内容。
80
81  ```ts
82  import { FormExtensionAbility, formProvider } from '@kit.FormKit';
83  import { hilog } from '@kit.PerformanceAnalysisKit';
84  import { BusinessError } from '@kit.BasicServicesKit';
85
86  const TAG: string = 'UpdateByTimeFormAbility';
87  const FIVE_MINUTE: number = 5;
88  const DOMAIN_NUMBER: number = 0xFF00;
89
90  export default class UpdateByTimeFormAbility extends FormExtensionAbility {
91    onFormEvent(formId: string, message: string): void {
92      // Called when a specified message event defined by the form provider is triggered.
93      hilog.info(DOMAIN_NUMBER, TAG, `FormAbility onFormEvent, formId = ${formId}, message: ${JSON.stringify(message)}`);
94      try {
95        // 设置过5分钟后更新卡片内容
96        formProvider.setFormNextRefreshTime(formId, FIVE_MINUTE, (err: BusinessError) => {
97          if (err) {
98            hilog.info(DOMAIN_NUMBER, TAG, `Failed to setFormNextRefreshTime. Code: ${err.code}, message: ${err.message}`);
99            return;
100          } else {
101            hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in setFormNextRefreshTiming.');
102          }
103        });
104      } catch (err) {
105        hilog.info(DOMAIN_NUMBER, TAG, `Failed to setFormNextRefreshTime. Code: ${(err as BusinessError).code}, message: ${(err as BusinessError).message}`);
106      }
107    }
108    // ...
109  }
110  ```
111
112
113在触发定时、定点或下次刷新后，系统会调用FormExtensionAbility的[onUpdateForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#onupdateform)生命周期回调，在回调中，可以使用[updateForm](../reference/apis-form-kit/js-apis-app-form-formProvider.md#updateform)进行提供方刷新卡片。`onUpdateForm`生命周期回调的使用请参见[通过FormExtensionAbility刷新卡片内容](arkts-ui-widget-event-formextensionability.md)。
114
115
116> **说明：**
117> 1. 定时刷新有配额限制，每张卡片每天最多通过定时方式触发刷新50次，定时刷新包含[卡片配置项updateDuration](arkts-ui-widget-configuration.md)和调用[setFormNextRefreshTime](../reference/apis-form-kit/js-apis-app-form-formProvider.md#setformnextrefreshtime)方法两种方式，当达到50次配额后，无法通过定时方式再次触发刷新，刷新次数会在每天的0点重置。
118>
119> 2. 当前定时刷新使用同一个计时器进行计时，因此卡片定时刷新的第一次刷新会有最多30分钟的偏差。比如第一张卡片A（每隔半小时刷新一次）在3点20分添加成功，定时器启动并每隔半小时触发一次事件，第二张卡片B(每隔半小时刷新一次)在3点40分添加成功，在3点50分定时器事件触发时，卡片A触发定时刷新，卡片B会在下次事件（4点20分）中才会触发。
120>
121> 3. 定时刷新和定点刷新仅在屏幕亮屏情况下才会触发，在灭屏场景下仅会记录刷新动作，待亮屏时统一进行刷新。
122> 4. 如果使能了卡片代理刷新，定时刷新和下次刷新不生效。
123