登录
前端成功转鸿蒙开发者真实案例，教大家如何开发鸿蒙APP--ArkTS 卡片刷新机制
2026年1月12日 05:35
大家好，我是陈杨，一名有着8 年前端开发经验、6 年技术写作积淀的鸿蒙开发者，也是鸿蒙生态里的一名极客。
曾因前端行业的危机感居安思危，果断放弃饱和的 iOS、安卓赛道，在鸿蒙 API9 发布时，凭着前端技术底子，三天吃透 ArkTS 框架，快速上手鸿蒙开发。三年深耕，我不仅打造了鸿蒙开源图表组件库「莓创图表」，闯进过创新赛、极客挑战赛总决赛，更带着团队实实在在做出了成果 —— 目前已成功上架11 款鸿蒙应用，涵盖工具、效率、创意等多个品类，包括JLPT、REFLEX PRO、国潮纸刻、Wss 直连、ZenithDocs Pro、圣诞相册、CSS 特效等，靠这些自研产品赚到了转型后的第一桶金。
从前端转型到鸿蒙掘金，靠的不是运气，而是选对赛道的眼光和快速落地的执行力。今天这篇文章，就接着上一篇的内容，和大家聊聊 [ArkTS 卡片刷新机制]，这篇很重要，认真听。
在 ArkTS 卡片开发中，“内容刷新” 是核心功能之一 —— 无论是实时数据更新（如天气、新闻）、图片替换，还是基于状态的内容切换，都依赖高效的刷新机制。本文基于 HarmonyOS 官方文档，系统梳理卡片刷新的两种核心模式（主动刷新、被动刷新）、特殊场景实现（图片刷新、状态关联刷新）及关键约束，结合完整代码示例，帮助开发者精准落地各类刷新需求。
一、刷新机制核心概述
ArkTS 卡片的刷新能力由系统框架提供，核心依赖两套接口和配置体系：
- 主动刷新：由卡片提供方（应用）或使用方（如桌面）主动触发，适用于 “按需更新” 场景（如用户点击刷新按钮、应用数据变化）；
- 被动刷新：由系统根据预设规则自动触发，适用于 “周期性更新” 场景（如每天固定时间刷新、每隔 30 分钟更新）；
-
数据传递：刷新时的数据通过
formBindingData封装，卡片页面通过@LocalStorageProp接收（数据自动转为 string 类型），确保数据同步的一致性。
关键接口说明：
| 接口名 | 调用方 | 核心作用 | 约束 |
|---|---|---|---|
updateForm |
卡片提供方 | 主动刷新自身卡片内容 | 仅能刷新当前应用的卡片，无法操作其他应用卡片 |
requestForm |
卡片使用方（系统应用） | 主动请求刷新已添加的卡片 | 仅能刷新当前宿主中的卡片 |
setFormNextRefreshTime |
卡片提供方 | 设置下次刷新时间 | 最短刷新间隔 5 分钟 |
二、主动刷新：按需触发的精准更新
主动刷新是开发者最常使用的模式，核心是通过updateForm接口手动触发，可搭配用户交互、应用数据变化等场景使用。
2.1 核心实现：提供方主动刷新
卡片提供方（应用）通过formProvider.updateForm接口触发刷新，需传入目标卡片的formId（唯一标识）和更新后的数据。通常与onFormEvent（用户交互触发）、onUpdateForm（生命周期回调）搭配使用。
完整代码示例：用户点击按钮触发刷新
// 1. 卡片页面（WidgetCard.ets）：提供刷新按钮，通过postCardAction传递事件
let storage = new LocalStorage();
@Entry(storage)
@Component
struct RefreshButtonCard {
// 接收FormExtensionAbility传递的formId和数据
@LocalStorageProp('formId') formId: string = '';
@LocalStorageProp('currentData') currentData: string = '初始数据';
build() {
Column({ space: 20 })
.width('100%')
.height('100%')
.justifyContent(FlexAlign.Center)
.padding(15) {
Text(`当前内容：${this.currentData}`)
.fontSize(16)
.fontWeight(FontWeight.Medium)
// 点击按钮触发刷新事件
Button("手动刷新")
.width("80%")
.height(50)
.backgroundColor("#5A5FFF")
.fontColor("#FFFFFF")
.onClick(() => {
// 发送message事件给FormExtensionAbility，携带formId
postCardAction(this, {
action: "message",
params: {
formId: this.formId,
refreshType: "manual"
}
});
})
}
}
}
// 2. FormExtensionAbility（EntryFormAbility.ets）：接收事件并执行刷新
import {
formBindingData,
FormExtensionAbility,
formProvider,
formInfo
} from '@kit.FormKit';
import { Want, BusinessError } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
const TAG: string = 'EntryFormAbility';
const DOMAIN_NUMBER: number = 0xFF00;
export default class EntryFormAbility extends FormExtensionAbility {
// 卡片创建时，将formId存入LocalStorage（供页面使用）
onAddForm(want: Want): formBindingData.FormBindingData {
hilog.info(DOMAIN_NUMBER, TAG, '[onAddForm] 卡片创建');
// 获取卡片唯一ID
const formId = want.parameters?.[formInfo.FormParam.IDENTITY_KEY] as string;
// 初始化数据（包含formId）
const initData = {
formId: formId,
currentData: '初始数据'
};
return formBindingData.createFormBindingData(initData);
}
// 接收卡片页面的message事件，执行刷新
async onFormEvent(formId: string, message: string): Promise<void> {
const params = JSON.parse(message);
hilog.info(DOMAIN_NUMBER, TAG, `[onFormEvent] 触发手动刷新，formId: ${formId}`);
// 模拟获取新数据（实际场景可替换为接口请求、数据库查询等）
const newData = {
currentData: `刷新于 ${new Date().toLocaleTimeString()}`
};
// 封装刷新数据并调用updateForm
const formInfo = formBindingData.createFormBindingData(newData);
try {
await formProvider.updateForm(formId, formInfo);
hilog.info(DOMAIN_NUMBER, TAG, `[onFormEvent] 刷新成功`);
} catch (error) {
const err = error as BusinessError;
hilog.error(DOMAIN_NUMBER, TAG, `[onFormEvent] 刷新失败：code=${err.code}, msg=${err.message}`);
}
}
}
2.2 关键注意点
-
formId是核心标识：每个卡片实例的formId唯一，需通过want.parameters[formInfo.FormParam.IDENTITY_KEY]获取（卡片创建时）； - 异常处理必须：
updateForm可能因网络异常、权限不足失败，需通过try/catch捕获BusinessError； - 数据格式限制：传递的数据需为 JSON 可序列化类型（字符串、数字、对象），复杂类型需手动转换。
三、被动刷新：系统驱动的自动更新
被动刷新无需手动触发，由系统根据配置自动执行，核心分为 “定时刷新”“定点刷新”“下次刷新” 三类，适用于周期性数据更新场景。
3.1 定时刷新：固定间隔自动更新
定时刷新通过form_config.json的updateDuration字段配置，单位为 “30 分钟”，需配合updateEnabled: true启用。
配置示例（form_config.json）
{
"forms": [
{
"name": "WeatherWidget",
"src": "./ets/widget/pages/WeatherCard.ets",
"uiSyntax": "arkts",
"updateEnabled": true, // 启用周期性刷新
"updateDuration": 2, // 刷新周期：2 * 30分钟 = 1小时
"defaultDimension": "2*2",
"supportDimensions": ["2*2"],
"colorMode": "auto",
"isDefault": true
}
]
}
代码实现（EntryFormAbility.ets）
系统触发定时刷新时，会回调onUpdateForm方法，需在此方法中实现数据更新逻辑：
export default class EntryFormAbility extends FormExtensionAbility {
// 定时刷新触发时执行
async onUpdateForm(formId: string): void {
hilog.info(DOMAIN_NUMBER, TAG, `[onUpdateForm] 定时刷新触发，formId: ${formId}`);
// 模拟请求天气数据（实际场景替换为真实接口）
const newWeatherData = {
city: "北京",
temperature: "25℃",
updateTime: new Date().toLocaleTimeString()
};
const formInfo = formBindingData.createFormBindingData(newWeatherData);
try {
await formProvider.updateForm(formId, formInfo);
} catch (error) {
const err = error as BusinessError;
hilog.error(DOMAIN_NUMBER, TAG, `定时刷新失败：${err.message}`);
}
}
}
定时刷新核心约束
- 刷新周期规则：
updateDuration为自然数，0 表示不生效；API 11 及以上版本，若应用市场配置了刷新周期，取 “配置值” 和 “应用配置值” 的较大者（如应用配置 1 小时，市场配置 2 小时，则按 2 小时刷新）； - 配额限制：每张卡片每天最多定时刷新 50 次（包含
updateDuration和setFormNextRefreshTime两种方式），0 点重置； - 可见性影响：卡片不可见时，系统仅记录刷新动作，待卡片可见后统一刷新布局。
3.2 定点刷新：指定时间自动更新
定点刷新支持 “单时间点” 和 “多时间点” 配置，通过form_config.json的scheduledUpdateTime（单时间点）或multiScheduledUpdateTime（多时间点）字段设置，需关闭定时刷新（updateDuration: 0`）。
配置示例（多时间点刷新）
{
"forms": [
{
"name": "NewsWidget",
"src": "./ets/widget/pages/NewsCard.ets",
"uiSyntax": "arkts",
"updateEnabled": true,
"updateDuration": 0, // 关闭定时刷新，优先定点刷新
"scheduledUpdateTime": "10:30", // 单时间点（兼容旧版本）
"multiScheduledUpdateTime": "08:00,12:00,18:00", // 多时间点（最多24个）
"defaultDimension": "2*4",
"supportDimensions": ["2*4"],
"isDefault": true
}
]
}
关键说明
- 优先级：多时间点配置（
multiScheduledUpdateTime）优先级高于单时间点（scheduledUpdateTime），两者同时配置时仅多时间点生效； - 时间格式：采用 24 小时制，精确到分钟（如
08:00、16:30），多时间点用英文逗号分隔； - 触发逻辑：系统在指定时间点回调
onUpdateForm方法，数据更新逻辑与定时刷新一致。
3.3 下次刷新：自定义延迟更新
通过formProvider.setFormNextRefreshTime接口设置下次刷新时间，适用于 “延迟更新” 场景（如用户操作后 5 分钟刷新），最短间隔为 5 分钟。
代码示例
export default class EntryFormAbility extends FormExtensionAbility {
onFormEvent(formId: string, message: string): void {
const params = JSON.parse(message);
if (params.action === "setNextRefresh") {
// 设置5分钟后刷新（参数单位：分钟）
const delayMinutes = 5;
formProvider.setFormNextRefreshTime(formId, delayMinutes, (err: BusinessError) => {
if (err) {
hilog.error(DOMAIN_NUMBER, TAG, `设置下次刷新失败：${err.message}`);
return;
}
hilog.info(DOMAIN_NUMBER, TAG, `已设置5分钟后刷新`);
});
}
}
// 下次刷新时间到后，触发onUpdateForm
async onUpdateForm(formId: string): void {
hilog.info(DOMAIN_NUMBER, TAG, `[onUpdateForm] 下次刷新触发`);
// 执行数据更新逻辑...
}
}
四、特殊场景刷新：图片与状态关联
除基础文本数据刷新外，卡片常见的复杂场景包括 “图片刷新”（本地 / 网络图片）和 “状态关联刷新”（根据卡片配置刷新不同内容），需针对性处理。
4.1 图片刷新：本地与网络图片更新
卡片展示图片需通过formImages字段传递文件描述符（fd），页面通过memory://fileName协议加载，支持本地图片和网络图片两种场景。
4.1.1 本地图片刷新（卡片创建时加载）
// EntryFormAbility.ets：onAddForm中加载本地图片
import { fileIo } from '@kit.CoreFileKit';
import { Want, BusinessError } from '@kit.AbilityKit';
export default class EntryFormAbility extends FormExtensionAbility {
onAddForm(want: Want): formBindingData.FormBindingData {
// 获取应用临时目录（存放本地图片）
const tempDir = this.context.getApplicationContext().tempDir;
const imgMap: Record<string, number> = {};
try {
// 打开本地图片（假设tempDir下有head.png）
const file = fileIo.openSync(`${tempDir}/head.png`);
imgMap['avatar'] = file.fd; // fd为文件描述符，作为图片标识
} catch (e) {
const err = e as BusinessError;
hilog.error(DOMAIN_NUMBER, TAG, `打开本地图片失败：${err.message}`);
}
// 封装图片数据（formImages为固定字段，不可改名）
class FormData {
text: string = "我的头像";
imgName: string = "avatar"; // 与formImages的key一致
formImages: Record<string, number> = imgMap; // 存储fd
}
return formBindingData.createFormBindingData(new FormData());
}
}
// 卡片页面（WidgetCard.ets）：加载本地图片
let storage = new LocalStorage();
@Entry(storage)
@Component
struct LocalImageCard {
@LocalStorageProp('text') text: string = "加载中...";
@LocalStorageProp('imgName') imgName: string = "";
build() {
Column()
.width('100%')
.height('100%')
.justifyContent(FlexAlign.Center) {
// 通过memory://协议加载图片（imgName对应formImages的key）
Image(`memory://${this.imgName}`)
.width(100)
.height(100)
.borderRadius(50)
.objectFit(ImageFit.Cover)
Text(this.text)
.margin({ top: 10 })
.fontSize(14)
}
}
}
4.1.2 网络图片刷新（用户点击触发）
网络图片需先下载到本地临时目录，再通过 fd 传递，需申请ohos.permission.INTERNET权限。
// 1. 配置权限（module.json5）
{
"module": {
"requestPermissions": [
{
"name": "ohos.permission.INTERNET",
"reason": "用于下载网络图片",
"usedScene": { "abilities": ["EntryFormAbility"], "when": "always" }
}
]
}
}
// 2. EntryFormAbility.ets：onFormEvent中下载并刷新图片
import { http } from '@kit.NetworkKit';
export default class EntryFormAbility extends FormExtensionAbility {
async onFormEvent(formId: string, message: string): Promise<void> {
// 先更新状态为“刷新中”
let loadingData = { text: "刷新中..." };
await formProvider.updateForm(formId, formBindingData.createFormBindingData(loadingData));
// 网络图片地址（替换为真实链接）
const imgUrl = "https://example.com/new-avatar.jpg";
const tempDir = this.context.getApplicationContext().tempDir;
const fileName = `img_${Date.now()}`; // 文件名唯一（确保图片刷新）
const tempFile = `${tempDir}/${fileName}`;
const imgMap: Record<string, number> = {};
try {
// 1. 下载网络图片
const httpRequest = http.createHttp();
const response = await httpRequest.request(imgUrl);
if (response.responseCode !== http.ResponseCode.OK) {
throw new Error(`下载失败：${response.responseCode}`);
}
// 2. 写入临时文件
const imgFile = fileIo.openSync(tempFile, fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE);
await fileIo.write(imgFile.fd, response.result as ArrayBuffer);
imgMap[fileName] = imgFile.fd;
// 3. 刷新卡片图片
const formData = {
text: "刷新成功",
imgName: fileName,
formImages: imgMap
};
await formProvider.updateForm(formId, formBindingData.createFormBindingData(formData));
// 4. 关闭文件（需在刷新后执行）
fileIo.closeSync(imgFile);
httpRequest.destroy();
} catch (error) {
const err = error as BusinessError;
hilog.error(DOMAIN_NUMBER, TAG, `网络图片刷新失败：${err.message}`);
// 刷新失败状态
const failData = { text: "刷新失败" };
await formProvider.updateForm(formId, formBindingData.createFormBindingData(failData));
}
}
}
图片刷新关键约束
- 图片大小限制：展示的图片需控制在 2MB 以内，避免占用过多内存；
- 文件名唯一性：每次刷新需使用不同的
imgName（如加时间戳），否则卡片不会感知图片变化； - 下载超时限制：
FormExtensionAbility后台仅存活 5 秒，需确保网络图片快速下载完成。
4.2 状态关联刷新：根据卡片配置更新内容
同一卡片可能存在多种状态（如两张天气卡片分别显示北京、上海天气），需通过持久化存储记录卡片状态，刷新时根据状态返回对应内容。
完整实现示例
// 1. form_config.json：配置定时刷新（每30分钟）
{
"forms": [
{
"name": "CityWeatherWidget",
"src": "./ets/widget/pages/WeatherCard.ets",
"uiSyntax": "arkts",
"updateEnabled": true,
"updateDuration": 1, // 30分钟刷新一次
"defaultDimension": "2*2",
"supportDimensions": ["2*2"],
"isDefault": true
}
]
}
// 2. 卡片页面（WeatherCard.ets）：选择城市状态
let storage = new LocalStorage();
@Entry(storage)
@Component
struct CityWeatherCard {
@LocalStorageProp('beijingWeather') beijingWeather: string = "待刷新";
@LocalStorageProp('shanghaiWeather') shanghaiWeather: string = "待刷新";
@State selectBeijing: boolean = false;
@State selectShanghai: boolean = false;
build() {
Column({ space: 15 })
.width('100%')
.height('100%')
.padding(15) {
// 城市选择复选框
Row({ space: 8 }) {
Checkbox({ name: 'bj', group: 'cityGroup' })
.onChange((value) => {
this.selectBeijing = value;
// 通知FormExtensionAbility更新状态
this.notifyStateChange();
});
Text("北京")
.fontSize(14);
}
Row({ space: 8 }) {
Checkbox({ name: 'sh', group: 'cityGroup' })
.onChange((value) => {
this.selectShanghai = value;
this.notifyStateChange();
});
Text("上海")
.fontSize(14);
}
// 天气展示
Text(`北京天气：${this.beijingWeather}`)
.fontSize(14)
.margin({ top: 10 });
Text(`上海天气：${this.shanghaiWeather}`)
.fontSize(14);
}
}
// 发送状态变更事件
private notifyStateChange() {
postCardAction(this, {
action: "message",
params: {
selectBeijing: JSON.stringify(this.selectBeijing),
selectShanghai: JSON.stringify(this.selectShanghai)
}
});
}
}
// 3. EntryFormAbility.ets：持久化状态并刷新对应内容
import { preferences } from '@kit.ArkData';
export default class EntryFormAbility extends FormExtensionAbility {
// 卡片创建时初始化状态（存入preferences数据库）
async onAddForm(want: Want): formBindingData.FormBindingData {
const formId = want.parameters?.[formInfo.FormParam.IDENTITY_KEY] as string;
const isTempCard = want.parameters?.[formInfo.FormParam.TEMPORARY_KEY] as boolean;
// 仅常态卡片持久化状态
if (!isTempCard) {
const store = await preferences.getPreferences(this.context, 'cityWeatherStore');
await store.put(`bj_${formId}`, 'false'); // 北京状态：未选中
await store.put(`sh_${formId}`, 'false'); // 上海状态：未选中
await store.flush();
}
return formBindingData.createFormBindingData({});
}
// 接收状态变更事件，更新数据库
async onFormEvent(formId: string, message: string): Promise<void> {
const params = JSON.parse(message);
const store = await preferences.getPreferences(this.context, 'cityWeatherStore');
if (params.selectBeijing !== undefined) {
await store.put(`bj_${formId}`, params.selectBeijing);
}
if (params.selectShanghai !== undefined) {
await store.put(`sh_${formId}`, params.selectShanghai);
}
await store.flush();
}
// 定时刷新时，根据状态返回对应天气数据
async onUpdateForm(formId: string): void {
const store = await preferences.getPreferences(this.context, 'cityWeatherStore');
const selectBeijing = await store.get(`bj_${formId}`, 'false');
const selectShanghai = await store.get(`sh_${formId}`, 'false');
const updateData: Record<string, string> = {};
// 模拟获取天气数据
if (selectBeijing === 'true') {
updateData.beijingWeather = `25℃ 晴（${new Date().toLocaleTimeString()}）`;
}
if (selectShanghai === 'true') {
updateData.shanghaiWeather = `28℃ 多云（${new Date().toLocaleTimeString()}）`;
}
await formProvider.updateForm(formId, formBindingData.createFormBindingData(updateData));
}
// 卡片删除时，清理数据库数据
async onRemoveForm(formId: string): void {
const store = await preferences.getPreferences(this.context, 'cityWeatherStore');
await store.delete(`bj_${formId}`);
await store.delete(`sh_${formId}`);
}
}
五、刷新机制核心约束与最佳实践
5.1 关键约束（避坑重点）
- 刷新次数限制：定时刷新每天最多 50 次，超出后当天无法触发；
-
进程存活限制：
FormExtensionAbility后台仅存活 5 秒（触发回调后），耗时操作（如下载大文件）需拉起主应用处理； -
权限限制：网络图片刷新需申请
INTERNET权限，本地文件操作需确保路径合法； - 资源限制：图片大小≤2MB，自定义字体总大小≤20MB，避免内存溢出。
5.2 最佳实践
- 选择合适的刷新方式：
- 实时交互场景（如点击刷新）→ 主动刷新；
- 周期性数据（如天气、新闻）→ 被动刷新（定时 / 定点）；
- 优化刷新性能：
- 减少刷新频率，非必要不使用高频定时刷新；
- 刷新数据仅传递变更部分，避免全量更新；
- 异常处理兜底：
- 网络请求失败时，保留上次有效数据；
- 图片加载失败时，显示默认占位图；
- 清理冗余数据：卡片删除时，同步清理数据库、临时文件等，避免存储冗余。
总结
ArkTS 卡片的刷新机制围绕 “主动按需” 和 “被动自动” 两大核心，覆盖了文本、图片、状态关联等各类场景。开发时需重点关注formId唯一性、数据传递格式、系统约束（次数、内存、进程存活），并根据业务场景选择合适的刷新方式。通过本文的代码示例和约束说明，可快速落地稳定、高效的卡片刷新功能，提升用户体验。
