本文主要提供被动刷新的开发指导,刷新流程请参考被动刷新概述。
当前卡片框架提供了如下两种按时间刷新卡片的方式:
定时刷新:表示在一定时间间隔内调用onUpdateForm的生命周期回调函数自动刷新卡片内容。可以在form_config.json配置文件的updateDuration字段中进行设置。例如,可以将updateDuration字段的值设置为2,表示刷新时间间隔为2个30分钟,即1小时。
{
"forms": [
{
"name": "UpdateDuration",
"description": "$string:widget_updateduration_desc",
"src": "./ets/updateduration/pages/UpdateDurationCard.ets",
"uiSyntax": "arkts",
"window": {
"designWidth": 720,
"autoDesignWidth": true
},
"isDefault": true,
"updateEnabled": true,
"scheduledUpdateTime": "10:30",
"updateDuration": 2,
"defaultDimension": "2*2",
"supportDimensions": [
"2*2"
]
}
]
}
在使用定时刷新时,需要在form_config.json配置文件中设置updateEnabled字段为true,以启用周期性刷新功能。
下次刷新:表示指定卡片的下一次刷新时间。可以通过调用setFormNextRefreshTime接口来实现。最短刷新时间为5分钟。例如,可以设置卡片在调用接口5分钟后刷新。
// entry/src/main/ets/updatebytimeformability/UpdateByTimeFormAbility.ts
import { formBindingData, FormExtensionAbility, formInfo, formProvider } from '@kit.FormKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { Want } from '@kit.AbilityKit';
const TAG: string = 'UpdateByTimeFormAbility';
const FIVE_MINUTE: number = 5;
const DOMAIN_NUMBER: number = 0xFF00;
export default class UpdateByTimeFormAbility extends FormExtensionAbility {
onAddForm(want: Want): formBindingData.FormBindingData {
// 卡片使用方创建卡片时触发,返回卡片数据绑定类
let formData: Record<string, Object | string> = {};
return formBindingData.createFormBindingData(formData);
}
// ...
onFormEvent(formId: string, message: string): void {
// 当卡片提供方的postCardAction接口的message事件被触发时调用
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.error(DOMAIN_NUMBER, TAG,
`Failed to setFormNextRefreshTime. Code: ${err.code}, message: ${err.message}`);
return;
} else {
hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in setFormNextRefreshTime.');
}
});
} catch (err) {
hilog.error(DOMAIN_NUMBER, TAG,
`Failed to setFormNextRefreshTime. Code: ${(err as BusinessError).code},
message: ${(err as BusinessError).message}`);
}
}
onAcquireFormState(want: Want): formInfo.FormState {
// 卡片使用方查询卡片状态时触发该回调,默认返回初始状态。
return formInfo.FormState.READY;
}
} 在触发定时、下次刷新后,系统会调用FormExtensionAbility的onUpdateForm生命周期回调,在回调中,可以使用updateForm接口刷新卡片内容。onUpdateForm生命周期回调的使用请参见卡片生命周期管理。
约束限制:
当前卡片框架提供了如下两种定点刷新卡片的方式:
单定点刷新:表示在每天的某个特定时间点自动刷新卡片内容。可以在form_config.json配置文件中的scheduledUpdateTime字段中进行设置。例如,可以将刷新时间设置为每天的上午10点30分。
{
"forms": [
{
"name": "ScheduledUpdateTime",
"description": "$string:widget_scheduledUpdateTime_desc",
"src": "./ets/scheduledupdatetime/pages/ScheduledUpdateTimeCard.ets",
"uiSyntax": "arkts",
"window": {
"designWidth": 720,
"autoDesignWidth": true
},
"isDefault": true,
"updateEnabled": true,
"scheduledUpdateTime": "10:30",
"updateDuration": 0,
"defaultDimension": "2*2",
"supportDimensions": [
"2*2"
]
}
]
} 多定点刷新:表示在每天的多个特定时间点自动刷新卡片内容。可以在form_config.json配置文件中的multiScheduledUpdateTime字段中进行设置,例如,可以将刷新时间设置为每天的上午11点30分和下午4点30分。
{
"forms": [
{
"name": "ScheduledUpdateTime",
"description": "$string:widget_scheduledUpdateTime_desc",
"src": "./ets/scheduledupdatetime/pages/ScheduledUpdateTimeCard.ets",
"uiSyntax": "arkts",
"window": {
"designWidth": 720,
"autoDesignWidth": true
},
"isDefault": true,
"updateEnabled": true,
"scheduledUpdateTime": "10:30",
"multiScheduledUpdateTime": "11:30,16:30",
"updateDuration": 0,
"defaultDimension": "2*2",
"supportDimensions": [
"2*2"
]
}
]
} 在触发定点刷新后,系统会调用FormExtensionAbility的onUpdateForm生命周期回调,在回调中,可以使用updateForm接口刷新卡片内容。onUpdateForm生命周期回调的使用请参见卡片生命周期管理。
约束限制:
当前卡片框架提供了如下按条件刷新卡片的方式:
当从无网络到有网络连接时会触发刷新。而网络间切换(例如:WiFi间切换,WiFi到流量,流量到WiFi),或从有网络连接到无网络连接时不会触发刷新。
为减少卡片在频繁开关网络场景进程启动次数,无网判定需要网络连续断开十分钟后,才会认为无网,下次联网后触发网络刷新。
{
"forms": [
{
"name": "UpdateDuration",
"description": "$string:widget_updateduration_desc",
"src": "./ets/updateduration/pages/UpdateDurationCard.ets",
"uiSyntax": "arkts",
"window": {
"designWidth": 720,
"autoDesignWidth": true
},
"isDefault": true,
"updateEnabled": true,
"scheduledUpdateTime": "10:30",
"updateDuration": 2,
"defaultDimension": "2*2",
"supportDimensions": [
"2*2"
],
"conditionUpdate": [
"network"
]
}
]
}