HarmonyOS：创建ArkTS卡片
一、ArkTS卡片类型
ArkTS卡片分为动态卡片与静态卡片两种类型。
与动态卡片相比，静态卡片整体的运行框架和渲染流程和动态卡片是一致的
主要区别在于，卡片渲染服务将卡片内容渲染完毕后，卡片使用方会使用最后一帧渲染的数据作为静态图片显示，其次卡片渲染服务中的卡片实例会释放该卡片的所有运行资源以节省内存。因此频繁的刷新会导致静态卡片运行时资源不断的创建和销毁，增加卡片功耗。
| 卡片类型 | 支持的能力 | 适用场景 | 优缺点 |
|---|---|---|---|
| 静态卡片 | 仅支持UI组件和布局能力。 | 主要用于展示静态信息（UI相对固定），仅可以通过FormLink组件跳转到指定的UIAbility。 | 功能简单但可以有效控制内存开销。 |
| 动态卡片 | 除了支持UI组件和布局能力，还支持通用事件能力和自定义动效能力。 | 用于有复杂业务逻辑和交互的场景。例如：卡片页面图片的刷新、卡片内容的刷新等。 | 功能丰富但内存开销较大。 |
1.1 动态卡片
ArkTS卡片中提供了postCardAction接口用于动态卡片内部和提供方应用间的交互，当前支持router、message和call三种类型的事件，仅在卡片控件的点击事件中可以调用。
动态卡片事件实现原理
动态卡片事件的主要使用场景如下：
- router事件：可以使用router事件跳转到指定UIAbility，以完成点击卡片跳转应用内页面的交互功能。对于非系统应用仅支持跳转到自己应用内的UIAbility。
- call事件：可以使用call事件拉起指定UIAbility到后台，再通过UIAbility申请对应后台长时任务完成音乐播放等功能。
- message事件：可以使用message拉起FormExtensionAbility，通过onFormEvent接口回调通知，以完成卡片内控件点击消息传递，从而更新卡片内容。
1.2 静态卡片
ArkTS卡片提供FormLink静态卡片交互组件，用于静态卡片内部和提供方应用间的交互，当前支持router、message和call三种类型的事件。
二、创建卡片当前有两种入口：
- 创建工程时，选择Application，可以在创建工程后右键新建卡片。
- 创建工程时，选择Atomic Service（元服务），也可以在创建工程后右键新建卡片。
说明
基于不同版本的DevEco Studio，请以实际界面为准。
在已有的应用工程中，可以通过右键新建ArkTS卡片，具体的操作方式如下。
- 右键新建卡片
说明
在API 10及以上 Stage模型的工程中，在Service Widget菜单可直接选择创建动态或静态服务卡片。创建服务卡片后，也可以在卡片的form_config.json配置文件中，通过isDynamic参数修改卡片类型：isDynamic置空或赋值为“true”，则该卡片为动态卡片；isDynamic赋值为"false"，则该卡片为静态卡片。
- 根据实际业务场景，选择一个卡片模板
- 在选择卡片的开发语言类型（Language）时，选择ArkTS选项。选择卡片支持的外观规格（Support dimension）时，选择期望的卡片尺寸，再选择默认的外观规格（Default dimension）。详细的卡片外观规格，可参考form_config.json配置文件，后续也可以在form_config.json配置文件中修改卡片规格。然后单击“Finish”，即可完成ArkTS卡片创建。
建议根据实际使用场景命名卡片名称，ArkTS卡片创建完成后，工程中会新增如下卡片相关文件：卡片生命周期管理文件（EntryFormAbility.ets）、卡片页面文件（WidgetCard.ets）和卡片配置文件（form_config.json）。
三、工程结构介绍
ArkTS卡片工程目录、相关模块
- FormExtensionAbility：卡片扩展模块，提供卡片创建、销毁、刷新等生命周期回调。
- FormExtensionContext：FormExtensionAbility的上下文环境，提供FormExtensionAbility具有的接口和能力。
- formProvider：提供了获取卡片信息、更新卡片、设置卡片更新时间等能力。
- formInfo：提供了卡片信息和状态等相关类型和枚举。
- formBindingData：提供卡片数据绑定的能力，包括FormBindingData对象的创建、相关信息的描述。
- 页面布局（WidgetCard.ets）：基于ArkUI提供卡片UI开发能力。
- ArkTS卡片通用能力：提供了能在ArkTS卡片中使用的组件、属性和API。
- ArkTS卡片特有能力：postCardAction用于卡片内部和提供方应用间的交互，仅在卡片中可以调用。
- 卡片配置：包含FormExtensionAbility的配置和卡片的配置。
- 在module.json5配置文件中的extensionAbilities标签下，配置FormExtensionAbility相关信息。
- 在resources/base/profile/目录下的form_config.json配置文件中，配置卡片（WidgetCard.ets）相关信息。
四、配置ArkTS卡片的配置文件
4.1 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"}]}]}
}
4.2 卡片配置
在上述FormExtensionAbility的元信息metadata配置项中，可以指定卡片具体配置信息的资源索引。例如当resource指定为$profile:form_config时，会使用开发视图的resources/base/profile/目录下的form_config.json作为卡片profile配置文件。在创建卡片时会自动生成form_config.json配置文件。
4.2.1 配置文件字段说明
卡片form_config.json配置文件
| 属性名称 | 含义 | 数据类型 | 是否可缺省 |
|---|---|---|---|
| forms | 表示应用的全部卡片配置信息。 最多支持配置16个卡片，若超过16个，则保留配置的前16个。 | 数组 | 否 |
| name | 表示卡片的名称，字符串最大长度为127字节。 | 字符串 | 否 |
| displayName | 表示卡片的展示名称。主要在卡片管理页面显示，用于展示卡片信息，建议能够体现卡片的核心功能或用途。支持字符串或字符串资源索引，建议使用字符串资源索引方式声明，以支持完整多语言能力。字符串最小长度为1字节，最大长度为30字节。 | 字符串 | 否 |
| description | 表示卡片的描述。用于在卡片管理页面展示卡片功能描述。支持字符串或字符串资源索引，建议使用字符串资源索引方式声明，以支持完整多语言能力。字符串最大长度为255字节。 | 字符串 | 可缺省，缺省为空。 |
| src | 表示卡片对应的UI代码的完整路径。当为ArkTS卡片时，完整路径需要包含卡片文件的后缀， 如：“./ets/widget/pages/WidgetCard.ets”。当为JS卡片时，完整路径无需包含卡片文件的后缀， 如：“./js/widget/pages/WidgetCard” | 字符串 | 否 |
| uiSyntax | 表示该卡片的类型，当前支持如下两种类型： - arkts：当前卡片为ArkTS卡片。 - hml：当前卡片为JS卡片。 | 字符串 | 可缺省，缺省值为“hml”。 |
| window | 用于定义与显示窗口相关的配置。 说明： 该字段仅对JS卡片生效。 | 对象 | 可缺省，缺省值见表2。 |
| isDefault | 表示该卡片是否为默认卡片，每个UIAbility有且只有一个默认卡片。 - true：默认卡片。 - false：非默认卡片。 | 布尔值 | 否 |
| colorMode | 表示卡片的主题样式，取值范围如下： - auto：跟随系统的颜色模式值选取主题。 - dark：深色主题。 - light：浅色主题。 说明： 从API version 20开始，该接口废弃，卡片主题样式统一跟随系统的颜色模式。 | 字符串 | 可缺省，缺省值为“auto”。 |
| supportDimensions | 表示卡片支持的外观规格，取值范围： - 1 * 2：表示1行2列的二宫格。 - 2 * 2：表示2行2列的四宫格。 - 2 * 4：表示2行4列的八宫格。 - 4 * 4：表示4行4列的十六宫格。 - 6 * 4：表示6行4列的二十四宫格。 | 字符串数组 | 否 |
| 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数组标签。 | 对象 | 可缺省，缺省值为空。 |
| isDynamic | 表示此卡片是否为动态卡片（仅针对ArkTS卡片生效）。 - true：为动态卡片 。 - false：为静态卡片。 | 布尔类型 | 可缺省，缺省值为true |
| fontScaleFollowSystem | 表示卡片使用方设置此卡片的字体是否支持跟随系统变化。 - true：支持跟随系统字体大小变化 。 - false：不支持跟随系统字体大小变化。 | 布尔类型 | 可缺省，缺省值为true。 |
| supportShapes | 表示卡片的显示形状，取值范围如下： - rect：表示矩形卡片。 - circle：表示圆形卡片。 | 字符串数组 | 可缺省，缺省值为“rect”。 |
| previewImages | 表示卡片预览图, 与配置项supportDimensions一一对应。 | 字符串 | 可缺省，智能穿戴卡片必须配置，当前仅支持在智能穿戴上使用。 |
| enableBlurBackground | 表示卡片是否使用模糊背板。 - true：开启模糊背板。 - false：关闭模糊背板。 | 布尔类型 | 可缺省，缺省值为false。 |
| renderingMode | 表示卡片的渲染模式，取值范围如下： - autoColor：自动模式，锁屏卡片中心与桌面卡片中心/卡片管理内都可以显示的卡片。 - fullColor：全色模式，桌面卡片中心/卡片管理内可以显示的卡片。 - singleColor：单色模式，锁屏卡片中心内可以显示的卡片。 | 字符串 | 可缺省，缺省值为“fullColor”。 |
| multiScheduledUpdateTime | 表示卡片的多定点刷新的时刻，作为单点刷新的一个附加参数，采用24小时制，精确到分钟，多个时间用英文逗号分隔，最多写24个时间。 说明： multiScheduledUpdateTime需要配合scheduledUpdateTime使用。 | 字符串 | 可缺省，缺省时不进行多定点刷新。 |
| conditionUpdate | 表示卡片的支持的条件刷新（仅对系统应用的ArkTS卡片生效）。取值范围如下： - network：表示支持网络刷新。 | 字符串 | 可缺省，缺省值为空字符串。 |
| funInteractionParams | 趣味交互类型互动卡片扩展字段。 | 对象 | 可缺省，缺省为空。funInteractionParams 和 sceneAnimationParams 同时配置时识别为趣味交互类型互动卡片。 |
| sceneAnimationParams | 场景动效类型互动卡片扩展字段。 | 对象 | 可缺省，缺省为空。funInteractionParams 和 sceneAnimationParams 同时配置时识别为趣味交互类型互动卡片。 |
isDynamic标签
此标签标识卡片是否为动态卡片（仅针对ArkTS卡片生效）。
| 卡片类型 | 支持的能力 | 适用场景 | 优缺点 |
|---|---|---|---|
| 静态卡片 | 仅支持UI组件和布局能力。 | 主要用于展示静态信息（UI相对固定），仅可以通过FormLink组件跳转到指定的UIAbility。 | 功能简单但可以有效控制内存开销。 |
| 动态卡片 | 除了支持UI组件和布局能力，还支持通用事件能力和自定义动效能力。 | 用于有复杂业务逻辑和交互的场景。例如：卡片页面图片的刷新、卡片内容的刷新等。 | 功能丰富但内存开销较大。 |
window标签
此标签标识window对象的内部结构说明。
| 属性名称 | 含义 | 数据类型 | 是否可缺省 |
|---|---|---|---|
| designWidth | 标识页面设计基准宽度。以此为基准，根据实际设备宽度来缩放元素大小。 | 数值 | 可缺省，缺省值为720px。 |
| autoDesignWidth | 标识页面设计基准宽度是否自动计算。当配置为true时，designWidth将会被忽略，设计基准宽度由设备宽度与屏幕密度计算得出。 | 布尔值 | 可缺省，缺省值为false。 |
funInteractionParams标签
此标签标识趣味交互类型互动卡片配置。funInteractionParams 和 sceneAnimationParams 同时配置时识别为趣味交互类型互动卡片。
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| abilityName | 字符串 | 否 | 趣味交互场景LiveFormExtensionAbility名称，默认为空。 |
| targetBundleName | 字符串 | 是 | 趣味交互场景主包包名。 |
| subBundleName | 字符串 | 否 | 趣味交互场景独立分包名，默认为空。 |
| keepStateDuration | 数值 | 否 | 趣味交互场景无交互时，激活态保持时长。默认值为10000，单位ms。取值为[0,10000]的整数，超过取值范围则取默认值10000。 |
sceneAnimationParams标签
此标签标识场景动效类型互动卡片配置。funInteractionParams 和 sceneAnimationParams 同时配置时识别为趣味交互类型互动卡片。
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| abilityName | 字符串 | 是 | 场景动效 extensionAbility 名称。 |
{"forms": [{// ..."sceneAnimationParams": {"abilityName": "MyLiveFormExtensionAbility"} }]}
配置文件示例
{"forms": [{"name": "demoCard","displayName": "$string:demoCard_display_name","description": "$string:demoCard_desc","src": "./ets/widget/pages/DemoCardWidget.ets","uiSyntax": "arkts","window": {"designWidth": 720,"autoDesignWidth": true},"colorMode": "auto","isDynamic": true,"isDefault": true,"updateEnabled": false,"scheduledUpdateTime": "10:30","updateDuration": 1,"defaultDimension": "2*2","supportDimensions": ["1*2","2*2"]}]
}