【鸿蒙南向开发】OpenHarmony——FormManager模块源代码分析

卡片服务简介

服务卡片（以下简称“卡片”）是FA的一种界面展示形式，将FA的重要信息或操作前置到卡片，以达到服务直达，减少体验层级的目的。

基本概念

卡片提供方

服务卡片（以下简称“卡片”）是FA的一种界面展示形式，将FA的重要信息或操作前置到卡片，以达到服务直达，减少体验层级的目的。

卡片提供方是覆写了卡片相关回调函数的FormAbility。

卡片使用方

显示卡片内容的宿主应用，控制卡片在宿主中展示的位置。主要为用户开发的js,hml等前台界面。

卡片管理服务

用于管理系统中所添加卡片的常驻代理服务，包括卡片对象的管理与使用，以及卡片周期性刷新等。

说明：卡片使用方和提供方不要求常驻运行，在需要添加/删除/请求更新卡片时，卡片管理服务会拉起卡片提供方获取卡片信息

运作机制

NAPI接口

Class	API	描述
formBindingData	createFormBindingData	创建一个FormBindingData对象。
FormExtension（Stage模型用）	onCreate	卡片提供方接收创建卡片的通知接口。
	onCastToNormal	卡片提供方接收临时卡片转常态卡片的通知接口。
	onUpdate	卡片提供方接收更新卡片的通知接口。获取最新数据后调用FormExtensionContext的updateForm接口刷新卡片数据。
	onVisibilityChange	卡片提供方接收修改可见性的通知接口。
	onEvent	卡片提供方接收处理卡片事件的通知接口。
	onDestroy	卡片提供方接收销毁卡片的通知接口。
LifecycleForm（FA模型用）	onCreate	卡片提供方接收创建卡片的通知接口。
	onCastToNormal	卡片提供方接收临时卡片转常态卡片的通知接口。
	onUpdate	卡片提供方接收更新卡片的通知接口。
	onVisibilityChange	卡片提供方接收修改可见性的通知接口。
	onEvent	卡片提供方接收处理卡片事件的通知接口。
	onDestroy	卡片提供方接收销毁卡片的通知接口。
	onAcquireFormState	卡片提供方接收查询卡片状态的通知接口。
FormHost	deleteForm	删除指定的卡片。调用此方法后，应用程序将无法使用该卡片，卡片管理器服务不再保留有关该卡片的信息。
	releaseForm	释放指定的卡片。调用此方法后，应用程序将无法使用该卡片，但卡片管理器服务仍然保留有关该卡片的缓存信息和存储信息。
	requestForm	请求卡片更新。
	castTempForm	将指定的临时卡片转换为普通卡片。
	notifyVisibleForms	向卡片框架发送通知以使指定的卡片可见。该方法调用成功后，会调用onVisibilityChange通知卡片提供方。
	notifyInvisibleForms	向卡片框架发送通知以使指定的卡片不可见。该方法调用成功后，会调用onVisibilityChange通知卡片提供方
	enableFormsUpdate	向卡片框架发送通知以使指定的卡片可以更新。该方法调用成功后，卡片刷新状态设置为使能，卡片可以接收来自卡片提供方的更新。
	disableFormsUpdate	向卡片框架发送通知以使指定的卡片不可以更新。该方法调用成功后，卡片刷新状态设置为去使能，卡片不可以接收来自卡片提供方的更新。
	isSystemReady	检查系统是否准备好。
	getAllFormsInfo	获取设备上所有应用提供的卡片信息。
	getFormsInfo	获取设备上指定应用程序提供的卡片信息。
	deleteInvalidForms	根据列表删除应用程序的无效卡片。
	acquireFormState	获取卡片状态
	on(“formUninstall”)	订阅卡片卸载事件。
	off(“formUninstall”)	取消订阅卡片卸载事件。
	notifyFormsVisible	通知卡片是否可见。
	notifyFormsEnableUpdate	通知卡片是否启用更新状态。
FormProvider	setFormNextRefreshTime	设置指定卡片的下一次更新时间。
	updateForm	更新指定的卡片。

接口回调时机如下图

说明：开发者仅需作为卡片提供方进行服务卡片内容的开发，卡片使用方和卡片代理服务由系统自动处理

卡片代理服务类图

关键类:FormMgrService是卡片代理服务的主类。处理来自卡片使用方的请求。

​ FormProviderMgr是卡片提供方的代理服务。负责连接卡片提供方的FormAbility并进行相关的回调。

​ FormMgrAdapter及FormTaskMgr负责代理服务进程内的各任务的处理。

总结：卡片使用方通过IFormMgr调用卡片代理服务(FormMgrService)的接口，代理服务进程内，通过FormMgrAdapter及FormTaskMgr处理来各请求任务，并通过卡片提供方的代理服务(FormProviderMgr)拉起卡片提供方的服务。

源码分析(以删除卡片为例)

1. 卡片使用方调用卡片代理服务的DeleteForm接口

foundation\aafwk\standard\services\formmgr\src\form_mgr_service.cpp

/**
 * @brief Delete forms with formIds, send formIds to form manager service.
 * @param formId The Id of the forms to delete.
 * @param callerToken Caller ability token.
 * @return Returns ERR_OK on success, others on failure.
 */
int FormMgrService::DeleteForm(const int64_t formId, const sptr<IRemoteObject> &callerToken)
{
    ErrCode ret = CheckFormPermission();
    if (ret != ERR_OK) {
        HILOG_ERROR("%{public}s fail, delete form permission denied", __func__);
        return ret;
    }

    return FormMgrAdapter::GetInstance().DeleteForm(formId, callerToken); //调用FormMgrAdapter的DeleteForm方法
}

foundation\aafwk\standard\services\formmgr\src\form_mgr_adapter.cpp

/**
 * @brief Delete forms with formIds, send formIds to form manager service.
 * @param formId The Id of the forms to delete.
 * @param callerToken Caller ability token.
 * @return Returns ERR_OK on success, others on failure.
 */
int FormMgrAdapter::DeleteForm(const int64