HarmonyOS 鸿蒙Next服务卡片开发

FormExtensionAbility 全生命周期，各函数详情如下：

声明周期函数	触发场景	核心功能与使用说明
`onAddForm(want: Want)`	卡片使用方创建卡片时	1. 从`want.parameters[formInfo.FormParam.NAME_KEY]`提取卡片信息； 2. 返回`FormBindingData`（封装卡片初始数据，如标题、详情）。
`onCastToNormalForm(formId: string)`	当前卡片使用方无此场景	无需实现，仅特定场景生效。
`onUpdateForm(formId: string)`	卡片需定时 / 定点更新，或使用方主动请求更新时	1. 构造新的卡片数据（如`{title: "更新后标题", detail: "更新后详情"}`）； 2. 调用`formProvider.updateForm(formId, 新数据)`完成刷新，需捕获`BusinessError`处理异常。
`onChangeFormVisibility(newStatus: Record<string, number>)`	卡片使用方发起 “可见 / 不可见” 通知时	仅系统应用生效，需根据`newStatus`（可见状态映射）做对应逻辑处理。
`onFormEvent(formId: string, message: string)`	卡片触发交互事件（如用户点击）时	需重写实现，处理事件逻辑（如跳转、数据变更），`message`为事件传递的信息。
`onRemoveForm(formId: string)`	卡片被删除时	删除此前持久化的该卡片实例数据（需根据实际业务场景实现，如清理本地缓存）。
`onConfigurationUpdate(config: Configuration)`	FormExtensionAbility 存活时系统配置更新（如屏幕旋转）	接收系统配置变更信息；注意：FormExtensionAbility 创建后 10 秒无操作会被自动清理。
`onAcquireFormState(want: Want)`	接收 “查询卡片状态” 的通知时	默认返回卡片初始状态`formInfo.FormState.READY`（表示卡片可正常使用）。

刷新类型详解如下

刷新类型	包含场景	关键触发逻辑 / 接口
主动刷新	1. 提供方主动刷新 2. 使用方主动刷新	1. 提供方识别数据更新诉求，调用`formProvider`的`updateForm`接口 2. 使用方检测系统变化（如语言、深浅色），系统应用调用`formHost`的`requestForm`接口，由管理服务通知提供方更新
被动刷新	1. 定时刷新 2. 定点刷新	1. 按开发者配置的时间间隔，自动调用`onUpdateForm`生命周期回调刷新 2. 按开发者配置的每日特定时间点刷新 3. 管理服务综合判断：定时信息、卡片可见状态、刷新次数，决定是否通知提供方

权限约束：
- 卡片提供方仅能刷新自己所属的卡片，无法刷新其他提供方的卡片
- 卡片使用方仅能刷新添加到自身的卡片，无法刷新其他使用方的卡片
数据 / 图片限制（按 API 版本）：
- API version 20 及以上：共享内存更新时，数据总大小≤10MB，刷新图片数量≤20 张
- API version 19 及之前：图片数量≤5 张，单张图片内存≤2MB；超出限制会导致图片显示异常

【官方文档——ArkTS卡片生命周期】

【官方文档——ArkTS卡片页面刷新】

更多关于HarmonyOS 鸿蒙Next服务卡片开发的实战系列教程也可以访问 https://www.itying.com/category-93-b0.html

yuanlaile 2楼

HarmonyOS 服务卡片没有类似页面 onPageShow() 的“可见性”生命周期，但官方把“刷新”拆成了两条线：

卡片侧（FormExtensionAbility）

只有 6 个标准回调：

onCreate() - 第一次拖出卡片
onUpdate() - 定时/定点刷新触发
onCastToNormal() - 临时卡转常态卡
onVisibilityChange() - 桌面滑到/滑离当前屏时触发（最接近 onPageShow）
onEvent() - 处理卡片按钮点击、message、call 等事件
onDestroy() - 卡片被移除

其中 onVisibilityChange({ [formId: string]: 0|1 }) 就是“卡片对用户可见/不可见”的钩子，可以在这里重新计算数据并调用 formProvider.updateForm() 刷新界面。

页面侧（UIAbility）

如果你想在“自己的 App 里改完数据后立刻刷新桌面卡片”，官方推荐“页面主动更新”模式：

在 onAddForm() 里把系统分配的 formId 存到本地（Preferences）
编辑页点保存后，取出 formId 列表，循环执行 formProvider.updateForm(formId, formBindingData.createFormBindingData(newData))

即可实现“实时刷新”，不受 30 min 定时限制。

数据刷新指导文档

Stage 模型（API 9+）《Stage 模型服务卡片开发指导》 https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/service-widget-overview-0000001536226057-V3
卡片生命周期与刷新机制 https://developer.harmonyos.com/cn/doc/harmonyos-guides-V5/arkts-ui-widget-lifecycle-V5
定时/定点/代理刷新配置说明 https://developer.harmonyos.com/cn/doc/harmonyos-guides-V5/arkts-ui-widget-update-by-time-V5

phonegap100 3楼

鸿蒙Next服务卡片基于ArkTS语言开发，使用声明式UI范式。服务卡片通过FormExtensionAbility组件实现生命周期管理，支持静态和动态卡片两种类型。开发时需在module.json5中配置卡片尺寸和外观。卡片布局通过ArkUI组件构建，数据更新采用FormProvider接口。卡片能力包括状态持久化、定时刷新和事件交互，可通过formBindingData进行数据绑定。

wuwangju 4楼

在HarmonyOS Next中，服务卡片没有直接的onPageShow()函数，但可以通过以下方式实现数据刷新：

定时刷新：通过setRefreshTime()设置定时刷新策略，系统会在指定时间自动触发卡片更新
手动刷新：用户下拉卡片时触发刷新
事件触发：通过postCardAction()发送事件到FormExtensionAbility，在onFormEvent()中处理数据更新

推荐方案：

对于周期性数据更新，使用定时刷新
对于用户交互触发的更新，使用事件机制
在FormExtensionAbility的onUpdateForm()中实现具体的数据更新逻辑

具体实现可参考官方文档中“服务卡片开发指南”部分，了解FormExtensionAbility的生命周期管理和数据更新机制。