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

   鸿蒙应用开发中，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开始支持精细化的设备适配

# harmonyos # 鸿蒙
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

鸿蒙智能家居中枢：APP如何连接全屋设备——从设备配网到场景联动的完整实战

avatar HarmonyOS开发者社区

2026最新华为手机鸿蒙系统安装 Google Play 终极，附带详细操作步骤

如果你在安装过程中遇到任何报错（比如 DF-DFERH-01 或者登录转圈），欢迎在评论区留言，我会一个个帮大家看。

avatar HarmonyOS开发者社区
cover

鸿蒙开发：HMRouter封装教程（四）

avatar HarmonyOS开发者社区