本文同步发表于我的微信公众号，微信搜索 程语新视界 即可关注，每个工作日都有文章更新

ArkTS卡片主要分两种类型：

• 动态卡片：支持数据更新和用户交互，需要卡片扩展模块提供后端能力

• 静态卡片：仅展示静态内容，不支持数据刷新和交互事件

卡片类型可通过配置文件中的isDynamic参数进行设置。

一、创建ArkTS卡片的两种方式

ArkTS卡片提供两种创建卡片包的方式，可根据项目需求任选其一。

方式一：卡片和应用共包方式

特点

• 卡片UI和应用代码位于同一个module内

• 最终编译产物在同一个HAP包中

• 适合卡片与应用紧密耦合的场景

创建步骤

1. 新建工程

• 打开DevEco Studio

• 选择创建Application或Atomic Service工程

• 两种工程类型都支持创建卡片

• 按照工程创建向导完成基础工程配置

2. 新建卡片

• 选中entry目录，右键单击

• 选择【New】→【Service Widget】→【Dynamic Widget】

• API 10及以上Stage模型工程可直接选择动态卡片或静态卡片

3. 卡片模板选择

• 选择适合的卡片模板

• 点击【Next】进入下一步

4. 卡片配置

• Language选择：选择ArkTS选项

• Support dimension：选择卡片支持的外观规格（尺寸）

  • 可选多种卡片尺寸

  • 选择默认外观规格

• 点击【Finish】完成创建

卡片类型切换说明

创建完成后，可通过form_config.json配置文件中的isDynamic参数修改卡片类型：

• isDynamic置空或赋值为"true"：动态卡片

• isDynamic赋值为"false"：静态卡片

注意：切换卡片类型后，用户交互实现也需要相应修改

工程结构介绍

创建完成后，工程中会新增以下卡片相关文件：

文件/目录	说明
EntryFormAbility.ets	卡片生命周期管理文件
WidgetCard.ets	卡片页面文件
form_config.json	卡片配置文件

核心模块

1. FormExtensionAbility（卡片扩展模块）

• 提供卡片创建、销毁、刷新等生命周期回调

• 卡片后端能力的核心实现

2. FormExtensionContext

• FormExtensionAbility的上下文环境

• 提供FormExtensionAbility具有的接口和能力

3. formProvider

• 获取卡片信息

• 更新卡片内容

• 设置卡片更新时间

4. formInfo

• 提供卡片信息和状态相关类型

• 包含卡片状态枚举定义

5. formBindingData

• 提供卡片数据绑定能力

• 创建FormBindingData对象

• 管理卡片数据相关信息

6. 页面布局（WidgetCard.ets）

• 基于ArkUI的卡片UI开发

• 支持ArkUI组件和属性

7. ArkTS卡片能力

• 通用能力：支持在卡片中使用的组件、属性和API

• 特有能力：postCardAction用于卡片内部和提供方应用间的交互（仅在卡片中可调用）

配置文件

1. module.json5配置

• 在extensionAbilities标签下配置FormExtensionAbility相关信息

• 注册卡片扩展能力

2. form_config.json配置

• 位于resources/base/profile/目录

• 配置卡片（WidgetCard.ets）相关信息

• 包括卡片名称、类型、尺寸等

方式二：独立卡片包方式

特点

• 卡片UI和应用代码位于不同module

• 最终编译产物分为卡片包和应用包

• 从API version 20开始支持

• 适合卡片与应用解耦、独立管理的场景

创建步骤

1. 新建工程

• 同样选择创建Application或Atomic Service工程

• 完成基础工程创建

2. 新建卡片

• 选中entry目录，右键单击

• 选择【New】→【Service Widget】→【Dynamic Widget(Standalone)】

• Service Widget菜单中可选择：

  • Dynamic Widget(standalone)：独立包动态卡片

  • Static Widget(standalone)：独立包静态卡片

3. 卡片模板选择

• 选择适合的卡片模板

• 点击【Next】进入下一步

4. 卡片配置

• 填写卡片配置信息

• 点击【Finish】完成创建

工程结构特点

创建成功后，项目结构如下：

entry模块（应用模块）

• 包含应用主功能

• 包含卡片后端能力

library模块（卡片模块）

• 包含卡片UI侧能力

• 独立管理卡片界面

模块关联配置

两个模块需要相互关联才能正常工作：

entry模块配置

• module.json5配置文件中的formWidgetModule字段

• 需关联library模块

library模块配置

• module.json5配置文件中的formExtensionModule字段

• 需关联entry模块

重要：创建完成后会自动生成并配置这些关联关系，后续也可手动修改

版本一致性要求

注意事项：

• 应用包和卡片包为2个独立模块

• 需要确保同时安装的应用包和卡片包版本号一致

• 版本不一致可能导致卡片加载失败

两种方式的对比

对比项	共包方式	独立包方式
模块结构	单module	多module
编译产物	单个HAP包	卡片包+应用包
API支持	全部版本	API 20+
耦合度	紧密耦合	松耦合
适用场景	卡片与应用强关联	卡片独立管理

实时预览功能

在开发卡片过程中，DevEco Studio支持对卡片进行实时预览：

• 即时查看卡片UI效果

• 快速调整布局和样式

• 验证卡片功能实现

卡片配置文件

form_config.json主要配置字段

{
  "name": "卡片名称",
  "description": "卡片描述",
  "src": "./ets/widget/pages/WidgetCard.ets",
  "window": {
    "designWidth": 720,
    "autoDesignWidth": true
  },
  "isDynamic": true,  // true:动态卡片 false:静态卡片
  "formConfigAbility": "ability://xxxx",
  "forms": [
    {
      "name": "卡片实例名称",
      "displayName": "显示名称",
      "description": "实例描述",
      "src": "./ets/widget/pages/WidgetCard.ets",
      "window": {
        "designWidth": 720,
        "autoDesignWidth": true
      },
      "colorMode": "auto",
      "isDefault": true,
      "updateEnabled": true,
      "scheduledUpdateTime": "10:30",
      "updateDuration": 1,
      "defaultDimension": "2*2",
      "supportDimensions": ["2*2", "2*4", "4*4"]
    }
  ]
}

建议

1. 选择合适的创建方式

   • 卡片功能简单且与应用绑定：选择共包方式

   • 卡片功能复杂需独立维护：选择独立包方式

2. 合理规划卡片类型

   • 需要数据更新：选择动态卡片

   • 仅展示静态信息：选择静态卡片（性能更优）

3. 版本兼容

   • 独立包方式要求API 20+

   • 确保应用包和卡片包版本一致

4. 实时预览

   • 开发过程中多使用预览功能

   • 及时调整UI布局

ArkTS卡片创建提供了两种方式，可以根据项目需求选择：

• 共包方式适合快速开发、卡片与应用紧密集成的场景

• 独立包方式适合卡片独立管理、需要解耦的场景