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

创建ArkTS卡片

· 52CE 我爱测

ArkTS卡片有两种创建卡片包的方式。开发者在开发过程中任选其一即可。 方式一:卡片和应用共包方式,创建步骤请参考共包方式创建卡片,此时卡片UI和应用代码在一个module内,最终编译产物也在同一个HAP包内。 方式二:独立卡片包方式,创建步骤请参考独立包方式创建卡片,此时卡片UI和应用代码在不同module内,最终编译产物分为卡片包和应用包。从API version 20开始支持。 ArkTS卡片创建完成,在开发卡片过程中,支持对卡片进行实时预览。 ## 方式一:共包方式创建卡片 ### 创建步骤 **1. 新建工程** 在DevEco Studio中,选择创建Application或Atomic Service工程,这两种都支持

创建ArkTS卡片

ArkTS卡片有两种创建卡片包的方式。开发者在开发过程中任选其一即可。
方式一:卡片和应用共包方式,创建步骤请参考共包方式创建卡片,此时卡片UI和应用代码在一个module内,最终编译产物也在同一个HAP包内。
方式二:独立卡片包方式,创建步骤请参考独立包方式创建卡片,此时卡片UI和应用代码在不同module内,最终编译产物分为卡片包和应用包。从API version 20开始支持。
ArkTS卡片创建完成,在开发卡片过程中,支持对卡片进行实时预览。

方式一:共包方式创建卡片

创建步骤

1. 新建工程
在DevEco Studio中,选择创建Application或Atomic Service工程,这两种都支持创建卡片。工程创建指导具体请参考创建一个新的工程。

[图示请参阅官方原文]

说明:

基于不同版本的DevEco Studio,请以实际界面为准。

2. 新建卡片
在已有的应用工程中,右键新建ArkTS卡片,具体操作如下。

  • 选中entry目录单击右键选择【New】->【Service Widget】->【Dynamic Widget】。在API 10及以上 Stage模型的工程中,开发者可通过Service Widget菜单直接选择创建动态卡片(Dynamic Widget)或静态卡片(Static Widget)。创建卡片后,也可在卡片的form_config.json配置文件中,通过isDynamic参数修改卡片类型:isDynamic置空或赋值为“true”,则该卡片为动态卡片;isDynamic赋值为"false",则该卡片为静态卡片。静态卡片和动态卡片切换之后用户交互实现也需要修改,具体参考ArkTS卡片概述中的动态卡片和静态卡片。
    [图示请参阅官方原文]

  • 选择模板后,点击【Next】。
    [图示请参阅官方原文]

  • 在选择卡片的开发语言类型(Language)时,选择ArkTS选项。选择卡片支持的外观规格(Support dimension)时,选择期望的卡片尺寸,然后选择默认的外观规格(Default dimension),最后点击“Finish”,即可完成ArkTS卡片创建。详细的卡片外观规格可参考form_config.json配置文件,后续也可以在form_config.json配置文件中修改卡片规格。
    [图示请参阅官方原文]

    建议根据实际使用场景命名卡片名称,ArkTS卡片创建完成后,工程中会新增如下卡片相关文件:卡片生命周期管理文件(EntryFormAbility.ets)、卡片页面文件(WidgetCard.ets)和卡片配置文件(form_config.json)。填写卡片配置之后点击【Finish】。
    [图示请参阅官方原文]

工程结构介绍

图1 ArkTS卡片工程目录、相关模块
[图示请参阅官方原文]

  • FormExtensionAbility:卡片扩展模块,提供卡片创建、销毁、刷新等生命周期回调。

  • FormExtensionContext:FormExtensionAbility的上下文环境,提供FormExtensionAbility具有的接口和能力。

  • formProvider:提供了获取卡片信息、更新卡片、设置卡片更新时间等能力。

  • formInfo:提供了卡片信息和状态等相关类型和枚举。

  • formBindingData:提供卡片数据绑定的能力,包括FormBindingData对象的创建、相关信息的描述。

  • 页面布局(WidgetCard.ets):基于ArkUI提供卡片UI开发能力。

  • 卡片配置:包含FormExtensionAbility的配置和卡片的配置。

    • 在module.json5配置文件中的extensionAbilities标签下,配置FormExtensionAbility相关信息。
    • 在resources/base/profile/目录下的form_config.json配置文件中,配置卡片(WidgetCard.ets)相关信息。

方式二:独立包方式创建卡片

创建步骤

1. 新建工程
在DevEco Studio中,选择创建Application或Atomic Service工程,这两种都支持创建卡片。工程创建指导具体请参考创建一个新的工程。

[图示请参阅官方原文]

说明:

基于不同版本的DevEco Studio,请以实际界面为准。

2. 新建卡片

  • 选中entry目录单击右键选择【New】->【Service Widget】->【Dynamic Widget(Standalone)】。在Service Widget菜单可直接选择创建独立包的动态卡片(Dynamic Widget(standalone))或静态卡片(Static Widget(standalone))。创建服务卡片后,也可以在卡片的form_config.json配置文件中,通过isDynamic参数修改卡片类型:isDynamic置空或赋值为“true”,则该卡片为动态卡片;isDynamic赋值为"false",则该卡片为静态卡片。静态卡片和动态卡片切换之后用户交互实现也需要修改,具体参考ArkTS卡片概述中的动态卡片和静态卡片。
    [图示请参阅官方原文]
  • 选择模板后,点击【Next】。
    [图示请参阅官方原文]
  • 填写卡片配置之后点击【Finish】。卡片创建成功后,entry包中包含应用和卡片后端能力;library包中包含卡片UI侧能力。entry模块下的module.json5配置文件中的formWidgetModule字段需关联library模块,library模块下的module.json5配置文件中的formExtensionModule字段需关联entry模块,以实现卡片包和应用包相互关联。创建完成后,会自动生成配置文件并配置,后续也可以按照卡片配置文件修改配置。
    [图示请参阅官方原文]

工程结构介绍

独立卡片包与卡片共包方式创建卡片,仅工程结构存在差异,生成的文件是一致的,各文件具体内容请参考共包方式工程结构介绍。
图2 独立卡片包工程目录。
[图示请参阅官方原文]

说明:

独立卡片包中应用包和卡片包为2个独立模块,因此需要关注同时安装的应用包和卡片包版本号一致。

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

资料来源与适用范围

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

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

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