HarmonyOS Next开发学习手册——服务卡片开发指南（FA模型）

卡片概述

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

卡片常用于嵌入到其他应用（当前只支持系统应用）中作为其界面的一部分显示，并支持拉起页面、发送消息等基础的交互功能。

卡片的基本概念：

卡片使用方：显示卡片内容的宿主应用，控制卡片在宿主中展示的位置。
卡片管理服务：用于管理系统中所添加卡片的常驻代理服务，包括卡片对象的管理与使用，以及卡片周期性刷新等。
卡片提供方：提供卡片显示内容元服务，控制卡片的显示内容、控件布局以及控件点击事件。

运作机制

卡片框架的运作机制如图1所示。

图1 卡片框架运作机制（FA模型）

卡片使用方包含以下模块：

卡片使用：包含卡片的创建、删除、请求更新等操作。
通信适配层：由HarmonyOS SDK提供，负责与卡片管理服务通信，用于将卡片的相关操作到卡片管理服务。

卡片管理服务包含以下模块：

周期性刷新：在卡片添加后，根据卡片的刷新策略启动定时任务周期性触发卡片的刷新。
卡片缓存管理：在卡片添加到卡片管理服务后，对卡片的视图信息进行缓存，以便下次获取卡片时可以直接返回缓存数据，降低时延。
卡片生命周期管理：对于卡片切换到后台或者被遮挡时，暂停卡片的刷新；以及卡片的升级/卸载场景下对卡片数据的更新和清理。
卡片使用方对象管理：对卡片使用方的RPC对象进行管理，用于使用方请求进行校验以及对卡片更新后的回调处理。
通信适配层：负责与卡片使用方和提供方进行RPC通信。

卡片提供方包含以下模块：

卡片服务：由卡片提供方开发者实现，开发者实现生命周期处理创建卡片、更新卡片以及删除卡片等请求，提供相应的卡片服务。
卡片提供方实例管理模块：由卡片提供方开发者实现，负责对卡片管理服务分配的卡片实例进行持久化管理。
通信适配层：由HarmonyOS SDK提供，负责与卡片管理服务通信，用于将卡片的更新数据主动推送到卡片管理服务。

说明

实际开发时只需要作为卡片提供方进行卡片内容的开发，卡片使用方和卡片管理服务由系统自动处理。

接口说明

FormAbility生命周期接口如下：

接口名	描述
onCreate(want: Want): formBindingData.FormBindingData	卡片提供方接收创建卡片的通知接口。
onCastToNormal(formId: string): void	卡片提供方接收临时卡片转常态卡片的通知接口
onUpdate(formId: string): void	卡片提供方接收更新卡片的通知接口。
onVisibilityChange(newStatus: Record<string, number>): void	卡片提供方接收修改可见性的通知接口。
onEvent(formId: string, message: string): void	卡片提供方接收处理卡片事件的通知接口。
onDestroy(formId: string): void	卡片提供方接收销毁卡片的通知接口。
onAcquireFormState?(want: Want): formInfo.FormState	卡片提供方接收查询卡片状态的通知接口。
onShare?(formId: string): {[key: string]: any}	卡片提供方接收卡片分享的通知接口。
onShareForm?(formId: string): Record<string, Object>	卡片提供方接收卡片分享的通知接口。推荐使用该接口替代onShare接口。如果了实现该接口，onShare将不再被回调。

FormProvider类有如下API接口，具体的API介绍详见接口文档。

接口名	描述
setFormNextRefreshTime(formId: string, minute: number, callback: AsyncCallback): void;	设置指定卡片的下一次更新时间。
setFormNextRefreshTime(formId: string, minute: number): Promise;	设置指定卡片的下一次更新时间，以promise方式返回。
updateForm(formId: string, formBindingData: FormBindingData, callback: AsyncCallback): void;	更新指定的卡片。
updateForm(formId: string, formBindingData: FormBindingData): Promise;	更新指定的卡片，以promise方式返回。

formBindingData类有如下API接口，具体的API介绍详见接口文档。

接口名	描述
createFormBindingData(obj?: Object	string): FormBindingData

开发步骤

FA卡片开发，即基于 FA模型的卡片提供方开发，主要涉及如下关键步骤：

实现卡片生命周期接口：开发FormAbility生命周期回调函数。
配置卡片配置文件：配置应用配置文件config.json。
卡片信息的持久化：对卡片信息进行持久化管理。
卡片数据交互：通过updateForm()更新卡片显示的信息。
开发卡片页面：使用HML+CSS+JSON开发JS卡片页面。
开发卡片事件：为卡片添加router事件和message事件。

实现卡片生命周期接口

创建FA模型的卡片，需实现卡片的生命周期接口。先参考IDE开发服务卡片指南生成服务卡片模板。

在form.ts中，导入相关模块

import type featureAbility from '@ohos.ability.featureAbility';
import type Want from '@ohos.app.ability.Want';
import formBindingData from '@ohos.app.form.formBindingData';
import formInfo from '@ohos.app.form.formInfo';
import formProvider from '@ohos.app.form.formProvider';
import dataPreferences from '@ohos.data.preferences';
import hilog from '@ohos.hilog';

在form.ts中，实现卡片生命周期接口

const TAG: string = '[Sample_FAModelAbilityDevelop]';
const domain: number = 0xFF00;

const DATA_STORAGE_PATH: string = 'form_store';
let storeFormInfo = async (formId: string, formName: string, tempFlag: boolean, context: featureAbility.Context): Promise<void> => {
  // 此处仅对卡片ID：formId，卡片名：formName和是否为临时卡片：tempFlag进行了持久化
  let formInfo: Record<string, string | number | boolean> = {
    'formName': 'formName',
    'tempFlag': 'tempFlag',
    'updateCount': 0
  };
  try {
    const storage = await dataPreferences.getPreferences(context, DATA_STORAGE_PATH);
    // put form info
    await storage.put(formId, JSON.stringify(formInfo));
    hilog.info(domain, TAG, `storeFormInfo, put form info successfully, formId: ${formId}`);
    await storage.flush();
  } catch (err) {
    hilog.error(domain, TAG, `failed to storeFormInfo, err: ${JSON.stringify(err as Error)}`);
  }
};

let deleteFormInfo = async (formId: string, context: featureAbility.Context) => {
  try {
    const storage = await dataPreferences.ge