Guía del usuario Cancelar

Creación de componentes HTML5 personalizados

Buscar

Última actualización el 24 may. 2023

En este artículo le enseñamos a crear componentes personalizados para HTML5 Canvas.

Animate se suministra con un conjunto de componentes predeterminados. Sin embargo, estos son insuficientes para su proyecto. Este tema le ayudará a comprender cómo crear componentes HTML5 personalizados para Animate.

Una definición de componente consta de tres partes principales:

Metadatos: proporciona información sobre el componente, como el nombre para mostrar, la versión, el conjunto de propiedades configurables, el icono, etcétera. Esto se captura en un archivo llamado components.js. Puede agrupar los componentes como categoría y este archivo le permite proporcionar los metadatos para todos los componentes en una categoría.
Origen: Proporciona información sobre el origen real del componente. Esto se incrusta en el motor de ejecución cuando se previsualiza o se publica una película mediante componentes.
Recursos: Aporta información sobre cualquier dependencia del motor de ejecución, por ejemplo, la biblioteca JavaScript o CSS o los elementos de tiempo de ejecución y los iconos. Los recursos se pueden utilizar en el entorno de edición de Animate.

Una definición de componente también tiene recursos relacionados con la localización.

componentsJS — Configuración de la carpeta de muestra para una categoría de componentes personalizados

Animate comprueba las siguientes carpetas en busca de cualquier componente de HTML5 personalizado y lo carga al inicio:

• Windows:

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

• MAC:

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

La ruta de carpeta anterior se aplica a inglés de Estados Unidos. Si usa Animate en otro idioma, sustituya en_US por su idioma para buscar el nombre de carpeta específico.

Animate crea una categoría y carga todos los componentes dentro de cada carpeta de la ubicación que contiene el archivo "components.js".

Metadatos de componente

Los metadatos de Componente están incluidos en un archivo llamado components.js que se coloca en una carpeta independiente dentro del directorio HTML5Components.

metadata-code — Metadatos de ejemplo para un componente de vídeo.

Components.js

es un archivo JSON que contiene las siguientes secciones:

Categoría: nombre del panel Componentes para este conjunto de componentes y que se puede localizar.
Componentes: conjunto donde cada entrada contiene los metadatos sobre un componente. El ejemplo anterior solo tiene un elemento en el conjunto. Los metadatos tienen las secciones siguientes:

Nombre	Obligatorio	Descripción
ClassName	Sí	Nombre de clase del componente especificado en el archivo de origen. El nombre de la clase admite un nivel de espacios de nombres. Por ejemplo, vídeo.
Versión	No	Número de versión del componente. Se utiliza para las actualizaciones futuras de los componentes. Sin embargo, el flujo no está definido en este momento.
Fuente	Sí	Ruta relativa del archivo de origen principal del componente. En la siguiente sección se proporcionan más detalles sobre el contenido del origen.
Icono	No	Ruta relativa para el icono para el componente. Este icono se utiliza en el panel de componentes y en el escenario al crear una instancia para el componente junto con su nombre. Si no se proporciona ninguno, se utiliza un icono predeterminado. Puede especificar el nombre del icono png que va a cargarse (normalmente 32x32). O bien, si desea admitir distintos iconos para una interfaz de usuario clara o una interfaz de usuario oscura, entonces debe proporcionar los dos .png con la siguiente convención de asignación de nombres: custom_icon_N.png – Icono para interfaz de usuario oscura custom_icon_D.png – Icono para interfaz de usuario clara y especifique el nombre 'custom_icon' como el valor para este campo. Los sufijos se añaden automáticamente en función de los ajustes actuales del usuario.
Dimensiones	No	Tamaño predeterminado de las instancias del componente. Siempre que el usuario arrastre y suelte un componente del panel Componentes al escenario, se crea una instancia nueva. Este campo especifica el tamaño inicial predeterminado para la instancia de componente. El valor debe ser un conjunto [anchura, altura]. Si no hay ningún valor especificado, entonces, Animate detecta un tamaño predeterminado. Además, Animate también restringe el tamaño en el rango entre [2,2] a [1000, 1000].
Dependencias	No	El conjunto de dependencias para el componente. Se trata de un conjunto donde cada entrada proporciona la ruta relativa de un origen local (con clave = “src”) y la ruta de la CDN (con clave = "cdn"). La ruta de CDN normalmente no es obligatoria. Esta ruta se utiliza cuando se usan bibliotecas alojadas en la configuración de publicación. De lo contrario, para la vista previa o la publicación, se utiliza el origen local. Observe la ruta relativa utilizada en el ejemplo anterior (vídeo). Carga las dependencias de un nivel superior, lo cual permite compartir algunas dependencias en múltiples conjuntos de componentes.
Propiedades	Sí	Este es un conjunto de propiedades. Cuando cree una instancia de este componente en el escenario, el conjunto de propiedades que se configure aquí se mostrará automáticamente en el inspector de propiedades. Los usuarios de este componente pueden configurar estas propiedades en Animate. Asimismo, las propiedades configuradas estarán disponibles durante la creación del componente en tiempo de ejecución. Cada entrada de la propiedad contiene las siguientes claves: nombre: el nombre que se muestra en el Inspector de propiedades para esta propiedad. Debe ser un nombre descriptivo. Este se puede localizar. variable: nombre interno utilizado para esta propiedad. Los valores configurados estarán disponibles con este nombre de variable en tiempo de ejecución. En secciones posteriores podrá encontrar más información sobre esto. Tipo: especifica el tipo de propiedad. Animate permite los siguientes tipos: Booleano: casilla de verificación en el inspector de propiedades Número: cuadro numérico en el inspector de propiedades Cadena: cuadro de texto en el inspector de propiedades Lista: permite al usuario configurar una matriz de valores. Colección: permite que los usuarios configuren una lista de pares <clave, valor>. (Consulte el cuadro combinado) Ruta de archivo: permite que el usuario busque y seleccione cualquier archivo local. El valor de cadena se indica en tiempo de ejecución. El archivo se copia automáticamente en la salida publicada en la carpeta "assets" y la ruta relativa pasa a estar disponible en tiempo de ejecución. Ruta de imagen: permite al usuario buscar y seleccionar una imagen. El archivo se copia automáticamente en la salida publicada en la carpeta de imágenes configuradas. A continuación, la ruta relativa pasa a estar disponible en tiempo de ejecución. Ruta de contenido de vídeo: permite al usuario buscar y seleccionar cualquier origen de vídeo en el formato web (mp4, ogg , ogv , webm ). El activo configurado se copia a la carpeta "videos" en la salida publicada. Color - selector de color en el Inspector de propiedades Predeterminado: valor predeterminado de la propiedad. El valor predeterminado debe ser del mismo tipo que el de la propiedad.

Origen del componente

Cada componente debe disponer de un archivo de origen asociado con código para gestionar lo siguiente:

Creación de la instancia de componente en tiempo de ejecución con un conjunto configurado de valores de propiedad
Asociar o desasociar al DOM.
Actualizaciones de la propiedad en cada fotograma

Se proporciona una clase base y una función de utilidad en el archivo anwidget.js para facilitar el desarrollo de componentes personalizados. Esta interfaz se incrementará en el futuro, pero será compatible con versiones anteriores. Actualmente, solo son compatibles los componentes basados en DOM; sin embargo, se ampliará la compatibilidad con componentes basados en Canvas. Actualmente solo son compatibles los widgets; sin embargo, se mejorará el marco para la compatibilidad con comportamientos de adición (componentes distintos a la interfaz de usuario).

El archivo anwidget.js está presente en la carpeta HTML5Components/sdk de la carpeta que se ejecutó por primera vez. Proporciona una clase base AnWidgetpara componentes personalizados y un método de utilidad $.anwidget (<className>, {prototipo de objeto}) para registrar un componente personalizado. La implementación actual utiliza jQuery, por lo que siempre se añade jQuery como una dependencia siempre que utilice los servicios ofrecidos por un widget. Sin embargo, si no desea agregar una dependencia implícita en jQuery, puede que tenga que implementar una clase de componente sin jQuery que proporcione la misma interfaz que un widget.

El HTML contiene las siguientes secciones (excepto el div de precargador) de forma predeterminada:

animation_container — Secciones del código HTML predeterminado (excepto el div de precargador)

Tenga en cuenta que la figura anterior muestra el orden en que los elementos se añaden en el DOM. Por tanto, sobre el lienzo se muestra el dom_overlay_container div.

No cambie la identificación del dom_overlay_container div como en nuestra primera versión, hay un par de funciones que dependen de esta identificación como fragmentos de código.

Como se muestra en la ilustración anterior, el dom_overlay_container div se muestra encima del lienzo como superposición. Para asegurarse de que los eventos de ratón también se hayan propagado correctamente al lienzo subyacente, se utiliza la propiedad CSS {pointer-events: none} para este div para que los eventos de ratón se propaguen al lienzo subyacente. Todas las instancias de componentes que se configuran en Animate en el proyecto se crean y se asocian como elemento secundario de este div dom_overlay_container. El orden relativo de las instancias de componente se mantiene en el tiempo de ejecución, aunque actualmente todas las instancias de componente se muestran como superposición. Se ha establecido {pointer.events: all} para todas las instancias de componente en tiempo de ejecución para que también reciban los eventos de ratón.

Ciclo de vida del componente

component_lifecycle — Ciclo de vida del componente

Se crea la instancia de componente cuando se construye DOM para el contenedor.
A continuación, la instancia se asocia al DOM cuando la cabeza lectora alcanza el fotograma en el que se utiliza la instancia de componente. Entonces, asocia un controlador de actualización al cual se llama en cada marca en tiempo de ejecución. El componente también activa un evento ‘adjunto’ en este momento con los siguientes datos de evento {id: id_of_the_instance} en el elemento principal.
Se actualizan las propiedades en cada llamada de actualización. Todas las actualizaciones de la propiedad se almacenan en caché y se aplican de forma instantánea durante un controlador de marca. Actualmente no se admiten las interpolaciones de propiedades personalizadas. Solo se actualizan las propiedades básicas, como la transformación y la visibilidad.
Cuando el cabezal de reproducción llega a un fotograma en el que se elimina la instancia de componente por completo, se separa del DOM. Un evento “separado” se activa en este momento en el elemento principal.

La clase base se denomina $.AnWidget e incluye los cambios siguientes:

Nombre	Obligatorio	Descripción
getCreateOptions()	No	Devuelve cualquier opción que el componente se desee aplicar durante la creación del componente. Una anulación típica normalmente utiliza esto para asignar una identificación única para cada instancia utilizando la variable _widgetID. El ejemplo en la siguiente sección, aclara su uso.
getCreateString()	Sí	Devuelve la cadena para la creación de la instancia DOM. Esta cadena se transfiere al programa de jQuery para crear el elemento DOM en sí el cual se adjunta posteriormente al DOM base. Por ejemplo, para un componente de imagen debe devolver el “<image>”. En tiempo de ejecución se crea el elemento y la referencia a un contenedor de jQuery se almacena de la forma siguiente en la instancia de componente: this._element = $(this.getCreateElement()) // this._element – contenedor jQuery para el elemento DOM creado subyacente. También podemos crear elementos compuestos; se abordarán en más detalle en una sección de ejemplos.
getProperties()	No	Devuelve un conjunto de nombres de propiedades CSS configurables. Normalmente, este coincide con todas las propiedades configuradas en components.json Por ejemplo, para el componente de vídeo este conjunto contiene las siguientes entradas: ["left", "top", "width", "height", "position", "transform-origin", "transform"]
getAttributes()	No	Devuelve un conjunto de atributos configurables. Normalmente, este coincide con todos los atributos que le permiten configurar components.json Por ejemplo, para el componente de vídeo este conjunto contiene las siguientes entradas: ["id", "src", "controls", "autoplay", "loop", "class"]
attach(parent)	No	Se llama a esta función cada vez que la instancia de componente está a punto de ser adjuntada al elemento DOM "parent". La implementación predeterminada realiza lo siguiente (y más cosas): // Añade el elemento al DOM principal $(parent).append(this._elemento); //Almacena la ref en this._$this this._$this = $(this._elemento); //Llama a la actualización forzada para aplicar todas las propiedades this.update(true); this._attached = true; //Activa el evento asociado al elemento principal $(parent).trigger("attached", this.getEventData("attached")) No es necesario anular esta función. Sin embargo, para los elementos compuestos, es posible que deba anularse. En la sección de ejemplos se explican en más detalle. Nota: Puede utilizar this._superApply(arguments) para llamar a cualquier método de la clase base de cualquier anulación.
detach()	No	Se llama a esta función cada vez que la instancia de componente está a punto de eliminarse del DOM. La implementación predeterminada hace lo siguiente: //Elimina el elemento del DOM this._$this.remove(); //Activa el evento por separado en el elemento principal $(parent).trigger("detached", this.getEventData("detached"));
setProperty(k,v)	No	Esta función se utiliza para definir cualquier propiedad para la instancia. Estos cambios se almacenan en caché y se aplican de una sola vez durante la llamada para actualizar con update() cada fotograma de cada propiedad que esté sucio.
update(force)	No	Se llama a esta función en cada fotograma cuando el componente forma parte del DOM y está visible. La implementación predeterminada aplica todas las propiedades CSS y los atributos que se han modificado o si el parámetro de fuerza es verdadero.
show()	No	Muestra la instancia del elemento. No suele ser necesario anular eso, pero es posible que sea necesario para elementos compuestos.
hide()	No	Oculta la instancia del elemento. No suele ser necesario anular eso, pero es posible que sea necesario para elementos compuestos.
getEventData(e)	No	Devuelve cualquier dato personalizado para el evento con el nombre 'e'. La implementación predeterminada pasa los datos {id: instance_id} para los eventos asociados o desasociados.
destroy()	No	Libera la memoria cuando la instancia del componente se separa de DOM. No suele ser necesario anular this.
applyProperties(e)	No	Asistente API para aplicar propiedades CSS para el envolvente de jQuery e.
applyAttributes(e)	No	Asistente API para aplicar los atributos para el envolvente de jQuery e.

Localización

La cadena de categoría, el nombre de visualización del componente y el nombre de la propiedad pueden ser localizados. Cree un archivo denominado strings.json en una carpeta con el nombre regional en la carpeta de componentes. Introduzca los pares de valor clave para que todas las cadenas puedan localizarse y se pueda utilizar la clave en components.js. Para otras configuraciones regionales, debe proporcionar las cadenas en las carpetas correspondientes en la carpeta local.

Empaquete y distribuya componentes HTML5 personalizados

Los desarrolladores y los diseñadores de Animate pueden permitir que los animadores instalen y utilicen componentes sin codificación, con componentes empaquetados listos para usar. Anteriormente, los animadores tenían que aprender estructuras de archivos, hacer programación y mover manualmente los archivos a carpetas concretas para activar las extensiones HTML5.

Requisitos previos

Cualquier componente creado por un desarrollador. Haga clic aquí para obtener instrucciones sobre la creación de componentes.
CC Extensions signing toolkit.

Antes de empaquetar un componente, cree un archivo MXI con los metadatos de la ruta de componentes de origen y de destino. Por ejemplo,

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

Esta información del archivo de origen y de destino es necesaria para activar la utilidad de extensiones para la instalación precisa del componente.

Componentes de empaquetado

Para empaquetar los componentes HTML5 personalizados, realice los pasos siguientes:

Para crear un archivo MXI, introduzca un contenido similar al del archivo de ejemplo abc.mxi utilizando un editor de texto y guárdelo con la extensión MXI .

Descargar

Obtener archivo
Descargue un archivo abc.mxi de muestra.
Añada el componente MXII y otros archivos asociados en una carpeta.
Cree un archivo .zip con la extensión ZXP usando la herramienta CC signing (ZXPSignCmd.exe). Utilice los comandos siguientes en la herramienta ZXP Sign Command para crear un archivo ZXP:

1. Cree un certificado con firma automática usando la opción -selfSignedCert.

Este paso se puede omitir si ya dispone de un certificado.
```
ZXPSignCmd -selfSignedCert US NY MyCompany MyCommonName password FileName.p12
```
El archivo FileName.p12 se genera en la carpeta actual.

2. Inicie la extensión con el siguiente comando:
```
ZXPSignCmd -sign projectName projectName.zxp FileName.p12 password
```
projectName es el nombre del proyecto de la extensión. En la carpeta actual se genera un archivo con el nombre projectName.zxp.

Componentes de distribución

Puede distribuir este archivo de componentes empaquetados projectName.zxp a cualquier usuario de Animate.

Adobe recomienda que distribuya sus productos a través del sitio web Adobe Add-ons. Puede distribuir complementos públicamente (gratis o de pago) o de forma privada (disponible para los usuarios indicados).

Instalación de componentes distribuidos

Los diseñadores o desarrolladores de Animate pueden instalar el componente del archivo ZXP distribuido usando la utilidad Gestionar extensiones.

Más productos similares

Adobe

Obtén ayuda de forma más rápida y sencilla

¿Nuevo usuario?