# 配置ArkTS卡片的配置文件
卡片相关的配置文件包括[FormExtensionAbility](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md)配置和卡片配置。如果是[独立卡片包](./arkts-ui-widget-creation.md)，还会包含[独立卡片包配置](./arkts-ui-widget-configuration.md#独立卡片包配置)。
## FormExtensionAbility配置
卡片需要在[module.json5配置文件](../quick-start/module-configuration-file.md)的`extensionAbilities`标签下，配置`FormExtensionAbility`相关信息。`FormExtensionAbility`需要填写`metadata`元信息标签，其中键名称为固定字符串 “ohos.extension.form”，资源为[卡片具体配置信息的资源索引](#卡片配置)。
配置示例如下：
```json
{
"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配置文件](../quick-start/module-configuration-file.md)中，`formExtensionModule`字段用来关联应用包的`module`。
配置示例如下：
```json
{
"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配置文件。在[创建卡片](./arkts-ui-widget-creation.md)时会自动生成form_config.json配置文件。
### 配置文件字段说明
**表1** 卡片form_config.json配置文件
| 属性名称 | 含义 | 数据类型 | 是否可缺省 |
| -------- | -------- | -------- | -------- |
| forms | 表示应用的全部卡片配置信息。
最多支持配置16个卡片，若超过16个，则保留配置的前16个。 | 数组 | 否 |
| name | 表示卡片的名称，字符串最大长度为127字节。用于开发者区分不同的卡片。 | 字符串 | 否 |
| displayName | 表示卡片的展示名称。主要在卡片管理页面显示，对应卡片预览下[卡片管理页面](./formkit-overview.md#卡片使用场景)中的"ArkTSCard"，用于展示卡片信息，建议能够体现卡片的核心功能或用途。支持字符串或字符串资源索引，建议使用字符串资源索引方式声明，以支持完整多语言能力。字符串最小长度为1字节，最大长度为30字节。 | 字符串 | 否 |
| description | 表示卡片的描述。用于在卡片管理页面展示卡片功能描述，对应卡片预览下[卡片管理页面](./formkit-overview.md#卡片使用场景)中的"This is a ArkTS card game by canvas."。支持字符串或字符串资源索引，建议使用字符串资源索引方式声明，以支持完整多语言能力。字符串最大长度为255字节。 | 字符串 | 可缺省，缺省为空。 |
| src | 表示卡片对应的UI代码的完整路径。当为ArkTS卡片时，完整路径需要包含卡片文件的后缀，如："./ets/widget/pages/WidgetCard.ets"。当为JS卡片时，完整路径无需包含卡片文件的后缀，如："./js/widget/pages/WidgetCard" | 字符串 | 否 |
| uiSyntax | 表示该卡片的类型，当前支持如下两种类型：
- arkts：当前卡片为ArkTS卡片。
- hml：当前卡片为JS卡片。 | 字符串 | 可缺省，缺省值为“hml”。 |
| [window](#window标签) | 用于定义与显示窗口相关的配置。
**说明：**
该字段仅对JS卡片生效。 | 对象 | 可缺省，缺省值见表2。 |
| isDefault | 表示该卡片是否为默认卡片，每个UIAbility有且只有一个默认卡片。
- true：默认卡片。
- false：非默认卡片。 | 布尔值 | 否 |
| colorMode(deprecated) | 表示卡片的主题样式，取值范围如下：
- auto：跟随系统的颜色模式值选取主题。
- dark：深色主题。
- light：浅色主题。
**说明：**
1.从API version 20开始，该接口废弃，卡片主题样式统一跟随系统的颜色模式。
2.该字段仅对JS卡片生效。 | 字符串 | 可缺省，缺省值为“auto”。 |
| supportDimensions | 表示卡片支持的外观规格，取值范围：
- 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列的二十四宫格。
**说明**： 2 \* 3和 3 \* 3仅支持手表设备。 | 字符串数组 | 否 |
| defaultDimension | 表示卡片的默认外观规格，取值必须在该卡片supportDimensions配置的列表中。 | 字符串 | 否 |
| updateEnabled | 表示卡片是否支持周期性刷新（包含定时刷新和定点刷新），取值范围：
- true：表示支持周期性刷新，可以在定时刷新（updateDuration）和定点刷新（scheduledUpdateTime）两种方式任选其一，当两者同时配置时，定时刷新优先生效。
- false：表示不支持周期性刷新。 | 布尔类型 | 否 |
| scheduledUpdateTime | 表示卡片的定点刷新的时刻，采用24小时制，精确到分钟。
**说明：**
updateDuration参数优先级高于scheduledUpdateTime，两者同时配置时，以updateDuration配置的刷新时间为准。 | 字符串 | 可缺省，缺省时不进行定点刷新。 |
| updateDuration | 表示卡片定时刷新的更新周期，单位为30分钟，取值为自然数。
当取值为0时，表示该参数不生效。
当取值为正整数N时，表示刷新周期为30\*N分钟。
**说明：**
updateDuration参数优先级高于scheduledUpdateTime，两者同时配置时，以updateDuration配置的刷新时间为准。 | 数值 | 可缺省，缺省值为“0”。 |
| formConfigAbility | 表示卡片的配置跳转链接，采用URI格式。| 字符串 | 可缺省，缺省值为空。 |
| metadata | 表示卡片的自定义信息，参考[Metadata](../reference/apis-ability-kit/js-apis-bundleManager-metadata.md)数组标签。 | 对象 | 可缺省，缺省值为空。 |
| dataProxyEnabled | 表示卡片是否支持[卡片代理刷新](./arkts-ui-widget-update-by-proxy.md)，取值范围：
- true：表示支持代理刷新。
- false：表示不支持代理刷新。
设置为true时，[定时刷新和下次刷新](./arkts-ui-widget-passive-refresh.md#卡片定时刷新)不生效，但不影响[定点刷新](./arkts-ui-widget-passive-refresh.md#卡片定点刷新)。 | 布尔类型 | 可缺省，缺省值为false。 |
| isDynamic | 表示此卡片是否为动态卡片（仅针对ArkTS卡片生效）。
- true：为[动态卡片](./arkts-form-overview.md#动态卡片) 。
- false：为[静态卡片](./arkts-form-overview.md#静态卡片)。
| 布尔类型 | 可缺省，缺省值为true。 |
| fontScaleFollowSystem | 表示卡片使用方设置此卡片的字体是否支持跟随系统变化。
- true：支持跟随系统字体大小变化 。
- false：不支持跟随系统字体大小变化。
| 布尔类型 | 可缺省，缺省值为true。 |
| supportShapes | 表示卡片的显示形状，取值范围如下：
- rect：表示矩形卡片。
- circle：表示圆形卡片。| 字符串数组 | 可缺省，缺省值为“rect”。 |
| previewImages | 表示卡片预览图, 与配置项`supportDimensions`一一对应。| 字符串 | 可缺省，智能穿戴卡片必须配置，当前仅支持在智能穿戴上使用。 |
| formVisibleNotify | 表示是否通知卡片提供方可见状态变化（仅对系统应用的卡片生效）。
- true：通知卡片提供方可见状态变化。
- false：不通知卡片提供方可见状态变化。 | 布尔类型 | 可缺省，缺省值为false。 |
| transparencyEnabled | 表示是否为透明卡片（仅对系统应用的ArkTS卡片生效）。
- true：表示是透明卡片。
- false：表示不是透明卡片。
| 布尔类型 | 可缺省，缺省值为false。 |
|enableBlurBackground|表示卡片是否使用模糊背板。
- true：开启模糊背板。
- false：关闭模糊背板。|布尔类型|可缺省，缺省值为false。|
|renderingMode|表示卡片的渲染模式，取值范围如下：
- autoColor：自动模式，呈现效果可以配置为全彩或单色。该模式下卡片中的颜色和图片允许卡片使用方修改，卡片添加至桌面或锁屏场景下可以配置为该模式。
- fullColor：全彩模式。该模式下卡片中的颜色和图片不允许被卡片使用方修改，卡片添加至桌面场景下可以配置为该模式。
- 单色模式，通过透明度和模糊区分元素，不使用任何色相。该模式下卡片中的颜色和图片允许卡片使用方修改，卡片添加到锁屏场景下可以配置为该模式。 |字符串|可缺省，缺省值为“fullColor”。|
|multiScheduledUpdateTime|表示卡片的多定点刷新的时刻，作为单点刷新的一个附加参数，采用24小时制，精确到分钟，多个时间用英文逗号分隔，最多写24个时间。
**说明：**
multiScheduledUpdateTime需要配合scheduledUpdateTime使用。|字符串|可缺省，缺省时不进行多定点刷新。|
|conditionUpdate|表示卡片的支持的条件刷新（仅对系统应用的ArkTS卡片生效）。取值范围如下：
- network：表示支持网络刷新。|字符串|可缺省，缺省值为空字符串。|
|[funInteractionParams](#funinteractionparams标签)| 趣味交互类型互动卡片扩展字段。| 对象 | 可缺省，缺省为空。funInteractionParams 和 sceneAnimationParams 同时配置时识别为趣味交互类型互动卡片。|
|[sceneAnimationParams](#sceneanimationparams标签)| [场景动效类型互动卡片](./arkts-ui-liveform-sceneanimation-overview.md)扩展字段。| 对象 | 可缺省，缺省为空。funInteractionParams 和 sceneAnimationParams 同时配置时识别为趣味交互类型互动卡片。|
| resizable | 表示是否可以拖拽卡片调整大小。调整值必须在该卡片或者同groupId卡片的supportDimensions配置列表中。
- true：可以调整大小。
- false：不可以调整大小。
**说明：**
从API version 20开始，支持该字段。 | 布尔类型 | 可缺省，缺省值为false。 |
| groupId | 表示一组卡片的共同id。多张卡片的groupId相同且resizable为true时，多张卡片的supportDimensions配置共享。例如，卡片A和B的groupId相同且resizable均为true，则卡片A可以调整为卡片A和B的supportDimensions配置中的任意尺寸。
推荐多张卡片功能相同且需要调整卡片尺寸时配置。
**说明：**
从API version 20开始，支持该字段。 | 字符串 | 可缺省，缺省值为false。 |
### window标签
此标签标识window对象的内部结构说明。
| 属性名称 | 含义 | 数据类型 | 是否可缺省 |
| -------- | -------- | -------- | -------- |
| designWidth | 标识页面设计基准宽度。以此为基准，根据实际设备宽度来缩放元素大小。 | 数值 | 可缺省，缺省值为720px。 |
| autoDesignWidth | 标识页面设计基准宽度是否自动计算。当配置为true时，designWidth将会被忽略，设计基准宽度由设备宽度与屏幕密度计算得出。 | 布尔值 | 可缺省，缺省值为false。 |
### funInteractionParams标签
此标签标识趣味交互类型互动卡片配置。funInteractionParams 和 sceneAnimationParams 同时配置时识别为趣味交互类型互动卡片。
| 名称 | 类型 | 必填 | 说明 |
|-------------------|-----|----|-------------------------------------------------------------------------------------------------------------------------------------|
| abilityName | 字符串 | 否 | 趣味交互场景LiveFormExtensionAbility名称，默认为空。 |
| targetBundleName | 字符串 | 是 | 趣味交互场景[主包包名](https://developer.huawei.com/consumer/cn/doc/quickApp-Guides/quickgame-independent-subpackage-0000002076341729)。 |
| subBundleName | 字符串 | 否 | 趣味交互场景[独立分包名](https://developer.huawei.com/consumer/cn/doc/quickApp-Guides/quickgame-independent-subpackage-0000002076341729)，默认为空。|
| keepStateDuration | 数值 | 否 | 趣味交互场景无交互时，激活态保持时长。默认值为10000，单位ms。取值为[0,10000]的整数，超过取值范围则取默认值10000。 |
```json
{
"forms": [
{
// ...
"funInteractionParams": {
"targetBundleName": "com.example.funInteraction",
"subBundleName": "com.example.subFunInteraction"
}
}
]
}
```
### sceneAnimationParams标签
此标签标识场景动效类型互动卡片配置。funInteractionParams 和 sceneAnimationParams 同时配置时识别为趣味交互类型互动卡片。
| 名称 | 类型 | 必填 | 说明 |
|---------------------------------------|--------|----|----------------------------|
| abilityName | 字符串 | 是 | 场景动效 extensionAbility 名称。|
| disabledDesktopBehaviors | 字符串数组 | 否 | 支持的取值包括SWIPE_DESKTOP（滑动桌面）、PULL_DOWN_SEARCH（下拉全搜）、LONG_CLICK（长按）、DRAG（拖动）。可以取值一个或多个，缺省表示不禁用任何行为。 |
```json
{
"forms": [
{
// ...
"sceneAnimationParams": {
"abilityName": "MyLiveFormExtensionAbility",
"disabledDesktopBehaviors": [
"SWIPE_DESKTOP",
"PULL_DOWN_SEARCH",
"LONG_CLICK",
"DRAG"
]
}
}
]
}
```
### 配置文件示例
```json
{
"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": []
}
]
}
```