卡片开发说明

场景介绍

卡片提供方控制卡片实际显示的内容、控件布局以及控件点击事件。开发者可以通过集成以下接口来提供卡片服务。

HarmonyOS中的服务卡片为卡片提供方开发者提供以下接口能力。

类名	接口名	描述
Ability	ProviderFormInfo onCreateForm(Intent intent)	卡片提供方接收创建卡片通知接口。
void onUpdateForm(long formId)	卡片提供方接收更新卡片通知接口。
void onDeleteForm(long formId)	卡片提供方接收删除卡片通知接口。
void onTriggerFormEvent(long formId, String message)	卡片提供方处理卡片事件接口（JS卡片使用）。
boolean updateForm(long formId, ComponentProvider component)	卡片提供方主动更新卡片（Java卡片使用）。
boolean updateForm(long formId, FormBindingData formBindingData)	卡片提供方主动更新卡片（JS卡片使用），仅更新formBindingData中携带的信息，卡片中其余信息保持不变。
void onCastTempForm(long formId)	卡片提供方接收临时卡片转常态卡片通知。
void onEventNotify(Map formEvents)	卡片提供方接收到事件通知，其中Ability.FORM_VISIBLE表示卡片可见通知，Ability.FORM_INVISIBLE表示卡片不可见通知。
ProviderFormInfo	ProviderFormInfo(int resId, Context context)	Java卡片返回对象构造函数。
ProviderFormInfo()	JS卡片返回对象构造函数。
void mergeActions(ComponentProvider componentProviderActions)	在提供方侧调用该接口，将开发者在ComponentProvider中设置的actions配置数据合并到当前对象中。
void setJsBindingData(FormBindingData data)	设置JS卡片的内容信息(JS卡片使用)。

其中，onEventNotify仅系统应用才会回调，其他接口回调时机如下图：

说明

卡片管理服务不负责保持卡片的活跃状态（设置了定时更新的除外），当使用方作出相应的请求时，管理服务会拉起提供方并回调相应接口。

Java/JS卡片场景能力差异如下表所示：

场景	Java卡片	JS卡片	支持的版本
实时刷新（类似时钟）	Java使用ComponentProvider做实时刷新代价比较大	JS可以做到端侧刷新，但是需要定制化组件	HarmonyOS 2.0及以上
开发方式	Java UI在卡片提供方需要同时对数据和组件进行处理，生成ComponentProvider远端渲染	JS卡片在使用方加载渲染，提供方只要处理数据、组件和逻辑分离	HarmonyOS 2.0及以上
组件支持	Text、Image、DirectionalLayout、PositionLayout、DependentLayout	div、list、list-item、swiper、stack、image、text、span、progress、button（定制：chart 、clock、calendar）	HarmonyOS 2.0及以上
卡片内动效	不支持	暂不开放	HarmonyOS 2.0及以上
阴影模糊	不支持	支持	HarmonyOS 2.0及以上
动态适应布局	不支持	支持	HarmonyOS 2.0及以上
自定义卡片跳转页面	不支持	支持	HarmonyOS 2.0及以上

综上所述，JS卡片比JAVA卡片支持的控件和能力都更丰富：

Java卡片：适合作为一个直达入口，没有复杂的页面和事件。

JS卡片：适合有复杂界面的卡片。

对于同一个Page ability，在config.json中最多支持配置16张卡片。