# 配置ArkTS卡片的配置文件

卡片相关的配置文件包括FormExtensionAbility配置和卡片配置。如果是独立卡片包，还会包含独立卡片包配置。

*   卡片五元组是确认卡片唯一的要素信息。五元组分别为bundleName、moduleName、abilityName、formName、formDimension。其中bundleName是app.json5配置文件标签中bundleName配置项、moduleName是module.json5配置文件标签中的name配置项、abilityName是abilities标签中的name配置项、formName是配置文件字段说明中的name配置项、formDimension对应的是配置文件字段说明中的supportDimensions配置项。
*   五元组不建议使用资源文件导入配置。使用资源文件导入时，资源文件新增字段等，对应的ID都会发生改变，会被认为五元组有改变。
*   如果应用升级后五元组有改变，系统中对应的卡片会被删除，在屏幕上会消失。

#### FormExtensionAbility配置

卡片需要在module.json5配置文件的extensionAbilities标签下，配置FormExtensionAbility相关信息。FormExtensionAbility需要填写metadata元信息标签，其中键名称为固定字符串 “ohos.extension.form”，资源为卡片具体配置信息的资源索引。

配置示例如下：

```
{
  "module": {
    // ...
    "extensionAbilities": [
      {
        "name": "EntryFormAbility",
        "srcEntry": "./ets/entryformability/EntryFormAbility.ets",
        "label": "$string:EntryFormAbility_label",
        "description": "$string:EntryFormAbility_desc",
        "type": "form",
        "metadata": [
          {
            "name": "ohos.extension.form",
            "resource": "$profile:form_config"
          }
        ]
      }
    ],
    // 只在独立卡片包形态中会使用，用来关联卡片包模块。
    "formWidgetModule": "library"
  }
}
```

#### 独立卡片包配置

相对应地，在卡片包的module.json5配置文件中，formExtensionModule字段用来关联应用包的module。

配置示例如下：

```
{
  "module": {
    "name": "library",
    "type": "shared",
    "description": "$string:shared_desc",
    "deviceTypes": [
      "phone"
    ],
    "deliveryWithInstall": true,
    // 只在独立卡片包形态中会使用，用来关联应用包模块。
    "formExtensionModule": "entry"
  }
}
```

#### 卡片配置

在上述FormExtensionAbility的元信息metadata配置项中，可以指定卡片具体配置信息的资源索引。例如当resource指定为$profile:form\_config时，会使用开发视图的resources/base/profile/目录下的form\_config.json作为卡片profile配置文件。在创建卡片时会自动生成form\_config.json配置文件。

#### 配置文件字段说明

**表1** 卡片form\_config.json配置文件

| 属性名称 | 含义 | 数据类型 | 是否可缺省 |
| --- | --- | --- | --- |
| forms | 表示应用的全部卡片配置信息。 最多支持配置16个卡片，若超过16个，则保留配置的前16个。 | 数组 | 否 |
| name | 表示卡片的名称，字符串最大长度为127字节。用于开发者区分不同的卡片。 说明： 该字段不建议引用资源文件。 | 字符串 | 否 |
| displayName | 表示卡片的展示名称。主要在卡片管理页面显示，对应卡片预览下卡片管理页面中的"cardName"，用于展示卡片信息，建议能够体现卡片的核心功能或用途。支持字符串或字符串资源索引，建议使用字符串资源索引方式声明，以支持完整多语言能力。字符串最小长度为1字节，最大长度为30字节。 | 字符串 | 否 |
| description | 表示卡片的描述。用于在卡片管理页面展示卡片功能描述，对应卡片预览下卡片管理页面中的"This is a service widget."。支持字符串或字符串资源索引，建议使用字符串资源索引方式声明，以支持完整多语言能力。字符串最大长度为255字节。 | 字符串 | 可缺省，缺省为空。 |
| src | 表示卡片对应的UI代码的完整路径。当为ArkTS卡片时，完整路径需要包含卡片文件的后缀，如："./ets/widget/pages/WidgetCard.ets"。当为JS卡片时，完整路径无需包含卡片文件的后缀，如："./js/widget/pages/WidgetCard"。 | 字符串 | 否 |
| uiSyntax | 表示该卡片的类型，当前支持如下两种类型： - arkts：当前卡片为ArkTS卡片。 - hml：当前卡片为JS卡片。 | 字符串 | 可缺省，缺省值为“hml”。 |
| window | 用于定义与显示窗口相关的配置。 说明： 该字段仅对JS卡片生效。 | 对象 | 可缺省，缺省值参考window标签表格。 |
| isDefault | 表示该卡片是否为默认卡片(在卡片中心内希望优先展示的卡片)，每个应用有且只有一个默认卡片。 - true：默认卡片。 - false：非默认卡片。 说明： 应用上架时每个应用只允许配置一张默认卡片。 | 布尔值 | 否 |
| colorMode(deprecated) | 表示卡片的主题样式，取值范围如下： - auto：跟随系统的颜色模式值选取主题。 - dark：深色主题。 - light：浅色主题。 说明： 1. 从API version 12开始支持该配置项，从API version 20开始废弃该配置项，卡片主题样式统一跟随系统的颜色模式。 2. 该字段仅对JS卡片生效。 | 字符串 | 可缺省，缺省值为“auto”。 |
| 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列的二十四宫格。 说明：具体设备支持情况参考supportDimensions字段与设备支持关系表。 | 字符串数组 | 否 |
| defaultDimension | 表示卡片的默认尺寸，取值必须在该卡片supportDimensions配置的列表中。 | 字符串 | 否 |
| updateEnabled | 表示卡片是否支持周期性刷新（包含定时刷新和定点刷新），取值范围： - true：表示支持周期性刷新，可以在定时刷新（updateDuration）和定点刷新（scheduledUpdateTime）两种方式任选其一，当两者同时配置时，定时刷新优先生效。 - false：表示不支持周期性刷新。 | 布尔类型 | 否 |
| scheduledUpdateTime | 表示卡片的定点刷新的时刻，采用24小时制，精确到分钟，例如："10:30"。 说明： updateDuration参数优先级高于scheduledUpdateTime，两者同时配置时，以updateDuration配置的刷新时间为准。 | 字符串 | 可缺省，缺省值为“0:0”，缺省时不进行定点刷新。 |
| updateDuration | 表示卡片定时刷新的更新周期，单位为30分钟，取值为自然数。 当取值为0时，表示该参数不生效。 当取值为正整数N时，表示刷新周期为30*N分钟。 说明： updateDuration参数优先级高于scheduledUpdateTime，两者同时配置时，以updateDuration配置的刷新时间为准。 | 数值 | 可缺省，缺省值为0。 |
| formConfigAbility | 表示桌面点击编辑后，需要拉起的ability路径，采用URI格式。 | 字符串 | 可缺省，缺省值为空。 |
| metadata | 表示卡片的自定义信息，参考Metadata数组标签。 | 对象 | 可缺省，缺省值为空。 |
| dataProxyEnabled | 表示卡片是否支持卡片代理刷新，取值范围： - true：表示支持代理刷新。 - false：表示不支持代理刷新。 设置为true时，定时刷新和下次刷新不生效，但不影响定点刷新。 说明： 从API version 12开始，支持该字段。 | 布尔类型 | 可缺省，缺省值为false。 |
| isDynamic | 表示此卡片是否为动态卡片（仅针对ArkTS卡片生效）。 - true：为动态卡片 。 - false：为静态卡片。 | 布尔类型 | 可缺省，缺省值为true。 |
| fontScaleFollowSystem | 表示卡片使用方设置此卡片的字体是否支持跟随系统变化。 - true：支持跟随系统字体大小变化。 - false：不支持跟随系统字体大小变化。 | 布尔类型 | 可缺省，缺省值为true。 |
| supportShapes | 表示卡片的显示形状，取值范围如下： - rect：表示矩形卡片。 - circle：表示圆形卡片。 | 字符串数组 | 可缺省，缺省值：["rect"]。 |
| previewImages | 表示卡片预览图, 与配置项supportDimensions一一对应。智能穿戴卡片必须配置，当前仅支持在智能穿戴上使用。 | 字符串数组 | 可缺省，缺省值：[]。 |
| transparencyEnabled | 表示是否为背板透明卡片（仅对系统应用或者申请了背板透明卡片能力的ArkTS卡片生效）。 - true：表示是背板透明卡片。 - false：表示不是背板透明卡片。 | 布尔类型 | 可缺省，缺省值为false。 |
| enableBlurBackground | 表示卡片是否使用模糊背板。 - true：开启模糊背板。 - false：关闭模糊背板。 说明： 本特性对产品功耗、性能要求较高，从API version 23开始仅在旗舰机型上支持，在不支持的机型上调用后不生效。 | 布尔类型 | 可缺省，缺省值为false。 |
| renderingMode | 表示卡片的渲染模式，取值范围如下： - autoColor：自动模式，呈现效果可以根据卡片使用方确定最终是全彩模式还是单色模式，具体请参考卡片色彩。该模式下卡片中的颜色和图片允许卡片使用方修改，卡片配置了该模式就可以添加到桌面或锁屏上。 - fullColor：全彩模式，具体请参考卡片色彩。该模式下卡片中的颜色和图片不允许被卡片使用方修改，卡片配置了该模式就可以添加到桌面上。 - singleColor：单色模式，通过透明度和模糊区分元素，不使用任何色相，具体请参考卡片色彩。该模式下卡片中的颜色和图片允许卡片使用方修改，卡片配置了该模式就可以添加到锁屏上。 说明： 从API version 15开始，支持该字段。 | 字符串 | 可缺省，缺省值为“fullColor”。 |
| multiScheduledUpdateTime | 表示卡片的多定点刷新的时刻，作为单点刷新的一个附加参数，采用24小时制，精确到分钟，多个时间用英文逗号分隔，最多写24个时间。 说明： 从API version 18开始，支持该字段。multiScheduledUpdateTime需要配合scheduledUpdateTime使用。 | 字符串 | 可缺省，缺省时不进行多定点刷新。 |
| conditionUpdate | 表示卡片支持的条件刷新。取值范围如下： - network：表示支持网络刷新。 说明： 从API版本18开始，支持该字段配置。从API版本26.0.0开始，设置后功能生效。 | 字符串数组 | 可缺省，缺省值为空字符串数组。 |
| funInteractionParams | 趣味交互类型互动卡片扩展字段。从API version 20开始，支持该字段。 | 对象 | 可缺省，缺省为空。funInteractionParams 和 sceneAnimationParams 同时配置时识别为趣味交互类型互动卡片。 |
| sceneAnimationParams | 场景动效类型互动卡片扩展字段。从API version 20开始，支持该字段。 | 对象 | 可缺省，缺省为空。funInteractionParams 和 sceneAnimationParams 同时配置时识别为趣味交互类型互动卡片。 |
| resizable | 表示是否可以拖拽卡片调整大小。调整值必须在该卡片或者同groupId卡片的supportDimensions配置列表中。 - true：可以调整大小。 - false：不可以调整大小。 说明： 从API version 20开始，支持该字段。 | 布尔类型 | 可缺省，缺省值为false。 |
| groupId | 表示一组卡片的共同id。多张卡片的groupId相同且resizable为true时，多张卡片的supportDimensions配置共享，推荐多张卡片功能相同且需要调整卡片尺寸时配置。 示例一：卡片A的groupId配置为'1'，resizable配置为true，supportDimension为2*2。卡片B的groupId配置为'1'，resizable配置为true，supportDimension为2*4。那么支持卡片A、B之间调整大小。 示例二：当supportDimension存在多个，resizable设置为true时，优先在同一张卡片之间调整大小。卡片A的resizable配置为true，supportDimension为2*2、2*4，支持卡片A的两个尺寸之间调整大小。 示例三：卡片A的groupId配置为'1'，resizable配置为true，supportDimension为1*2。卡片B的groupId配置为'1'，resizable配置为true，supportDimension为2*2、2*4、4*4。卡片A可以调整到卡片B的默认尺寸，卡片B只支持在B卡片支持的三个尺寸之间调整大小，无法调整为卡片A。 说明： 从API version 20开始，支持该字段。 | 字符串 | 可缺省，空字符串。 |
| supportDeviceTypes | 表示特定卡片支持的设备类型。例如，卡片的supportDeviceTypes字段配置了“phone”、“tablet”、“tv”，那么该卡片就支持在手机、平板、大屏上面显示。 说明： 从API version 22开始，支持该字段。 | 字符串数组 | 可缺省，缺省值：["phone", "tablet", "tv", "wearable", "car", "2in1"]。 |
| supportDevicePerformanceClasses | 表示特定卡片支持的设备性能等级信息。例如，卡片的supportDevicePerformanceClasses字段配置了“high”、“medium”、“low”，那么该卡片就支持在性能等级为“high”、“medium”、“low”设备上面显示。 说明： 从API version 22开始，支持该字段。 | 字符串数组 | 可缺省，缺省值：["high", "medium", "low"]。 |
| standby | 待机屏保显示页面卡片扩展字段。 说明： 从API version 23开始，支持该字段。依赖系统实现待机屏保显示应用后展示 | 对象 | 可缺省，属性缺省值见standby标签。 |

#### supportDeviceTypes标签

此标签标识卡片支持的设备类型。

| 属性名称 | 含义 | 数据类型 |
| --- | --- | --- |
| phone | 手机设备。 | 字符串 |
| tablet | 平板设备。 | 字符串 |
| tv | 智慧屏设备。 | 字符串 |
| wearable | 智能手表设备。 | 字符串 |
| car | 车机设备。 | 字符串 |
| 2in1 | PC/2in1设备。 | 字符串 |

#### supportDevicePerformanceClasses标签

此标签标识卡片支持的设备性能等级信息。

| 属性名称 | 含义 | 数据类型 |
| --- | --- | --- |
| high | 表示设备能力定级为高。 | 字符串 |
| medium | 表示设备能力定级为中。 | 字符串 |
| low | 表示设备能力定级为低。 | 字符串 |

#### window标签

此标签标识window对象的内部结构说明。只支持在JS卡片中使用。

| 属性名称 | 含义 | 数据类型 | 是否可缺省 |
| --- | --- | --- | --- |
| designWidth | 标识页面设计基准宽度。以此为基准，根据实际设备宽度来缩放元素大小。取值范围大于等于0小于2^16，单位：px | 数值 | 可缺省，缺省值为720px。 |
| autoDesignWidth | 标识页面设计基准宽度是否自动计算。当配置为true时，designWidth将会被忽略，设计基准宽度由设备宽度与屏幕密度计算得出。 | 布尔值 | 可缺省，缺省值为false。 |

#### funInteractionParams标签

此标签标识趣味交互类型互动卡片配置。funInteractionParams 和 sceneAnimationParams 同时配置时识别为趣味交互类型互动卡片。

| 名称 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| abilityName | 字符串 | 否 | 趣味交互场景LiveFormExtensionAbility名称，默认为空。 |
| targetBundleName | 字符串 | 是 | 趣味交互场景主包包名。 |
| subBundleName | 字符串 | 否 | 趣味交互场景独立分包名，默认为空。 |
| keepStateDuration | 数值 | 否 | 趣味交互场景无交互时，激活态保持时长。默认值为10000，单位ms。取值为(0,60000]的整数，超过取值范围则取最大值60000。 说明： 在API版本26.0.0之前该字段为(0,10000]的整数，超过取值范围则取默认值10000。 |

```
{
  "forms": [
    {
       // ...
      "funInteractionParams": {
         "targetBundleName": "com.example.funInteraction",
         "subBundleName": "com.example.subFunInteraction"
      }
    }
  ]
}
```

#### sceneAnimationParams标签

此标签标识场景动效类型互动卡片配置。funInteractionParams 和 sceneAnimationParams 同时配置时识别为趣味交互类型互动卡片。

| 名称 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| abilityName | 字符串 | 是 | 场景动效LiveFormExtensionAbility名称。 |
| disabledDesktopBehaviors | 字符串数组 | 否 | 支持的取值包括SWIPE_DESKTOP（滑动桌面）、PULL_DOWN_SEARCH（下拉全搜）、LONG_CLICK（长按）、DRAG（拖动）。可以取值一个或多个，缺省表示不禁用任何行为。 说明： 从API version 20开始支持该字段配置，功能仅对系统应用生效。 |
| triggerTypes | 字符串数组 | 否 | 场景动效触发类型，支持的取值包括shake（摇一摇）。 说明： 从API版本26.0.0开始，支持该字段。 |

```
   {
     "forms": [
       {
         "sceneAnimationParams": {
            "abilityName": "MyLiveFormExtensionAbility",
            "triggerTypes": [
              "shake"
            ]
         }
       }
     ]
   }
```

#### standby标签

此标签标识standby对象的内部结构说明。应用通过开放能力申请，且卡片isSupported配置为true才支持在待机屏保显示界面展示。

| 属性名称 | 含义 | 数据类型 | 是否可缺省 |
| --- | --- | --- | --- |
| isSupported | 标识卡片是否支持在待机屏保显示界面展示。 - true：表示卡片支持在待机屏保显示界面展示。 - false：表示卡片不支持在待机屏保显示界面展示。 | 布尔值 | 可缺省，缺省值为true。 |
| isAdapted | 标识卡片是否针对待机屏保显示界面做过适配，配置成true，会把卡片布局组件中backgroundImage移除。 - true：表示卡片适配过待机屏保显示界面。 - false：表示卡片没有适配过待机屏保显示界面。 | 布尔值 | 可缺省，缺省值为false。 |
| isPrivacySensitive | 标识卡片是否是隐私敏感卡片，隐私敏感卡片在待机屏保显示界面展示会用蒙层覆盖。 - true：表示卡片是隐私敏感卡片。 - false：表示卡片不是隐私敏感卡片。 | 布尔值 | 可缺省，缺省值为false。 |

```
{
  "forms": [
    {
      // ...
      "standby": {
        "isSupported": true,
        "isAdapted": false,
        "isPrivacySensitive": false
      }
    }
  ]
}
```

#### 配置文件示例

```
{
  "forms": [
    {
      "name": "widget",
      "displayName": "$string:widget_display_name",
      "description": "$string:widget_desc",
      "src": "./ets/widget/pages/WidgetCard.ets",
      "uiSyntax": "arkts",
      "window": {
        "designWidth": 720,
        "autoDesignWidth": true
      },
      "renderingMode": "fullColor",
      "isDefault": true,
      "updateEnabled": true,
      "scheduledUpdateTime": "10:30",
      "updateDuration": 1,
      "defaultDimension": "2*2",
      "supportDimensions": [
        "2*2"
      ],
      "formConfigAbility": "ability://EntryAbility",
      "isDynamic": true,
      "metadata": []
    }
  ]
}
```

#### supportDimensions字段与设备支持关系表

各类型设备支持的卡片尺寸规格。其中"仅锁屏"表示该尺寸仅适用于锁屏场景；"部分机型"表示具体支持情况需根据设备桌面宫格配置判断。

| 卡片尺寸信息 | Phone | PC | 2in1 | Tablet | TV | Car | Wearable |
| --- | --- | --- | --- | --- | --- | --- | --- |
| "1*2" | 是 | 是 | 是 | 是 | 是 | 是 | 是 |
| "2*2" | 是 | 是 | 是 | 是 | 是 | 是 | 是 |
| "2*4" | 是 | 是 | 是 | 是 | 是 | 是 | 否 |
| "4*4" | 是 | 是 | 是 | 是 | 是 | 是 | 否 |
| "1*1" | 是（仅锁屏） | 否 | 否 | 是（仅锁屏） | 否 | 否 | 是 |
| "6*4" | 是（部分机型） | 是 | 是 | 是（部分机型） | 否 | 否 | 否 |
| "2*3" | 否 | 否 | 否 | 否 | 否 | 否 | 是 |
| "3*3" | 否 | 否 | 否 | 否 | 否 | 否 | 是 |