Form Kit（卡片开发服务）学习笔记01-核心概念与架构设计

在HarmonyOS应用中实现桌面小组件（服务卡片）需要调用Form Kit。卡片能够将应用关键信息直接展示在桌面，用户无需打开应用即可完成操作。开发时首先需要理解Form Kit的核心概念和架构设计。

核心概念

服务卡片由卡片提供方（通常是Ability）和卡片使用方（桌面、负一屏等）协同工作。卡片生命周期由系统管理，开发者需实现以下回调方法：

回调方法	触发时机
`onAddForm(want)`	用户添加卡片到桌面时
`onUpdateForm(formId)`	系统触发定时更新或主动更新时
`onRemoveForm(formId)`	卡片从桌面移除时
`onCastToNormalForm(formId)`	卡片从临时态转为常态时（仅临时卡片触发）
`onEvent(formId, message)`	卡片内部通过postCardAction发送事件时

注意：onUpdateForm的调用间隔由updateDuration字段控制，最小间隔为30分钟。若设置过短，系统可能不会按预期频繁更新。建议根据业务实际需求设置更新周期，避免无效刷新导致功耗问题。

卡片支持三种开发类型：ArkTS卡片、JS卡片、Napi卡片。ArkTS卡片基于ArkTS声明式UI开发，性能和开发体验最佳；JS卡片使用JavaScript/FA模型，适合存量JS应用迁移；Napi卡片用于C++场景。当前官方推荐首选ArkTS卡片。

环境准备

开发ArkTS卡片需要以下环境配置：

DevEco Studio 4.0及以上版本（Form Kit从API 12开始支持元服务，建议使用对应SDK版本）。
新建工程时，在"Project Template"中选择"Service Widget"模板，或手动在已有工程中添加卡片Ability。

手动添加步骤：

在模块的module.json5中声明卡片Ability，并配置extensionAbilities数组：

json 复制代码

{
  "module": {
    "extensionAbilities": [
      {
        "name": "EntryFormAbility",
        "srcEntry": "./ets/entryformability/EntryFormAbility.ets",
        "type": "form",
        "description": "$string:EntryFormAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryFormAbility_label",
        "exported": true,
        "metadata": [
          {
            "name": "ohos.extension.form",
            "resource": "$profile:form_config"
          }
        ]
      }
    ]
  }
}

配置form_config.json文件如果没有见创建一个内容：

typescript 复制代码

{
  "forms": [
    {
      "name": "widget",
      "displayName": "$string:widget_name",
      "description": "$string:widget_desc",
      "src": "./ets/widget/pages/WidgetCard.ets",
      "uiSyntax": "arkts",
      "window": {
        "designWidth": 720,
        "autoDesignWidth": true
      },
      "isDefault": true,
      "updateEnabled": true,
      "updateDuration": 60,
      "defaultDimension": "1*2",
      "supportDimensions": ["1*2", "2*2"]
    }
  ]
}

创建Ability文件（如EntryFormAbility.ts），继承自FormExtensionAbility，实现对应生命周期回调。

提示：src路径下的Widget页面文件必须导出build函数，且只能使用ArkTS声明式UI的部分组件（如Column、Text、Image），不支持if/else等逻辑控制。另外，supportDimensions中定义的大小的宽高比必须符合系统规范（如12、24等），否则添加卡片时会失败。

注意事项

服务卡片接口标记"元服务API"：从API version 12开始，该接口支持在元服务中使用。如果接口不支持在元服务中使用，文档中不做特殊说明。
支持在ArkTS卡片UI界面中使用的接口，会额外添加"卡片能力"标记。例如ohos.ohos.abilityAccessCtrl中的部分接口有该标记。在卡片中使用全局context需注意，卡片UI中没有getContext()方法，应通过formBindingContext获取。
卡片的数据更新建议通过postCardAction或updateForm实现，避免在卡片内直接发起网络请求（受限于卡片运行环境）。
卡片的刷新频率受到系统限制：即使updateDuration设置为1分钟，系统实际也可能按10分钟一次进行刷新。如需更实时的数据展示，可结合postCardAction向后台Ability发送事件，由Ability主动更新卡片。

结尾

下一篇将介绍ArkTS卡片的完整开发流程和生命周期回调的具体实现，包括如何传递数据、处理用户交互事件。你在开发服务卡片时遇到过哪些棘手的问题？欢迎评论交流。