名称
上次更新日期：
2023年5月24日
阅读本文可了解如何创建 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
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 中配置这些属性，配置好的属性将在运行时组件实例化期间可用。 每个属性条目包含以下键：
|
组件源
每个组件都应有一个关联的源文件，该文件提供了用于处理以下内容的代码：
- 运行时创建组件实例并赋予配置的各个属性值
- 附加到和脱离开 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，它提供下列覆盖：
Name |
必需 |
说明 |
|---|---|---|
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="jquery-ui-1.12.0" destination="$FLASH\HTML5Components\jQueryUI\" file-type="ordinary" />
启用扩展实用程序需要该来源和目标文件信息，以便准确安装您的组件。
打包组件
要打包 HTML5 自定义组件，请执行以下步骤：
将您的 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 的文件。
分发组件
您可以向任何 Animate 用户分发此 projectName.zxp 打包组件文件。
Adobe 建议您通过 Adobe 插件网站分发产品。 您可以公开（免费或付费）或私下分发加载项。
安装分发的组件
Animate 设计人员或开发人员可以使用“管理扩展”实用程序来安装分发的 ZXP 文件组件。
