HarmonyOS：创建ArkTS卡片

一、ArkTS卡片类型

ArkTS卡片分为动态卡片与静态卡片两种类型。

与动态卡片相比，静态卡片整体的运行框架和渲染流程和动态卡片是一致的
主要区别在于，卡片渲染服务将卡片内容渲染完毕后，卡片使用方会使用最后一帧渲染的数据作为静态图片显示，其次卡片渲染服务中的卡片实例会释放该卡片的所有运行资源以节省内存。因此频繁的刷新会导致静态卡片运行时资源不断的创建和销毁，增加卡片功耗。

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卡片，具体的操作方式如下。

1. 右键新建卡片
   

说明
在API 10及以上 Stage模型的工程中，在Service Widget菜单可直接选择创建动态或静态服务卡片。创建服务卡片后，也可以在卡片的form_config.json配置文件中，通过isDynamic参数修改卡片类型：isDynamic置空或赋值为“true”，则该卡片为动态卡片；isDynamic赋值为"false"，则该卡片为静态卡片。

2. 根据实际业务场景，选择一个卡片模板
   

3. 在选择卡片的开发语言类型（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配置文件

isDynamic标签
此标签标识卡片是否为动态卡片（仅针对ArkTS卡片生效）。

window标签
此标签标识window对象的内部结构说明。

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

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

   {
     "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"
      ]
    }
  ]
}