1# 配置ArkTS卡片的配置文件 2<!--Kit: Form Kit--> 3<!--Subsystem: Ability--> 4<!--Owner: @cx983299475--> 5<!--Designer: @xueyulong--> 6<!--Tester: @chenmingze--> 7<!--Adviser: @Brilliantry_Rui--> 8 9卡片相关的配置文件包括[FormExtensionAbility](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md)配置和卡片配置。如果是[独立卡片包](./arkts-ui-widget-creation.md)，还会包含[独立卡片包配置](./arkts-ui-widget-configuration.md#独立卡片包配置)。 10 11## FormExtensionAbility配置 12卡片需要在[module.json5配置文件](../quick-start/module-configuration-file.md)的`extensionAbilities`标签下，配置`FormExtensionAbility`相关信息。`FormExtensionAbility`需要填写`metadata`元信息标签，其中键名称为固定字符串 “ohos.extension.form”，资源为[卡片具体配置信息的资源索引](#卡片配置)。 13 14 配置示例如下： 15 16 17 ```json 18 { 19 "module": { 20 // ... 21 "extensionAbilities": [ 22 { 23 "name": "EntryFormAbility", 24 "srcEntry": "./ets/entryformability/EntryFormAbility.ets", 25 "label": "$string:EntryFormAbility_label", 26 "description": "$string:EntryFormAbility_desc", 27 "type": "form", 28 "metadata": [ 29 { 30 "name": "ohos.extension.form", 31 "resource": "$profile:form_config" 32 } 33 ] 34 } 35 ], 36 "formWidgetModule": "library" // 只在独立卡片包形态中会使用，用来关联卡片包模块。 37 } 38 } 39 ``` 40## 独立卡片包配置 41相对应地，在卡片包的[module.json5配置文件](../quick-start/module-configuration-file.md)中，`formExtensionModule`字段用来关联应用包的`module`。<br> 42配置示例如下： 43```json 44{ 45 "module": { 46 "name": "library", 47 "type": "shared", 48 "description": "$string:shared_desc", 49 "deviceTypes": [ 50 "phone" 51 ], 52 "deliveryWithInstall": true, 53 "formExtensionModule": "entry" // 只在独立卡片包形态中会使用，用来关联应用包模块。 54 } 55} 56``` 57 58## 卡片配置 59 60在上述FormExtensionAbility的元信息metadata配置项中，可以指定卡片具体配置信息的资源索引。例如当resource指定为$profile:form_config时，会使用开发视图的resources/base/profile/目录下的form_config.json作为卡片profile配置文件。在[创建卡片](./arkts-ui-widget-creation.md)时会自动生成form_config.json配置文件。 61 62### 配置文件字段说明 63 64 **表1** 卡片form_config.json配置文件 65 66 | 属性名称 | 含义 | 数据类型 | 是否可缺省 | 67 | -------- | -------- | -------- | -------- | 68 | forms | 表示应用的全部卡片配置信息。<br/>最多支持配置16个卡片，若超过16个，则保留配置的前16个。 | 数组 | 否 | 69 | name | 表示卡片的名称，字符串最大长度为127字节。用于开发者区分不同的卡片。 | 字符串 | 否 | 70 | displayName | 表示卡片的展示名称。主要在卡片管理页面显示，对应卡片预览下[卡片管理页面](./formkit-overview.md#卡片使用场景)中的<!--RP3-->"ArkTSCard"<!--RP3End-->，用于展示卡片信息，建议能够体现卡片的核心功能或用途。支持字符串或字符串资源索引，建议使用字符串资源索引方式声明，以支持完整多语言能力。字符串最小长度为1字节，最大长度为30字节。 | 字符串 | 否 | 71 | description | 表示卡片的描述。用于在卡片管理页面展示卡片功能描述，对应卡片预览下[卡片管理页面](./formkit-overview.md#卡片使用场景)中的<!--RP4-->"This is a ArkTS card game by canvas."<!--RP4End-->。支持字符串或字符串资源索引，建议使用字符串资源索引方式声明，以支持完整多语言能力。字符串最大长度为255字节。 | 字符串 | 可缺省，缺省为空。 | 72 | src | 表示卡片对应的UI代码的完整路径。当为ArkTS卡片时，完整路径需要包含卡片文件的后缀，如："./ets/widget/pages/WidgetCard.ets"。当为JS卡片时，完整路径无需包含卡片文件的后缀，如："./js/widget/pages/WidgetCard" | 字符串 | 否 | 73 | uiSyntax | 表示该卡片的类型，当前支持如下两种类型：<br/>- arkts：当前卡片为ArkTS卡片。<br/>- hml：当前卡片为JS卡片。 | 字符串 | 可缺省，缺省值为“hml”。 | 74 | [window](#window标签) | 用于定义与显示窗口相关的配置。<br/>**说明：**<br/>该字段仅对JS卡片生效。 | 对象 | 可缺省，缺省值见表2。 | 75 | isDefault | 表示该卡片是否为默认卡片，每个UIAbility有且只有一个默认卡片。<br/>- true：默认卡片。<br/>- false：非默认卡片。 | 布尔值 | 否 | 76 | colorMode<sup>(deprecated)</sup> | 表示卡片的主题样式，取值范围如下：<br/>- auto：跟随系统的颜色模式值选取主题。<br/>- dark：深色主题。<br/>- light：浅色主题。<br/>**说明：**<br/>1.从API version 20开始，该接口废弃，卡片主题样式统一跟随系统的颜色模式。<br/>2.该字段仅对JS卡片生效。 | 字符串 | 可缺省，缺省值为“auto”。 | 77 | supportDimensions | 表示卡片支持的外观规格，取值范围：<!--RP5--><!--RP5End--><br/>- 1 \* 2：表示1行2列的二宫格。<br/>- 2 \* 2：表示2行2列的四宫格。<br/>- 2 \* 4：表示2行4列的八宫格。<br/>- 2 \* 3：表示2行3列的六宫格。<br/>- 3 \* 3：表示3行3列的九宫格。<br/>- 4 \* 4：表示4行4列的十六宫格。<br/>- 6 \* 4：表示6行4列的二十四宫格。<br>**说明**： 2 \* 3和 3 \* 3仅支持手表设备<!--RP6--><!--RP6End-->。 | 字符串数组 | 否 | 78 | defaultDimension | 表示卡片的默认外观规格，取值必须在该卡片supportDimensions配置的列表中。 | 字符串 | 否 | 79 | updateEnabled | 表示卡片是否支持周期性刷新（包含定时刷新和定点刷新），取值范围：<br/>- true：表示支持周期性刷新，可以在定时刷新（updateDuration）和定点刷新（scheduledUpdateTime）两种方式任选其一，当两者同时配置时，定时刷新优先生效。<br/>- false：表示不支持周期性刷新。 | 布尔类型 | 否 | 80 | scheduledUpdateTime | 表示卡片的定点刷新的时刻，采用24小时制，精确到分钟。<br/>**说明：**<br/>updateDuration参数优先级高于scheduledUpdateTime，两者同时配置时，以updateDuration配置的刷新时间为准。 | 字符串 | 可缺省，缺省时不进行定点刷新。 | 81 | updateDuration | 表示卡片定时刷新的更新周期，单位为30分钟，取值为自然数。<br/>当取值为0时，表示该参数不生效。<br/>当取值为正整数N时，表示刷新周期为30\*N分钟。<br/>**说明：**<br/>updateDuration参数优先级高于scheduledUpdateTime，两者同时配置时，以updateDuration配置的刷新时间为准。 | 数值 | 可缺省，缺省值为“0”。 | 82 | formConfigAbility | 表示卡片的配置跳转链接，采用URI格式。| 字符串 | 可缺省，缺省值为空。 | 83 | metadata | 表示卡片的自定义信息，参考[Metadata](../reference/apis-ability-kit/js-apis-bundleManager-metadata.md)数组标签。 | 对象 | 可缺省，缺省值为空。 | 84 | <!--DelRow-->dataProxyEnabled | 表示卡片是否支持[卡片代理刷新](./arkts-ui-widget-update-by-proxy.md)，取值范围：<br/>- true：表示支持代理刷新。<br/>- false：表示不支持代理刷新。<br/>设置为true时，[定时刷新和下次刷新](./arkts-ui-widget-passive-refresh.md#卡片定时刷新)不生效，但不影响[定点刷新](./arkts-ui-widget-passive-refresh.md#卡片定点刷新)。 | 布尔类型 | 可缺省，缺省值为false。 | 85 | isDynamic | 表示此卡片是否为动态卡片（仅针对ArkTS卡片生效）。 <br/>- true：为[动态卡片](./arkts-form-overview.md#动态卡片) 。<br/>- false：为[静态卡片](./arkts-form-overview.md#静态卡片)。<br/>| 布尔类型 | 可缺省，缺省值为true。 | 86 | fontScaleFollowSystem | 表示卡片使用方设置此卡片的字体是否支持跟随系统变化。 <br/>- true：支持跟随系统字体大小变化 。<br/>- false：不支持跟随系统字体大小变化。<br/>| 布尔类型 | 可缺省，缺省值为true。 | 87 | supportShapes | 表示卡片的显示形状，取值范围如下：<br/>- rect：表示矩形卡片。<br/>- circle：表示圆形卡片。| 字符串数组 | 可缺省，缺省值为“rect”。 | 88 | previewImages | 表示卡片预览图, 与配置项`supportDimensions`一一对应。| 字符串 | 可缺省，智能穿戴卡片必须配置，当前仅支持在智能穿戴上使用。 | 89 | <!--DelRow-->formVisibleNotify | 表示是否通知卡片提供方可见状态变化（仅对系统应用的卡片生效）。<br/>- true：通知卡片提供方可见状态变化。<br/>- false：不通知卡片提供方可见状态变化。 | 布尔类型 | 可缺省，缺省值为false。 | 90 | <!--DelRow-->transparencyEnabled | 表示是否为透明卡片（仅对系统应用的ArkTS卡片生效）。 <br/>- true：表示是透明卡片。<br/>- false：表示不是透明卡片。<br/>| 布尔类型 | 可缺省，缺省值为false。 | 91 |enableBlurBackground|表示卡片是否使用模糊背板。<br/>- true：开启模糊背板。<br/>- false：关闭模糊背板。|布尔类型|可缺省，缺省值为false。| 92 |renderingMode|表示卡片的渲染模式，取值范围如下：<br/>- autoColor：自动模式，呈现效果可以配置为全彩或单色<!--RP7--><!--RP7End-->。该模式下卡片中的颜色和图片允许卡片使用方修改，卡片添加至桌面或锁屏场景下可以配置为该模式。<br/>- fullColor：全彩模式<!--RP7--><!--RP7End-->。该模式下卡片中的颜色和图片不允许被卡片使用方修改，卡片添加至桌面场景下可以配置为该模式。<br/>- 单色模式，通过透明度和模糊区分元素，不使用任何色相<!--RP7--><!--RP7End-->。该模式下卡片中的颜色和图片允许卡片使用方修改，卡片添加到锁屏场景下可以配置为该模式。 |字符串|可缺省，缺省值为“fullColor”。| 93 |multiScheduledUpdateTime|表示卡片的多定点刷新的时刻，作为单点刷新的一个附加参数，采用24小时制，精确到分钟，多个时间用英文逗号分隔，最多写24个时间。<br/>**说明：**<br/>multiScheduledUpdateTime需要配合scheduledUpdateTime使用。|字符串|可缺省，缺省时不进行多定点刷新。| 94 |conditionUpdate|表示卡片的支持的条件刷新（仅对系统应用的ArkTS卡片生效）。取值范围如下：<br/>- network：表示支持网络刷新。|字符串|可缺省，缺省值为空字符串。| 95 |[funInteractionParams](#funinteractionparams标签)| 趣味交互类型互动卡片扩展字段。| 对象 | 可缺省，缺省为空。funInteractionParams 和 sceneAnimationParams 同时配置时识别为趣味交互类型互动卡片。| 96 |[sceneAnimationParams](#sceneanimationparams标签)| [场景动效类型互动卡片](./arkts-ui-liveform-sceneanimation-overview.md)扩展字段。| 对象 | 可缺省，缺省为空。funInteractionParams 和 sceneAnimationParams 同时配置时识别为趣味交互类型互动卡片。| 97 | resizable | 表示是否可以拖拽卡片调整大小。调整值必须在该卡片或者同groupId卡片的supportDimensions配置列表中。<br/>- true：可以调整大小。<br/>- false：不可以调整大小。<br/>**说明：**<br/>从API version 20开始，支持该字段。 | 布尔类型 | 可缺省，缺省值为false。 | 98 | groupId | 表示一组卡片的共同id。多张卡片的groupId相同且resizable为true时，多张卡片的supportDimensions配置共享。例如，卡片A和B的groupId相同且resizable均为true，则卡片A可以调整为卡片A和B的supportDimensions配置中的任意尺寸。<br/>推荐多张卡片功能相同且需要调整卡片尺寸时配置。<br/>**说明：**<br/>从API version 20开始，支持该字段。 | 字符串 | 可缺省，缺省值为false。 | 99 100### window标签 101 102此标签标识window对象的内部结构说明。 103 104 | 属性名称 | 含义 | 数据类型 | 是否可缺省 | 105 | -------- | -------- | -------- | -------- | 106 | designWidth | 标识页面设计基准宽度。以此为基准，根据实际设备宽度来缩放元素大小。 | 数值 | 可缺省，缺省值为720px。 | 107 | autoDesignWidth | 标识页面设计基准宽度是否自动计算。当配置为true时，designWidth将会被忽略，设计基准宽度由设备宽度与屏幕密度计算得出。 | 布尔值 | 可缺省，缺省值为false。 | 108 109### funInteractionParams标签 110 111此标签标识趣味交互类型互动卡片配置。funInteractionParams 和 sceneAnimationParams 同时配置时识别为趣味交互类型互动卡片。 112 113| 名称 | 类型 | 必填 | 说明 | 114|-------------------|-----|----|-------------------------------------------------------------------------------------------------------------------------------------| 115| abilityName | 字符串 | 否 | 趣味交互场景LiveFormExtensionAbility名称，默认为空。 | 116| targetBundleName | 字符串 | 是 | 趣味交互场景[主包包名](https://developer.huawei.com/consumer/cn/doc/quickApp-Guides/quickgame-independent-subpackage-0000002076341729)。 | 117| subBundleName | 字符串 | 否 | 趣味交互场景[独立分包名](https://developer.huawei.com/consumer/cn/doc/quickApp-Guides/quickgame-independent-subpackage-0000002076341729)，默认为空。| 118| keepStateDuration | 数值 | 否 | 趣味交互场景无交互时，激活态保持时长。默认值为10000，单位ms。取值为[0,10000]的整数，超过取值范围则取默认值10000。 | 119 120```json 121{ 122 "forms": [ 123 { 124 // ... 125 "funInteractionParams": { 126 "targetBundleName": "com.example.funInteraction", 127 "subBundleName": "com.example.subFunInteraction" 128 } 129 } 130 ] 131} 132``` 133 134### sceneAnimationParams标签 135 136此标签标识场景动效类型互动卡片配置。funInteractionParams 和 sceneAnimationParams 同时配置时识别为趣味交互类型互动卡片。 137 138| 名称 | 类型 | 必填 | 说明 | 139|---------------------------------------|--------|----|----------------------------| 140| abilityName | 字符串 | 是 | 场景动效 extensionAbility 名称。| 141| <!--DelRow-->disabledDesktopBehaviors | 字符串数组 | 否 | 支持的取值包括SWIPE_DESKTOP（滑动桌面）、PULL_DOWN_SEARCH（下拉全搜）、LONG_CLICK（长按）、DRAG（拖动）。可以取值一个或多个，缺省表示不禁用任何行为。 | 142 143<!--RP2--> 144 ```json 145 { 146 "forms": [ 147 { 148 // ... 149 "sceneAnimationParams": { 150 "abilityName": "MyLiveFormExtensionAbility", 151 "disabledDesktopBehaviors": [ 152 "SWIPE_DESKTOP", 153 "PULL_DOWN_SEARCH", 154 "LONG_CLICK", 155 "DRAG" 156 ] 157 } 158 } 159 ] 160 } 161 ``` 162<!--RP2End--> 163 164### 配置文件示例 165 166<!--RP1--> 167 ```json 168 { 169 "forms": [ 170 { 171 "name": "widget", 172 "displayName": "$string:widget_display_name", 173 "description": "$string:widget_desc", 174 "src": "./ets/widget/pages/WidgetCard.ets", 175 "uiSyntax": "arkts", 176 "window": { 177 "designWidth": 720, 178 "autoDesignWidth": true 179 }, 180 "renderingMode": "fullColor", 181 "isDefault": true, 182 "updateEnabled": true, 183 "scheduledUpdateTime": "10:30", 184 "updateDuration": 1, 185 "defaultDimension": "2*2", 186 "supportDimensions": [ 187 "2*2" 188 ], 189 "formConfigAbility": "ability://EntryAbility", 190 "isDynamic": true, 191 "metadata": [] 192 } 193 ] 194 } 195 ``` 196<!--RP1End-->