ArkTS卡片页面刷新概述
=============

卡片使用方（例如：桌面）和卡片提供方均可主动触发卡片页面刷新。此外，卡片管理服务会根据开发者声明的定时信息，按需通知卡片提供方进行卡片刷新。因此，卡片刷新方式包括：卡片提供方主动触发刷新、卡片使用方主动触发刷新以及卡片定时定点刷新。这些刷新方式均需由卡片提供方推送需要刷新的卡片数据。

#### 卡片数据交互

ArkTS卡片管理服务支持卡片提供方（例如：应用）和卡片之间的数据交互。卡片通过[postCardAction](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-postcardaction#postcardaction-1)传递数据给卡片提供方，卡片提供方则通过[updateForm](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-app-form-formprovider#formproviderupdateform)接口传递数据给卡片。卡片提供方将数据提供给卡片后，可以用于卡片页面刷新等。

由于卡片提供方和卡片为相互独立的进程，两者间的数据共享只能通过[LocalStorageProp](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-localstorage#localstorageprop)传递，不能使用getContext方法。因此卡片提供方推送数据后，卡片UI需要通过LocalStorageProp接收数据，且接收数据时，卡片数据会被转换成string类型。

#### 页面刷新分类

根据触发方式的差异，卡片刷新分为主动刷新和被动刷新。

#### \[h2\]主动刷新

主动刷新包括卡片提供方主动刷新卡片和卡片使用方主动刷新卡片。开发指导请参考[ArkTS卡片主动刷新](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-ui-widget-active-refresh)。

**图1 卡片提供方主动刷新卡片流程图**

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/94/v3/0Pdxqjk2Sm6Oqp-_V1ckNg/zh-cn_image_0000002594668512.png?HW-CC-KV=V1&HW-CC-Date=20260612T073341Z&HW-CC-Expire=86400&HW-CC-Sign=20CC38D3B0CD243E7AB0C82818C7D4D46781033A590EEDE15BAB1103C50B658D)

卡片提供方应用运行过程中，如果识别到有要更新卡片数据的诉求，可以主动通过formProvider提供的[updateForm](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-app-form-formprovider#formproviderupdateform)接口更新卡片。

**图2 卡片使用方主动刷新卡片流程图**

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/d6/v3/Japz4KC4Q1iyavz2DQ45uw/zh-cn_image_0000002594828440.png?HW-CC-KV=V1&HW-CC-Date=20260612T073341Z&HW-CC-Expire=86400&HW-CC-Sign=339AEB2BF2C5576E8D6DAD0E6FE979EB047B97C4CDB240D1F78EFEFEFA7718E1)

当卡片使用方检测到系统语言或主题模式（如深浅色）发生变化时，可以主动通过formHost提供的requestForm（仅支持系统应用使用）接口请求更新卡片，卡片管理服务会进而通知卡片提供方完成卡片更新。

#### \[h2\]被动刷新

被动刷新包括定时刷新、定点刷新。开发指导请参考[ArkTS卡片被动刷新](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-ui-widget-passive-refresh)。

卡片定时刷新：表示在一定时间间隔内调用[onUpdateForm](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-app-form-formextensionability#formextensionabilityonupdateform)的生命周期回调函数自动刷新卡片内容。

卡片定点刷新：表示在每天的某个特定时间点自动刷新卡片内容。

**图3 卡片管理服务通知卡片提供方定时定点刷新卡片流程图**

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/7d/v3/6sTOg3XsRYOgS27YGTYJqQ/zh-cn_image_0000002625187887.png?HW-CC-KV=V1&HW-CC-Date=20260612T073341Z&HW-CC-Expire=86400&HW-CC-Sign=052713868376295C26BCC09E39D06FD819D75604711C466A56F98EB19B308CB9)

根据卡片提供方开发者提前配置声明的定时刷新信息，卡片管理服务会根据定时信息、卡片可见状态、刷新次数等因素综合判断是否需要通知卡片提供方更新卡片。

#### 约束与限制

1.  卡片提供方仅允许刷新自己的卡片，其他提供方的卡片无法刷新。
2.  卡片使用方仅允许刷新添加到自己的卡片，添加到其他使用方的卡片无法刷新。
3.  从API version 20开始，如果卡片刷新的数据通过共享内存更新，刷新数据总大小不超过10MB，刷新图片数量不超过20张。API version 19及之前的版本，图片文件数量上限为5张，每张限制内存2MB，超出限制的图片会显示异常。