创建自定义 HTML5 组件

名称

必需

描述

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：属性的默认值。默认类型应与属性的类型相同。

名称

必需

描述

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 应用特性。