本文同步发表于我的微信公众号，微信搜索 程语新视界 即可关注，每个工作日都有文章更新

   鸿蒙应用开发中，ArkTS卡片是一种重要的服务交互形态，允许用户快速访问应用的核心功能。而卡片的配置文件则是定义卡片行为和外观的核心元数据。

卡片配置

卡片五元组：卡片的唯一标识

卡片五元组是确认卡片唯一的要素信息，包括：

五元组	对应配置	说明
bundleName	app.json5 中的 bundleName	应用包名
moduleName	module.json5 中的 name	模块名称
abilityName	abilities 标签中的 name	Ability名称
formName	form_config.json 中的 name	卡片名称
formDimension	form_config.json 中的 supportDimensions	卡片规格

提示：

• 五元组不建议使用资源文件导入配置

• 使用资源文件导入时，资源文件新增字段会导致ID改变，会被认为五元组发生变化

• 如果应用升级后五元组有改变，系统中对应的卡片会被删除，在屏幕上会消失

二、卡片配置文件体系

卡片相关的配置文件主要包括三类：

2.1 FormExtensionAbility配置

在module.json5配置文件中，通过extensionAbilities标签配置FormExtensionAbility相关信息。

配置示例

{
  "module": {
    // ... 其他配置
    "extensionAbilities": [
      {
        "name": "EntryFormAbility",                    // ExtensionAbility名称
        "srcEntry": "./ets/entryformability/EntryFormAbility.ets",  // 入口文件
        "label": "$string:EntryFormAbility_label",     // 显示名称
        "description": "$string:EntryFormAbility_desc", // 描述信息
        "type": "form",                                 // 类型固定为"form"
        "metadata": [
          {
            "name": "ohos.extension.form",              // 固定字符串
            "resource": "$profile:form_config"          // 卡片配置文件的资源索引
          }
        ]
      }
    ],
    // 独立卡片包形态中使用，关联卡片包模块
    "formWidgetModule": "library"
  }
}

字段说明

字段	说明	是否必填
name	ExtensionAbility名称	是
srcEntry	卡片生命周期入口文件路径	是
type	固定为"form"	是
metadata	元信息标签，name固定为"ohos.extension.form"	是
resource	卡片具体配置信息的资源索引	是
formWidgetModule	独立卡片包中关联应用包的module	否

2.2 独立卡片包配置

对于独立卡片包形态，需要在卡片包的module.json5中配置formExtensionModule字段，用于关联应用包的module。

{
  "module": {
    "name": "library",                           // 卡片包模块名称
    "type": "shared",                             // 模块类型
    "description": "$string:shared_desc",         // 描述
    "deviceTypes": ["phone"],                      // 支持的设备类型
    "deliveryWithInstall": true,                   // 是否随应用安装
    // 关联应用包模块
    "formExtensionModule": "entry"                  // 应用包模块名称
  }
}

2.3 卡片配置（form_config.json）

在FormExtensionAbility的metadata配置中，通过resource指定卡片配置文件的路径。通常在resources/base/profile/目录下创建form_config.json文件。

三、卡片配置文件字段

3.1 顶层配置：forms数组

{
  "forms": [
    {
      // 卡片1配置
    },
    {
      // 卡片2配置
    }
    // 最多支持16个卡片
  ]
}

限制：

• 最多支持配置16个卡片

• 若超过16个，则只保留配置的前16个

3.2 核心字段说明

属性名称	含义	数据类型	是否可缺省
name	卡片名称，用于开发者区分不同卡片，最大长度127字节	字符串	否
displayName	卡片展示名称，在卡片管理页面显示，最大长度30字节	字符串	否
description	卡片描述，在卡片管理页面展示功能描述，最大长度255字节	字符串	可缺省
src	卡片对应UI代码的完整路径	字符串	否
uiSyntax	卡片类型：arkts（ArkTS卡片）或 hml（JS卡片）	字符串	可缺省，默认hml
isDefault	是否为默认卡片，每个应用有且只有一个	布尔值	否
supportDimensions	卡片支持的外观规格	字符串数组	否
defaultDimension	卡片的默认尺寸	字符串	否
updateEnabled	是否支持周期性刷新	布尔类型	否
isDynamic	是否为动态卡片（仅ArkTS卡片）	布尔类型	可缺省，默认true
renderingMode	卡片渲染模式	字符串	可缺省，默认fullColor
fontScaleFollowSystem	字体是否跟随系统变化	布尔类型	可缺省，默认true
resizable	是否可以拖拽调整大小	布尔类型	可缺省，默认false

3.3 supportDimensions规格列表

卡片支持的外观规格：

规格	说明	适用设备
1 × 1	1行1列的一宫格	仅支持锁屏使用
1 × 2	1行2列的二宫格	通用
2 × 2	2行2列的四宫格	通用
2 × 4	2行4列的八宫格	通用
2 × 3	2行3列的六宫格	仅手表设备
3 × 3	3行3列的九宫格	仅手表设备
4 × 4	4行4列的十六宫格	通用
6 × 4	6行4列的二十四宫格	通用

3.4 刷新机制配置

{
  "updateEnabled": true,           // 开启周期性刷新
  "scheduledUpdateTime": "10:30",  // 定点刷新时刻（24小时制）
  "updateDuration": 1,              // 定时刷新周期（30分钟为单位）
  "multiScheduledUpdateTime": "08:00,12:00,18:00"  // 多定点刷新（最多24个时间）
}

刷新优先级说明：

• updateDuration（定时刷新）优先级高于scheduledUpdateTime（定点刷新）

• 两者同时配置时，以updateDuration为准

• updateDuration为0时表示不生效

• 正整数N表示刷新周期为30×N分钟

• multiScheduledUpdateTime需要配合scheduledUpdateTime使用

3.5 渲染模式配置

{
  "renderingMode": "fullColor"  // 可选值：fullColor、autoColor、singleColor
}

模式	说明	适用场景
fullColor	全彩模式，颜色和图片不允许被修改	桌面卡片
autoColor	自动模式，根据使用方决定全彩或单色	桌面/锁屏卡片
singleColor	单色模式，通过透明度和模糊区分元素	锁屏卡片

3.6 window配置（仅JS卡片）

{
  "window": {
    "designWidth": 720,        // 页面设计基准宽度
    "autoDesignWidth": true     // 是否自动计算基准宽度
  }
}

属性	说明	是否可缺省
designWidth	页面设计基准宽度，根据实际设备宽度缩放	可缺省，默认720px
autoDesignWidth	是否自动计算基准宽度，为true时designWidth被忽略	可缺省，默认false

3.7 趣味交互配置（API 20+）

funInteractionParams 趣味交互类型

{
  "funInteractionParams": {
    "abilityName": "MyLiveFormAbility",           // 趣味交互Ability名称
    "targetBundleName": "com.example.fun",         // 主包包名（必填）
    "subBundleName": "com.example.sub",            // 独立分包名
    "keepStateDuration": 10000                     // 激活态保持时长（ms）
  }
}

字段说明：

• targetBundleName：必填，趣味交互场景主包包名

• subBundleName：可选，独立分包名

• keepStateDuration：可选，无交互时激活态保持时长，默认10000ms，取值[0,10000]

sceneAnimationParams 场景动效类型

{
  "sceneAnimationParams": {
    "abilityName": "MyLiveFormExtensionAbility"    // 场景动效Ability名称（必填）
  }
}

注意：funInteractionParams和sceneAnimationParams同时配置时，识别为趣味交互类型互动卡片。

3.8 设备适配配置（API 22+）

supportDeviceTypes 标签

{
  "supportDeviceTypes": ["phone", "tablet", "tv", "wearable", "car", "2in1"]
}

属性	含义
phone	手机设备
tablet	平板设备
tv	智慧屏设备
wearable	智能手表设备
car	车机设备
2in1	PC/2in1设备

缺省值：["phone", "tablet", "tv", "wearable", "car", "2in1"]

supportDevicePerformanceClasses 标签

{
  "supportDevicePerformanceClasses": ["high", "medium", "low"]
}

属性	含义
high	设备能力定级为高
medium	设备能力定级为中
low	设备能力定级为低

缺省值：["high", "medium", "low"]

3.9 其他配置字段

字段	说明	默认值
formConfigAbility	桌面点击编辑后拉起的ability路径（URI格式）	空
metadata	卡片的自定义信息	空
supportShapes	卡片的显示形状：rect（矩形）、circle（圆形）	["rect"]
previewImages	卡片预览图，与supportDimensions一一对应	[]
transparencyEnabled	是否为背板透明卡片（仅系统应用）	false
enableBlurBackground	卡片是否使用模糊背板	false
groupId	一组卡片的共同id，用于共享尺寸调整	空字符串

四、完整配置文件示例

4.1 基础卡片配置示例

{
  "forms": [
    {
      // 基本信息
      "name": "weather_widget",
      "displayName": "$string:weather_widget_name",
      "description": "$string:weather_widget_desc",
      "src": "./ets/widget/pages/WeatherWidget.ets",
      "uiSyntax": "arkts",
      
      // 默认设置
      "isDefault": true,
      "defaultDimension": "2×2",
      "supportDimensions": ["2×2", "2×4", "4×4"],
      
      // 刷新设置
      "updateEnabled": true,
      "scheduledUpdateTime": "06:00",
      "updateDuration": 2,  // 每60分钟刷新一次
      
      // 样式设置
      "renderingMode": "autoColor",
      "fontScaleFollowSystem": true,
      "isDynamic": true,
      
      // 设备适配
      "supportDeviceTypes": ["phone", "tablet"],
      "supportDevicePerformanceClasses": ["high", "medium"],
      
      // 其他
      "formConfigAbility": "ability://WeatherSettingAbility",
      "metadata": []
    }
  ]
}

4.2 互动卡片配置示例

{
  "forms": [
    {
      "name": "music_player_widget",
      "displayName": "$string:music_player_name",
      "src": "./ets/widget/pages/MusicWidget.ets",
      "uiSyntax": "arkts",
      "isDefault": false,
      "defaultDimension": "2×4",
      "supportDimensions": ["2×2", "2×4"],
      "updateEnabled": false,
      "isDynamic": true,
      
      // 趣味交互配置（API 20+）
      "funInteractionParams": {
        "targetBundleName": "com.example.music",
        "abilityName": "MusicLiveFormAbility",
        "keepStateDuration": 8000
      },
      
      // 其他配置
      "renderingMode": "fullColor",
      "supportDeviceTypes": ["phone", "tablet", "car"]
    }
  ]
}

4.3 JS卡片配置示例

{
  "forms": [
    {
      "name": "simple_js_widget",
      "displayName": "$string:js_widget_name",
      "src": "./js/widget/pages/SimpleWidget",
      "uiSyntax": "hml",  // JS卡片类型
      "isDefault": false,
      "defaultDimension": "2×2",
      "supportDimensions": ["2×2", "2×4"],
      
      // JS卡片专用window配置
      "window": {
        "designWidth": 720,
        "autoDesignWidth": true
      },
      
      // 由于JS卡片已废弃，建议使用colorMode但注意版本限制
      "colorMode": "auto",  // API 12-19有效，API 20+废弃
      
      "updateEnabled": true,
      "updateDuration": 1
    }
  ]
}

五、注意事项

5.1 五元组变更的影响

// 危险操作：使用资源文件定义name
{
  "name": "$string:widget_name"  // 不建议！资源文件变化会导致ID改变
}

// 安全操作：直接定义字符串
{
  "name": "weather_widget"  // 推荐！稳定的字符串标识
}

后果：五元组变化 → 系统删除原卡片 → 桌面卡片消失

5.2 版本兼容性说明

字段	引入版本	废弃版本	说明
colorMode	API 12	API 20	仅JS卡片，跟随系统颜色模式
multiScheduledUpdateTime	API 18	-	多定点刷新
conditionUpdate	API 18	-	条件刷新（网络刷新）
funInteractionParams	API 20	-	趣味交互配置
sceneAnimationParams	API 20	-	场景动效配置
resizable	API 20	-	调整大小
groupId	API 20	-	卡片组ID
supportDeviceTypes	API 22	-	设备类型支持
supportDevicePerformanceClasses	API 22	-	设备性能等级

5.3 卡片数量限制

{
  "forms": [
    // 卡片1
    // 卡片2
    // ...
    // 卡片16
    // 卡片17  超出限制，不会生效
  ]
}

限制：最多16个卡片，超过部分被忽略

5.4 独立卡片包关联

// 应用包 module.json5
{
  "module": {
    "name": "entry",
    "formWidgetModule": "library"  // 关联卡片包模块
  }
}

// 卡片包 module.json5
{
  "module": {
    "name": "library",
    "type": "shared",
    "formExtensionModule": "entry"  // 关联应用包模块
  }
}

总结

配置清单

必做事项：

• 使用稳定的字符串定义name，避免使用资源文件

• 确保五元组在应用升级后不变

• 合理设置刷新周期，避免过度消耗电量

• 为不同设备类型配置合适的supportDimensions

• 提供预览图（previewImages）增强用户体验

注意事项：

• 检查卡片数量不超过16个

• 确认默认卡片（isDefault）全局唯一

• 验证定时刷新和定点刷新的优先级

• 测试五元组变化时的卡片行为

版本检查：

• 新特性字段（如API 22+）确认目标设备版本支持

• 废弃字段（如colorMode）及时移除

• 互动卡片配置（API 20+）检查能力申请

刷新策略：

• 非必要不开启周期性刷新

• 合理设置刷新间隔（避免过短）

• 使用定点刷新替代定时刷新

卡片类型选择

卡片类型	适用场景	配置要点
静态卡片	简单信息展示	isDynamic: false
动态卡片	需要交互/实时数据	isDynamic: true
趣味交互卡片	游戏、娱乐类	配置funInteractionParams
场景动效卡片	音乐、天气等	配置sceneAnimationParams
JS卡片	兼容旧版本	uiSyntax: "hml"

ArkTS卡片配置文件是定义卡片行为和外观的核心元数据，主要包括：

1. FormExtensionAbility配置：在module.json5中定义卡片生命周期入口

2. 卡片配置：在form_config.json中定义卡片的具体属性和行为

3. 独立卡片包配置：用于解耦卡片和应用包

核心要点：

• 五元组是卡片的唯一标识，变更会导致卡片删除

• 卡片最多支持16个，超过部分被忽略

• 刷新机制中定时刷新优先级高于定点刷新

• 从API 20开始支持互动卡片，从API 22开始支持精细化的设备适配