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`字段中进行设置。例如,可以将`updateDuration`字段的值设置为2,表示刷新时间设置为每小时一次。 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 > **说明:** 33 > 34 > 1. 在使用定时刷新时,需要在form_config.json配置文件中设置`updateEnabled`字段为`true`,以启用周期性刷新功能。 35 > 36 > 2. 为减少卡片被动周期刷新进程启动次数,降低卡片刷新功耗,应用市场在安装应用时可以为该应用配置刷新周期, 37 > 也可以为已经安装的应用动态配置刷新周期,用来限制卡片刷新周期的时长,以达到降低周期刷新进程启动次数的目的。 38 > <br/> ● 当配置了`updateDuration`(定时刷新)后,若应用市场动态配置了该应用的刷新周期, 39 > 卡片框架会将form_config.json文件中配置的刷新周期与应用市场配置的刷新周期进行比较,取较长的刷新周期做为该卡片的定时刷新周期。 40 > <br/> ● 若应用市场未动态配置该应用的刷新周期,则以form_config.json文件中配置的刷新周期为准。 41 > <br/> ● 若该卡片取消定时刷新功能,该规则将无效。 42 > <br/> ● 卡片定时刷新的更新周期单位为30分钟。应用市场配置的刷新周期范围是1~336,即最短为半小时(1 * 30min)刷新一次,最长为一周(336 * 30min)刷新一次。 43 > <br/> ● 该规则从API11开始生效。若小于API11,则以form_config.json文件中配置的刷新周期为准。 44 45- 下次刷新:表示指定卡片的下一次刷新时间。可以通过调用[setFormNextRefreshTime](../reference/apis-form-kit/js-apis-app-form-formProvider.md#setformnextrefreshtime)接口来实现。最短刷新时间为5分钟。例如,可以在接口调用后的5分钟内刷新卡片内容。 46 47 ```ts 48 import { FormExtensionAbility, formProvider } from '@kit.FormKit'; 49 import { hilog } from '@kit.PerformanceAnalysisKit'; 50 import { BusinessError } from '@kit.BasicServicesKit'; 51 52 const TAG: string = 'UpdateByTimeFormAbility'; 53 const FIVE_MINUTE: number = 5; 54 const DOMAIN_NUMBER: number = 0xFF00; 55 56 export default class UpdateByTimeFormAbility extends FormExtensionAbility { 57 onFormEvent(formId: string, message: string): void { 58 // Called when a specified message event defined by the form provider is triggered. 59 hilog.info(DOMAIN_NUMBER, TAG, `FormAbility onFormEvent, formId = ${formId}, message: ${JSON.stringify(message)}`); 60 try { 61 // 设置过5分钟后更新卡片内容 62 formProvider.setFormNextRefreshTime(formId, FIVE_MINUTE, (err: BusinessError) => { 63 if (err) { 64 hilog.info(DOMAIN_NUMBER, TAG, `Failed to setFormNextRefreshTime. Code: ${err.code}, message: ${err.message}`); 65 return; 66 } else { 67 hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in setFormNextRefreshTiming.'); 68 } 69 }); 70 } catch (err) { 71 hilog.info(DOMAIN_NUMBER, TAG, `Failed to setFormNextRefreshTime. Code: ${(err as BusinessError).code}, message: ${(err as BusinessError).message}`); 72 } 73 } 74 // ... 75 } 76 ``` 77 78在触发定时、下次刷新后,系统会调用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`生命周期回调的使用请参见[卡片生命周期管理](./arkts-ui-widget-lifecycle.md)。 79 80**约束限制:** 811. 定时刷新有配额限制,每张卡片每天最多通过定时方式触发刷新50次,定时刷新次数包含[卡片配置项updateDuration](arkts-ui-widget-configuration.md)和调用[setFormNextRefreshTime](../reference/apis-form-kit/js-apis-app-form-formProvider.md#setformnextrefreshtime)方法两种方式,当达到50次配额后,无法通过定时方式再次触发刷新,刷新次数会在每天的0点重置。 82> 832. 当前定时刷新使用同一个计时器进行计时,因此卡片定时刷新的第一次刷新会有最多30分钟的偏差。比如第一张卡片A(每隔半小时刷新一次)在3点20分添加成功,定时器启动并每隔半小时触发一次事件,第二张卡片B(每隔半小时刷新一次)在3点40分添加成功,在3点50分定时器事件触发时,卡片A触发定时刷新,卡片B会在下次事件(4点20分)中才会触发。 84> 853. 定时刷新在卡片可见情况下才会触发,在卡片不可见时仅会记录刷新动作和刷新数据,待可见时统一刷新布局。 86> 874. 如果使能了卡片代理刷新,定时刷新和下次刷新不生效。 88