概述
ArkTS卡片框架提供了 updateForm 接口和requestForm接口主动触发卡片的页面刷新,通过 LocalStorageProp 确认需要刷新的卡片数据。
接口 | 是否系统能力 | 约束 |
---|---|---|
updateForm | 否 | 1. 提供方调用。 2. 提供方仅允许刷新自己的卡片,其他提供方的卡片无法刷新。 |
requestForm | 是 | 1. 使用方调用。 2. 仅允许刷新添加到当前使用方的卡片,添加到其他使用方的卡片无法刷新。 |
下面介绍卡片页面刷新的典型场景。
- 卡片定时刷新和定点刷新
- 刷新本地图片和网络图片
- 根据卡片状态刷新不同内容
卡片定时刷新和定点刷新
当前卡片框架提供了如下几种按时间刷新卡片的方式:
- 定时刷新:表示在一定时间间隔内调用 onUpdateForm 的生命周期回调函数自动刷新卡片内容。可以在form_config.json配置文件的 updateDuration 字段中进行设置。例如,可以将刷新时间设置为每小时一次。
说明 :
- 在使用定时和定点刷新功能之前,需要在form_config.json配置文件中设置updateEnabled字段为true,以启用周期性刷新功能。
当配置了updateDuration(定时刷新)后,该设置会优先于scheduledUpdateTime(定点刷新)生效,即使同时配置了两者,定点刷新也会被忽略。
- 为减少卡片被动周期刷新进程启动次数,降低卡片刷新功耗,应用市场在安装应用时可以为该应用配置刷新周期,
也可以为已经安装的应用动态配置刷新周期,用来限制卡片刷新周期的时长,以达到降低周期刷新进程启动次数的目的。
● 当配置了updateDuration(定时刷新)后,若应用市场动态配置了该应用的刷新周期,
卡片框架会将form_config.json文件中配置的刷新周期与应用市场配置的刷新周期进行比较,取较长的刷新周期做为该卡片的定时刷新周期。
● 若应用市场未动态配置该应用的刷新周期,则以form_config.json文件中配置的刷新周期为准。
● 若该卡片取消定时刷新功能,该规则将无效。
● 卡片定时刷新的更新周期单位为30分钟。应用市场配置的刷新周期范围是1~336,即最短为半小时(1 * 30min)刷新一次,最长为一周(336 * 30min)刷新一次。
● 该规则从API11开始生效。若小于API11,则以form_config.json文件中配置的刷新周期为准。
{
"forms": [
{
"name": "UpdateDuration",
"description": "$string:widget_updateduration_desc",
"src": "./ets/updateduration/pages/UpdateDurationCard.ets",
"uiSyntax": "arkts",
"window": {
"designWidth": 720,
"autoDesignWidth": true
},
"colorMode": "auto",
"isDefault": true,
"updateEnabled": true,
"scheduledUpdateTime": "10:30",
"updateDuration": 2,
"defaultDimension": "2*2",
"supportDimensions": [
"2*2"
]
}
]
}
- 定点刷新:表示在每天的某个特定时间点自动刷新卡片内容。可以在form_config.json配置文件中的 scheduledUpdateTime 字段中进行设置。例如,可以将刷新时间设置为每天的上午10点30分。
说明
当同时配置了定时刷新(updateDuration)和定点刷新(scheduledUpdateTime)时,定时刷新的优先级更高。如果想要配置定点刷新,则需要将updateDuration配置为0。
{
"forms": [
{
"name": "ScheduledUpdateTime",
"description": "$string:widget_scheupdatetime_desc",
"src": "./ets/scheduledupdatetime/pages/ScheduledUpdateTimeCard.ets",
"uiSyntax": "arkts",
"window": {
"designWidth": 720,
"autoDesignWidth": true
},
"colorMode": "auto",
"isDefault": true,
"updateEnabled": true,
"scheduledUpdateTime": "10:30",
"updateDuration": 0,
"defaultDimension": "2*2",
"supportDimensions": [
"2*2"
]
}
]
}
- 下次刷新:表示指定卡片的下一次刷新时间。可以通过调用 setFormNextRefreshTime 接口来实现。最短刷新时间为5分钟。例如,可以在接口调用后的5分钟内刷新卡片内容。
import { FormExtensionAbility, formProvider } from '@kit.FormKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';
const TAG: string = 'UpdateByTimeFormAbility';
const FIVE_MINUTE: number = 5;
const DOMAIN_NUMBER: number = 0xFF00;
export default class UpdateByTimeFormAbility extends FormExtensionAbility {
onFormEvent(formId: string, message: string): void {
// Called when a specified message event defined by the form provider is triggered.
hilog.info(DOMAIN_NUMBER, TAG, `FormAbility onFormEvent, formId = ${formId}, message: ${JSON.stringify(message)}`);
try {
// 设置过5分钟后更新卡片内容
formProvider.setFormNextRefreshTime(formId, FIVE_MINUTE, (err: BusinessError) => {
if (err) {
hilog.info(DOMAIN_NUMBER, TAG, `Failed to setFormNextRefreshTime. Code: ${err.code}, message: ${err.message}`);
return;
} else {
hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in setFormNextRefreshTiming.');
}
});
} catch (err) {
hilog.info(DOMAIN_NUMBER, TAG, `Failed to setFormNextRefreshTime. Code: ${(err as BusinessError).code}, message: ${(err as BusinessError).message}`);
}
}
...
}
在触发定时、定点或下次刷新后,系统会调用FormExtensionAbility的 onUpdateForm 生命周期回调,在回调中,可以使用 updateForm 进行提供方刷新卡片。onUpdateForm生命周期回调的使用请参见 通过FormExtensionAbility刷新卡片内容。
说明:
- 定时刷新有配额限制,每张卡片每天最多通过定时方式触发刷新50次,定时刷新包含 卡片配置项updateDuration 和调用 setFormNextRefreshTime 方法两种方式,当达到50次配额后,无法通过定时方式再次触发刷新,刷新次数会在每天的0点重置。
- 当前定时刷新使用同一个计时器进行计时,因此卡片定时刷新的第一次刷新会有最多30分钟的偏差。比如第一张卡片A(每隔半小时刷新一次)在3点20分添加成功,定时器启动并每隔半小时触发一次事件,第二张卡片B(每隔半小时刷新一次)在3点40分添加成功,在3点50分定时器事件触发时,卡片A触发定时刷新,卡片B会在下次事件(4点20分)中才会触发。
- 定时刷新和定点刷新仅在屏幕亮屏情况下才会触发,在灭屏场景下仅会记录刷新动作,待亮屏时统一进行