用户指南 取消(C)

创建自定义 HTML5 组件

 

阅读本文可了解如何创建 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 中配置这些属性,配置好的属性将在运行时组件实例化期间可用。

每个属性条目包含以下键:

  1. name:此属性在 PI 中显示的名称。这应该是一个易记的名称。可予以本地化。
  2. variable:对此属性使用的内部名称。所配置的值将在运行时随此变量名称提供。有关此键的更多信息将在后面的部分中加以介绍。
  3. Type:指定属性的类型。Animate 支持以下类型:
    1. Boolean(布尔值)- PI 中的复选框
    2. Number(数值)- PI 中的数值框
    3. String(字符串)  - PI 中的 文本框
    4. List(列表)      - 允许 用户 配置一组值。
    5. Collection(集合)- 允许用户配置一个 <键, 值> 对列表。(请参阅“组合框”)
    6. File Path(文件路径)- 允许用户浏览和选择任一本地文件。字符串值在运行时提供。此文件会自动复制在 assets 文件夹下发布的输出中,相对路径在运行时可用。
    7. Image Path(图像路径)- 允许用户浏览和选择 任一 图像。此文件会自动复制在所配置的图像文件夹下发布的输出中,相对路径在运行时可用。
    8. Video Content Path(视频内容路径)- 允许用户浏览和选择任一 Web 格式视频源(mp4、 ogg 、 ogv 、 webm )。配置的资源会复制到 video 文件夹下发布的输出中。
    9. Color(颜色)- PI 中的拾色器
  4. Default:属性的默认值。默认类型应 与 属性的类型相同。

组件源

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

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

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

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

 

HTML 模板

html 默认包含下面几部分(不包括预加载器 div):

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},以便它们也能接收鼠标事件。

组件的生命周期

组件的生命周期

  1. 组件实例是在为容器构造 DOM 时创建的。

  2. 之后当播放头到达使用该组件实例的帧时,该实例会被附加到 DOM。之后该实例附加一个 update 处理函数,该函数会在运行时每一次 tick 被调用。组件此时还会触发一个 attached 事件,且对父元素使用以下事件数据 {id: id_of_the_instance}

  3. 每次 update 回调,都将更新属性。在 tick 处理函数期间,所有的属性更新会被缓存并应用一次。当前不支持自定义属性补间。仅更新变换和可见性等基本属性。

  4. 当播放头到达删除组件实例的帧时,我们会将它与 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 文件夹下相应的文件夹中提供字符串。

.json 字符串

打包和分发 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; />
<file source=&quot;jquery-ui-1.12.0&quot; destination=&quot;$FLASH\HTML5Components\jQueryUI\&quot; file-type=&quot;ordinary&quot; />
<file source=&quot;jquery-ui-1.12.0&quot; destination=&quot;$FLASH\HTML5Components\jQueryUI\&quot; file-type=&quot;ordinary&quot; />

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

打包组件

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

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

    下载

  2. 将您的 MXI 组件文件和其他相关文件添加到文件夹。

  3. 使用 CC Extensions 签名工具 (ZXPSignCmd.exe) 创建 ZXP 扩展压缩文件。使用 ZXP 签名命令工具中的以下命令可创建 ZXP 文件:

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

    如果已经有证书,可以跳过此步骤。

    ZXPSignCmd -selfSignedCert US NY MyCompany MyCommonName password FileName.p12
    ZXPSignCmd -selfSignedCert US NY MyCompany MyCommonName password FileName.p12
    ZXPSignCmd -selfSignedCert US NY MyCompany MyCommonName password FileName.p12

    此时将在当前文件夹中生成 FileName.p12 文件。

    2. 使用以下命令签署扩展:

    ZXPSignCmd -sign projectName projectName.zxp FileName.p12 password
    ZXPSignCmd -sign projectName projectName.zxp FileName.p12 password
    ZXPSignCmd -sign projectName projectName.zxp FileName.p12 password

    projectName 是扩展项目的名称。在当前文件夹中,将生成一个名为 projectName.zxp 的文件。

分发组件

您可以向任何 Animate 用户分发此 projectName.zxp 打包组件文件。

Adobe 建议您通过 Adobe 插件网站分发产品。您可以公开(免费或付费)或私下分发加载项。

安装分发的组件

Animate 设计人员或开发人员可以使用“管理扩展”实用程序来安装分发的 ZXP 文件组件。

更快、更轻松地获得帮助

新用户?