大网数据广告活动
OpenHarmony 设备与应用开发

配置ArkTS卡片的配置文件

· 52CE 我爱测

卡片相关的配置文件包括FormExtensionAbility配置和卡片配置。如果是独立卡片包,还会包含独立卡片包配置。 > **说明:** > >- 卡片五元组是确认卡片唯一的要素信息。五元组分别为bundleName、moduleName、abilityName、formName、formDimension。其中bundleName是app.json5配置文件标签中bundleName配置项、moduleName是module.json5配置文件标签中的name配置项、abilityName是abilities标签中的name配置项、formName是配置文件字段说明中的name配置项、formDimension对应的是配置文件

配置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 表示卡片的展示名称。主要在卡片管理页面显示,对应卡片预览下卡片管理页面中的"ArkTSCard",用于展示卡片信息,建议能够体现卡片的核心功能或用途。支持字符串或字符串资源索引,建议使用字符串资源索引方式声明,以支持完整多语言能力。字符串最小长度为1字节,最大长度为30字节。 字符串 否
description 表示卡片的描述。用于在卡片管理页面展示卡片功能描述,对应卡片预览下卡片管理页面中的"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 用于定义与显示窗口相关的配置。
说明:
该字段仅对JS卡片生效。
对象 可缺省,缺省值参考window标签表格。
isDefault 表示该卡片是否为默认卡片(在卡片中心内希望优先展示的卡片),每个应用有且只有一个默认卡片。
- true:默认卡片。
- false:非默认卡片。
说明:
应用上架时每个应用只允许配置一张默认卡片。
布尔值 否
colorMode(deprecated) 表示卡片的主题样式,取值范围如下:
- auto:跟随系统的颜色模式值选取主题。
- dark:深色主题。
- light:浅色主题。
说明:
1. 从API version 12开始支持该配置项,从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小时制,精确到分钟,例如:"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一一对应。智能穿戴卡片必须配置,当前仅支持在智能穿戴上使用。 字符串数组 可缺省,缺省值:[]。
formVisibleNotify 表示是否通知卡片提供方可见状态变化(仅对系统应用的卡片生效)。
- true:通知卡片提供方可见状态变化。
- false:不通知卡片提供方可见状态变化。
布尔类型 可缺省,缺省值为false。
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',resizeable配置为true,supportDimension为2*2。卡片B的groupId配置为'1',resizeable配置为true,supportDimension为2*4。那么支持卡片A、B之间调整大小。
示例二:当supportDimension存在多个,resizable设置为true时,优先在同一张卡片之间调整大小。卡片A的resizeable配置为true,supportDimension为2*2、2*4,支持卡片A的两个尺寸之间调整大小。
示例三:卡片A的groupId配置为'1',resizeable配置为true,supportDimension为1*2。卡片B的groupId配置为'1',resizeable配置为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",
         "disabledDesktopBehaviors": [
           "SWIPE_DESKTOP",
           "PULL_DOWN_SEARCH",
           "LONG_CLICK",
           "DRAG"
         ],
         "triggerTypes": [
           "shake"
         ]
      }          
    }
  ]
}

standby标签

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

属性名称 含义 数据类型 是否可缺省
isSupported 标识卡片是否支持在待机屏保显示界面展示。
- true:表示卡片支持在待机屏保显示界面展示。
- false:表示卡片不支持在待机屏保显示界面展示。
布尔值 可缺省,缺省值为true。
isAdapted 标识卡片是否针对待机屏保显示界面做过适配,配置成true,会把卡片布局组件中backgroudimage移除。
- 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": []
    }
  ]
}

本文来自 OpenHarmony 文档贡献者,按 CC BY 4.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
OpenHarmony 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY 4.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。