用户指南取消(C)

创建自定义 HTML5 组件

搜索

上次更新日期： 2023年5月24日

Animate

打开应用程序

阅读本文可了解如何创建 HTML5 Canvas 自定义组件。

Animate 提供一组默认组件。但这些组件对于您的项目来说是不够的。本主题可帮助您了解如何在 Animate 中创建自定义的 HTML5 组件。

组件的定义包括三个主要部分：

元数据：提供组件的有关信息，如显示名称、版本、可配置属性、图标等等。这些都放在一个名为 components.js 的文件中。可以将组件编组到一个类别中，而此文件允许您为一个类别中的所有组件提供元数据。
源：提供实际组件源的有关信息。这是在您预览或发布使用组件的影片时，在运行时嵌入的。
资源：提供运行时依赖的有关信息，如 JavaScript 库或 CSS 或运行时资源和图标。这些资源可以用在 Animate 创作环境中。

组件定义还具有本地化相关的资源。

Animate 将检查以下文件夹中是否包含任何自定义 HTML5 组件并在启动时进行加载：

• Windows：

<AppData>/Local/Adobe/Adobe Animate 2017/en_US/Configuration/HTML5Components

• MAC：

~/Library/Application Support/Adobe/Animate 2017/en_US/Configuration/HTML5Components/

上面的文件夹路径仅适用于美国英语版本。如果您使用的是任何其他语言的 Animate，请查找您的语言对应的文件夹名称来替换 en_US。

对每个其中包含文件 components.js 的文件夹，Animate 会创建一个类别，并将所有组件加载到其中。

组件元数据

组件的元数据放在一个名为 components.js 的文件中，该文件位于 HTML5Components 目录中一个单独的文件夹内。

Components.js

是一个 JSON 文件，它包含以下部分：

Category（类别）：该组组件在组件面板中的名称，可予以本地化。
Components（组件）：是一个元素组，其中每项包含一个组件的元数据。上例仅包含一个元素。元数据包含以下部分：

名称	必需	描述
ClassName	是	源文件中指定的组件的类名称。此类名称支持单级别命名空间。例如，Video。
Version	否	组件的版本号。它用于以后组件的升级。不过，流并不在此时定义。
Source	是	组件的主源文件的相对路径。下一部分提供有关源文件所含内容的更多详细信息。
Icon	否	组件图标的相对路径。在使用组件名称为组件创建任何实例时，组件面板中和舞台上会使用此图标。如果未提供，将使用默认图标。您可以指定要加载图标（通常为 32x32）的 png 名称。或者，如果希望对浅色 UI 和深色 UI 使用不同的图标，则可以提供两个 .png，并使用以下命名约定： custom_icon_N.png – 深色 UI 图标 custom_icon_D.png – 浅色 UI 图标只需指定名称 custom_icon 作为此字段的值。系统会根据当前的用户设置自动追加后缀。
Dimensions	否	组件实例的默认大小。每当用户将组件从组件面板拖放到舞台时，就会创建一个新的实例。此字段指定组件实例的默认初始大小。其值应该是一个 [宽度, 高度] 数组。如果未指定任何值，Animate 会挑选一个默认大小。此外，Animate 会将大小限制在 [2,2] 到 [1000,1000] 范围内。
Dependencies	否	组件的相关项集。这是一组相关项，其中每一条目都提供本地源的相对路径（键为 src）和 CDN 路径（键为 cdn）。CDN 路径不是必需的。此路径用于当您在发布设置中使用托管库的时候。如果不是这样，将在您预览或发布时使用本地源。请注意上例 (video) 中使用的相对路径。它从上面一级加载相关项，从而允许跨多个组件集共享某些相关项。
Properties	是	这是一组属性。在舞台上创建此组件的任何实例时，此处配置的属性集将自动显示在 PI 中。此组件的用户可以在 Animate 中配置这些属性，配置好的属性将在运行时组件实例化期间可用。每个属性条目包含以下键： name：此属性在 PI 中显示的名称。这应该是一个易记的名称。可予以本地化。 variable：对此属性使用的内部名称。所配置的值将在运行时随此变量名称提供。有关此键的更多信息将在后面的部分中加以介绍。 Type：指定属性的类型。Animate 支持以下类型： Boolean（布尔值）- PI 中的复选框 Number（数值）- PI 中的数值框 String（字符串） - PI 中的文本框 List（列表） - 允许用户配置一组值。 Collection（集合）- 允许用户配置一个 <键, 值> 对列表。（请参阅“组合框”） File Path（文件路径）- 允许用户浏览和选择任一本地文件。字符串值在运行时提供。此文件会自动复制在 assets 文件夹下发布的输出中，相对路径在运行时可用。 Image Path（图像路径）- 允许用户浏览和选择任一图像。此文件会自动复制在所配置的图像文件夹下发布的输出中，相对路径在运行时可用。 Video Content Path（视频内容路径）- 允许用户浏览和选择任一 Web 格式视频源（mp4、 ogg 、 ogv 、 webm ）。配置的资源会复制到 video 文件夹下发布的输出中。 Color（颜色）- PI 中的拾色器 Default：属性的默认值。默认类型应与属性的类型相同。

组件源

每个组件都应有一个与之相关联用于提供代码的源文件，用于处理以下过程：

运行时创建组件实例并赋予配置的各个属性值
附加到和脱离开 DOM
在每帧中更新属性

文件 anwidget.js 中提供了一个基类和一个实用程序函数，使得自定义组件的开发更为方便。以后将会增强此接口的功能，但会向后兼容。目前仅支持基于 DOM 的组件，但会扩展对基于 Canvas 组件的支持。目前仅支持小部件 (widget)，但会增强框架功能以支持附加行为（非 UI 组件）。

文件 anwidget.js 位于初始文件夹的 HTML5Components/sdk 文件夹下。它为自定义组件提供一个基类 AnWidget 和一个用来注册自定义组件的实用程序方法 $.anwidget(<className>, {Object Prototype})。当前实现使用的是 jQuery，因此每当使用小部件提供的服务时，都将 jQuery 始终作为一个相关项来添加。但是，如果不想对 jQuery 添加隐式相关项，可能需要实现一个不带 jQuery 的组件类，它与小部件提供相同的接口。

html 默认包含下面几部分（不包括预加载器 div）：

请注意上图显示了元素在 DOM 中的添加顺序。因此 dom_overlay_container div 显示在画布的上面。

不要更改 dom_overlay_container div 的 ID，因为在我们的第一个版本中，有几个功能（如代码片段）依赖此 ID。

如上图所示，dom_overlay_container div 叠加在画布的上面。要确保鼠标事件也能够正确传播到下面的画布，我们对此 div 使用 CSS 属性 {pointer-events: none}，以便鼠标事件能够传播到下面的画布。您的项目中在 Animate 中配置的所有组件实例都会被实例化并作为子项附加到此 dom_overlay_container div。组件实例的相对顺序在运行时将保持不变，但当前所有组件实例始终显示为叠加。我们将在运行时对所有组件实例设置 {pointer-events: all}，以便它们也能接收鼠标事件。

组件的生命周期

组件实例是在为容器构造 DOM 时创建的。
之后当播放头到达使用该组件实例的帧时，该实例会被附加到 DOM。之后该实例附加一个 update 处理函数，该函数会在运行时每一次 tick 被调用。组件此时还会触发一个 attached 事件，且对父元素使用以下事件数据 {id: id_of_the_instance}。
每次 update 回调，都将更新属性。在 tick 处理函数期间，所有的属性更新会被缓存并应用一次。当前不支持自定义属性补间。仅更新变换和可见性等基本属性。
当播放头到达删除组件实例的帧时，我们会将它与 DOM 脱离开。此时会对父元素触发 detached 事件。

基类名为 $.AnWidget，它提供下列覆盖：

名称	必需	描述
getCreateOptions()	否	返回想要在组件实例化期间应用组件的任何选项。典型的覆盖通常是使用 this 并利用 _widgetID 全局变量为每个实例分配一个唯一的 ID。下一部分中的示例将更为清楚地描述其使用方式。
getCreateString()	是	返回 DOM 实例创建字符串。此字符串将传递给 jQuery 以创建实际的 DOM 元素，以后该元素会附加到基本 DOM。例如，对于图像组件，应返回“<image>”。元素在运行时创建，且对 jQuery 包装器的引用存储在组件实例中，如下所示： this._element = $(this.getCreateElement()) // this._element – 用于下层创建的 DOM 元素的 jQuery 包装器。我们还可以创建复合元素；详细信息将在示例部分中提供。
getProperties()	否	返回一组可配置的 CSS 属性名。通常，它们与在 components.json 中配置的所有属性相匹配例如，对于视频组件，此属性组包含以下条目： ["left", "top", "width", "height", "position", "transform-origin", "transform"]
getAttributes()	否	返回一组可配置的特性。通常，它们与允许您在 components.json 中配置的所有特性相匹配例如，对于视频组件，此属性组包含以下条目： ["id", "src", "controls", "autoplay", "loop", "class"]
attach(parent)	否	每当组件实例即将附加到父 DOM 元素时，调用此函数。默认实现完成以下工作（以及更多工作）： //将元素追加到父 DOM $(parent).append(this._element); //将引用存储在 this._$this this._$this = $(this._element); //调用强制更新以应用所有属性 this.update(true); this._attached = true; //对父项触发 attached 事件 $(parent).trigger("attached", this.getEventData("attached")) 无需覆盖此函数。但对于复合元素，可能需要覆盖。详细信息将在示例部分中提供。注意：可以使用 this._superApply(arguments) 调用任何覆盖中的任何基类方法。
detach()	否	每当组件实例即将脱离父 DOM 时，调用此函数。默认实现完成以下工作： //删除 DOM 中的元素 this._$this.remove(); //对父项触发 detached 事件 $(parent).trigger("detached", this.getEventData("detached"));
setProperty(k,v)	否	此函数用于为实例设置任一属性。在调用 update() 期间，对每一帧每一使用过的属性，会立即缓存并应用这些更改。
update(force)	否	当组件是 DOM 的一部分且可见时，对每一帧调用此函数。默认实现（或 force 参数为 true 时）应用所有已经发生变化的 CSS 属性和特性。
show()	否	显示元素实例。通常无需覆盖此方法，但对复合元素可能需要。
hide()	否	隐藏元素实例。通常无需覆盖此方法，但对复合元素可能需要。
getEventData(e)	否	返回名称带有 e 的事件的自定义数据。默认实现是为 attached 和 detached 事件传递数据 {id: instance_id}。
destroy()	否	组件实例脱离 DOM 时释放内存。通常无需覆盖此方法。
applyProperties(e)	否	辅助 API，用于对 jQuery 包装器 e 应用 CSS 属性。
applyAttributes(e)	否	辅助 API，用于对 jQuery 包装器 e 应用特性。

本地化

类别字符串、组件显示名称和属性名称是可以本地化的。在 components 文件夹下的 locale 文件夹中创建一个名为 strings.json 的文件。对所有要本地化的字符串提供键值对并在 components.js 中使用这些键。对于其他语言，需要在 locale 文件夹下相应的文件夹中提供字符串。

打包和分发 HTML5 自定义组件

Animate 开发人员或设计人员通过提供即用型打包组件，让动画制作人员无需编码即可安装和使用组件。以前，动画制作人员必须了解文件结构、编程、将文件手动移到特定文件夹，才能激活 HTML5 扩展。

先决条件

开发人员创建的任何组件。单击此处获取关于创建组件的说明。
CC Extensions 签名工具包。

打包组件之前，创建一个含组件的来源和目标路径元数据的 MXI 文件。例如，

<file source=&quot;jquery-ui-1.12.0&quot; destination=&quot;$FLASH\HTML5Components\jQueryUI\&quot; file-type=&quot;ordinary&quot; />

启用扩展实用程序需要该来源和目标文件信息，以便准确安装您的组件。

打包组件

要打包 HTML5 自定义组件，请执行以下步骤：

要创建 MXI 文件，请输入与示例类似的内容文本编辑器输入 abc.mxi 文件之类的内容，然后用 MXI 扩展名保存。

下载

获取文件
下载示例 abc.mxi 文件。
将您的 MXI 组件文件和其他相关文件添加到文件夹。
使用 CC Extensions 签名工具 (ZXPSignCmd.exe) 创建 ZXP 扩展压缩文件。使用 ZXP 签名命令工具中的以下命令可创建 ZXP 文件：

1. 使用 -selfSignedCert 选项创建一个自签名证书。

如果已经有证书，可以跳过此步骤。
```
ZXPSignCmd -selfSignedCert US NY MyCompany MyCommonName password FileName.p12
```
此时将在当前文件夹中生成 FileName.p12 文件。

2. 使用以下命令签署扩展：
```
ZXPSignCmd -sign projectName projectName.zxp FileName.p12 password
```
projectName 是扩展项目的名称。在当前文件夹中，将生成一个名为 projectName.zxp 的文件。