目录

卡片的生命周期回调函数有哪些

问题现象

卡片的生命周期包含哪些回调函数。

背景知识

FormExtensionAbility卡片扩展模块，提供卡片创建、销毁、刷新等生命周期回调。

解决方案

回调函数

函数介绍

触发时机

使用限制

onAddForm

卡片提供方接收创建卡片的通知接口。
  1. 拉起卡片管理页面预览卡片时。
  2. 从卡片管理页面将卡片添加至桌面时。
  3. 长按桌面卡片，将卡片移动并落至其他屏时。
  4. 使用FormMenu将卡片添加至桌面时。
  5. 长按桌面卡片，拖动卡片调整大小时。
  1. 回调函数需返回卡片数据绑定类。
  2. 拉起卡片管理页面预览卡片时，仅触发当前预览卡片与前后两个卡片的onAddForm函数；通过左右滑动，可继续触发后续卡片的onAddForm函数。
  3. 若卡片需要调整尺寸大小，应在卡片配置文件form_config.json中，将resizable设置为true。

onCastToNormalForm

卡片提供方收到卡片使用方将临时卡片转常态卡片的通知接口。

卡片提供方收到卡片使用方将临时卡片转常态卡片的通知时。

当前卡片使用方不会使用临时卡片，不涉及该回调函数。

onUpdateForm

卡片提供方接收携带参数的更新卡片的通知接口。
  1. 将卡片添加至桌面时。
  2. 长按桌面卡片，将卡片移动并落至其他屏时。
  3. 桌面卡片设置为被动刷新时。
  4. 卡片页面组件使用reloadForms和reloadAllForms接口请求刷新卡片内容时，参考卡片提供方批量请求刷新卡片内容。
  5. 长按桌面卡片，拖动卡片调整大小时。
  1. 若支持卡片定时更新/卡片定点更新/卡片使用方主动请求更新功能，则提供方需要重写该方法以支持数据更新。
  2. 卡片定时更新需在卡片配置文件form_config.json中，设置updateEnabled为true，且updateDuration设置为大于0的整数值。
  3. 卡片定点更新需在卡片配置文件form_config.json中，scheduledUpdateTime或multiScheduledUpdateTime设置需刷新的24小时制时刻。
  4. 同时配置了定时刷新updateDuration和定点刷新scheduledUpdateTime时，定时刷新的优先级更高且定点刷新不会执行。如果想要配置定点刷新，则需要将updateDuration配置为0。
  5. 若卡片需要调整尺寸大小，应在卡片配置文件form_config.json中，将resizable设置为true。

onChangeFormVisibility

卡片提供方接收修改可见性的通知接口。

卡片可见性发生变更时。

仅对系统应用生效，且需要将formVisibleNotify配置为true。

onFormEvent

卡片提供方接收处理卡片事件的通知接口。

卡片页面组件使用postCardAction接口且action类型为message时，参考卡片提供方主动刷新卡片内容。

无。

onRemoveForm

卡片提供方接收销毁卡片的通知接口。
  1. 卡片管理页面退出时。
  2. 卡片从桌面上移除时。
  3. 长按桌面卡片，拖动卡片调整大小时。

若卡片需要调整尺寸大小，应在卡片配置文件form_config.json中，将resizable设置为true。

onConfigurationUpdate

卡片配置发生变更的通知接口。

当系统环境发生变更时（例如深色模式开关时）。

仅当FormExtensionAbility存活时才会触发onConfigurationUpdate回调，FormExtensionAbility创建后10秒内无操作将会被清理，此时无法触发。

onStop

卡片提供方的卡片进程退出的通知接口。

卡片提供方的卡片进程退出时。

FormExtensionAbility创建后10秒内无操作将会被清理，卡片进程退出，此时会触发onStop回调。

onFormLocationChanged

卡片提供方接收卡片位置变更的通知接口。

卡片添加至桌面时。

无。

典型场景介绍：

总结

卡片扩展模块FormExtensionAbility提供了包含卡片创建、销毁、刷新等生命周期，应用可以在不同的业务场景，根据触发时机需要在对应函数中执行操作。