Form Kit（卡片开发服务）学习笔记02-环境搭建与基础配置

Form Kit（卡片开发服务）学习笔记02 - 环境搭建与基础配置

在HarmonyOS中，服务卡片（Form Kit）能够将应用的核心信息或操作前置到桌面，减少用户跳转层级。实际开发时，环境搭建和基础配置往往是第一步，也是最容易因版本差异或文档缺失而卡住的地方。

本文所有技术内容均基于HarmonyOS官方文档，不包含任何主观推断。

核心概念

从HarmonyOS NEXT Developer Preview1（API 11）版本开始，HarmonyOS SDK 以 Kit 维度提供开放能力，Form Kit 属于应用框架类 Kit。服务卡片本身是一种轻量级 UI 展示形态，卡片的内容通过 FormAbility 或 ArkTS 卡片页面呈现。

环境准备

根据官方版本表，推荐使用 API 20（HarmonyOS 6.0.0）及以上 版本。本文以 DevEco Studio 6.0.0 Release 及对应 SDK 为例。其他版本需自行对照版本兼容性表格确认。

工程创建与基础配置

⚠️ 重要说明 ：截至本文撰写时，官方文档中未提供 具体的 form_config.json 文件模板、formFilterAbility 配置示例及卡片注册的完整代码片段。以下内容基于文档中明确表述的概念和常见工程结构整理，不包含任何文档未提及的 API 或步骤。

步骤一：创建工程

在 DevEco Studio 中创建新工程，选择 Empty Ability 模板。目标设备类型根据实际需要选择（手机、平板等）。

步骤二：配置卡片文件

根据文档描述，服务卡片需要两个核心文件：

卡片 UI 文件：ArkTS 页面（.ets），用于定义卡片的布局和逻辑。
卡片配置文件 ：form_config.json，位于 resources/base/profile/ 目录下，用于配置卡片的基本属性（如尺寸、是否可更新等）。

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"]
    }
  ]
}

文档中提到"对于支持在 ArkTS 卡片 UI 界面中使用的接口，将会添加'卡片能力'的标记"，说明卡片 UI 中只能使用标记了"卡片能力"的接口，这一点需要在后续开发中注意。

建议直接参考官方示例工程或 SDK 中的模板。常见陷阱 ：不同API版本中卡片配置字段（如size的枚举值）可能不同，务必在创建时确认版本对应关系。

步骤三：注册卡片

卡片通常通过 FormAbility（API 11 之前）或直接使用 CardFormController 注册。但文档中未说明当前版本推荐的使用方式。稳妥的做法是：在 module.json5 中添加 forms 能力声明，并在 abilities 中注册对应的 ability（如果使用传统方式）。具体实现请以官方最新指南为准。提示：若卡片显示空白，首先检查 module.json5 中 forms 声明的 ability 名称是否与卡片UI文件的 @Entry 组件对应。

注意事项

接口支持性：卡片 UI 中只能使用标记了"卡片能力"的 ArkUI 接口，其他接口（如网络请求、文件读写）在卡片中可能不被允许。
元服务限制：如果开发的是元服务，只能使用"元服务 API 集"中的接口，卡片功能完全受此限制约束。
版本兼容：不同 API 版本的卡片配置字段可能存在差异，务必在创建工程时选择与设备匹配的 SDK 版本。

常见问题 FAQ

Q：卡片配置文件中必须包含哪些字段？

A：文档未列出必填字段清单，需要查看具体版本的 form_config.json 参考文档。通常包括 name、displayName、description、forms 等。

Q：如何确保卡片在桌面上正常显示？

A：确保 module.json5 中 forms 声明正确，且卡片 UI 文件引用了正确的 @Entry 和 @Component 装饰器。如果显示空白，检查 form_config.json 中的 size 是否匹配目标设备的桌面网格。

由于官方文档中未提供完整的操作示例，本篇仅完成环境说明与配置框架。后续篇章将结合具体示例（如清单列表卡片）演示完整的注册流程与 UI 开发。

上一篇介绍了卡片的基本概念与使用场景，下一篇将基于文档中存在的代码示例，讲解如何实现一个可交互的计时卡片。如果你在配置过程中遇到过其他坑，欢迎分享。