Creazione di componenti HTML5 personalizzati

Cerca

Ultimo aggiornamento il 24 mag 2023

Animate

Apri app

Guida utente di Adobe Animate

Introduzione ad Animate

Animazione

Interattività

Area di lavoro e flusso di lavoro

File multimediali e video

Piattaforme

Esportazione e pubblicazione

Risoluzione dei problemi

Scopri come creare componenti personalizzati per HTML5 Canvas.

Animate offre un set di componenti predefiniti. Tuttavia, questi potrebbero non essere sufficienti per un particolare progetto. Questo articolo spiega come creare componenti personalizzati HTML5 per Animate.

La definizione di un componente è composta da tre parti principali:

Metadati: informazioni sul componente, quali nome visualizzato, versione, set di proprietà configurabili, icone e così via. Questi possono essere inclusi in un file denominato components.js. Puoi raggruppare i componenti creando una categoria; in tal caso questo file ti permette di fornire i metadati per tutti i componenti di una stessa categoria.
Sorgente: informazioni sulla sorgente del componente, incorporata in fase di runtime quando esegui l’anteprima o pubblichi un filmato mediante un componente.
Risorse: informazioni su tutte le dipendenze in fase di runtime quali la libreria Javascript o CSS o le risorse e icone di runtime. Le risorse possono essere utilizzate nell’ambiente di creazione di Animate.

La definizione di un componente ha anche risorse relative alla localizzazione.

componentsJS — Configurazione della cartella di esempio per una categoria di componenti personalizzati

Animate controlla le seguenti cartelle per individuare eventuali componenti HTML5 personalizzati da caricare all’avvio:

• Windows:

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

• MAC:

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

Il percorso della cartella riportato qui sopra si riferisce alla versione in inglese americano. Se usi Animate in un’altra lingua, cerca la cartella corrispondente invece di en_US (ad esempio, it_IT per la versione italiana).

Per ogni cartella in tale percorso che contiene il file components.js, Animate crea una categoria e carica tutti i componenti al suo interno.

Metadati dei componenti

I metadati del componente sono memorizzati in un file denominato components.js inserito in una cartella separata nella directory HTML5Components.

metadata-code — Metadati di esempio per un componente video.

Components.js

è un file JSON che contiene le seguenti sezioni:

Categoria: nome che viene visualizzato nel pannello Componenti per questo set di componenti; può essere localizzato.
Componenti: array in cui ogni voce contiene i metadati relativi a un componente. L’esempio precedente ha un solo elemento nell’array. I metadati presentano le sezioni seguenti:

Nome	Richiesto	Descrizione
ClassName	Sì	Nome della classe del componente specificato nel file di origine. Il nome della classe supporta un livello di spazi dei nomi. Ad esempio, Video.
Versione	No	Numero di versione del componente. Questo valore viene utilizzato per gli aggiornamenti futuri del componente. Tuttavia, il relativo flusso non è al momento definito.
Origine	Sì	Percorso relativo del file sorgente principale del componente. Nella sezione successiva vengono forniti ulteriori dettagli sul contenuto dell’origine.
Icona	No	Percorso relativo per l’icona del componente. Questa icona viene usata nel pannello Componenti e sullo stage quando viene creata un’istanza del componente, e viene accompagnata dal relativo nome. Se non viene fornita un’icona, verrà usata l’icona predefinita. Puoi specificare il nome del file png dell’icona da caricare (in genere 32x32). Oppure, se vuoi fornire icone diverse per le modalità d’interfaccia scura e chiara, puoi fornire due file png denominati come segue: icona_personalizzata_N.png – Icona per interfaccia scura icona_personalizzata_D.png – Icona per interfaccia chiara Per il valore di questo campo, modifica solo il nome “icona_personalizzata”. I suffissi vengono automaticamente aggiunti in base all’impostazione corrente.
Dimensioni	No	Dimensione predefinita per le istanze del componente. Quando l’utente trascina un componente dal pannello Componenti allo stage, viene creata una nuova istanza. Questo campo specifica le dimensioni iniziali predefinite per l’istanza del componente. Il valore deve essere un array [larghezza, altezza]. Se non viene specificato alcun valore, Animate sceglie una dimensione predefinita. Inoltre, Animate limita l’intervallo di dimensioni consentite da [2,2] a [1000,1000].
Dipendenze	No	Insieme di dipendenze per il componente. Questo è un array in cui ogni voce fornisce il percorso relativo di un’origine locale (con chiave = “src”) e il percorso CDN (con chiave =’cdn’). Il percorso CDN non è obbligatorio. Questo percorso viene utilizzato se nelle impostazioni di pubblicazione si utilizzano librerie in hosting. In caso contrario, per l’anteprima o la pubblicazione viene utilizzata l’origine locale. Prendi nota del percorso relativo utilizzato nell’esempio precedente (Video). Le dipendenze vengono caricate da un livello superiore: questo consente di condividere alcune dipendenze tra più set di componenti.
Proprietà	Sì	Questo è un array di proprietà. Quando si crea un’istanza del componente sullo stage, il set di proprietà configurato qui verrà automaticamente visualizzato nella finestra di ispezione Proprietà. Gli utenti di questo componente possono configurare tali proprietà in Animate e le proprietà configurate diventano disponibili durante la riproduzione dell’istanza del componente in fase di runtime. Ogni voce di proprietà contiene le seguenti chiavi: nome: nome visualizzato nella finestra di ispezione Proprietà per questa proprietà. Deve essere un nome facile da riconoscere e può essere localizzato. variabile: nome interno utilizzato per questa proprietà. I valori configurati saranno disponibili con questo nome di variabile in fase di runtime. Questo argomento verrà approfondito nelle sezioni successive. Tipo: specifica il tipo della proprietà. Animate consente i tipi seguenti: Booleano: casella di controllo nella finestra di ispezione Proprietà Numero: casella numerica nella finestra di ispezione Proprietà Stringa: casella di testo nella finestra di ispezione Proprietà Elenco: consente all’utente di configurare un array di valori. Raccolta: consente agli utenti di specificare un elenco di coppie <chiave, valore>. (Vedere Casella combinata) Percorso file: consente all’utente di individuare e selezionare un file locale. Il valore di stringa viene fornito in fase di runtime. Il file viene automaticamente copiato nell’output pubblicato nella cartella assets e il percorso relativo viene reso disponibile in fase di runtime. Percorso immagine: consente all’utente di individuare e selezionare un’immagine . Il file viene automaticamente copiato nell’output pubblicato nella cartella configurata per le immagini e il percorso relativo viene reso disponibile in fase di runtime. Percorso contenuto video: consente all’utente di individuare e selezionare un’origine video in formato Web (mp4, ogg , ogv , webm ). La risorsa configurata viene copiata nella cartella videos nell’output pubblicato. Colore: selettore di colore nella finestra di ispezione Proprietà Predefinito: valore predefinito della proprietà. Il valore predefinito deve essere dello stesso tipo della proprietà.

Origine componente

A ogni componente deve essere associato un file di origine con il codice necessario per gestire quanto segue:

Creazione dell’istanza del componente in fase di runtime con il set configurato di valori delle proprietà
Associazione e rimozione dal DOM.
Aggiornamenti delle proprietà in ogni fotogramma

Viene fornita una classe base, nonché una funzione di utilità nel file anwidget.js, per facilitare la creazione di componenti personalizzati. Questa interfaccia verrà ottimizzata in futuro, con retrocompatibilità. Attualmente sono supportati solo componenti basati su DOM. Tuttavia il supporto verrà esteso a componenti basati su Canvas. Attualmente sono supportati solo i widget. Tuttavia, il framework verrà ottimizzato per supportare anche l’aggiunta dei comportamenti (componenti non-UI).

Il file anwidget.js si trova nella cartella HTML5Components/sdk, all’interno della cartella del primo avvio. Fornisce una classe base AnWidgetper i componenti personalizzati e un metodo di utilità $.anwidget(<className>, {Object Prototype}) per la registrazione di un componente personalizzato. L’implementazione corrente utilizza jQuery, quindi jQuery viene sempre aggiunto come dipendenza ogni volta che si utilizzano i servizi forniti da un widget. Tuttavia, se non desideri aggiungere una dipendenza implicita su jQuery, puoi implementare una classe di componenti senza jQuery, che fornisce la stessa interfaccia sotto forma di widget.

L’html contiene per impostazione predefinita le seguenti sezioni (escluso il div del preloader):

animation_container — Sezioni HTML predefinite (escluso il div del preploader)

La figura precedente illustra l’ordine in cui gli elementi vengono aggiunti nel DOM. Quindi il div dom_overlay_container è visualizzato al di sopra del Canvas.

Non cambiare l’ID del div dom_overlay_container come nella nostra prima versione, perché un paio di funzioni dipendono da questo ID, come gli snippet di codice.

Come illustrato nella figura precedente, il div dom_overlay_container si trova al di sopra del Canvas come sovrapposizione. Affinché gli eventi del mouse vengano propagati correttamente al Canvas sottostante, abbiamo usato per questo div la proprietà CSS {pointer-events: none}. Tutte le istanze del componente configurate nel progetto in Animate sono create e allegate come elemento secondario di questo div dom_overlay_container. L’ordine relativo delle istanze del componente viene mantenuto in fase di runtime, ma al momento tutte le istanze del componente vengono sempre visualizzate come sovrapposizione. Abbiamo impostato {pointer-events: all} per tutte le istanze del componente in fase di runtime, affinché ricevano anch’esse gli eventi del mouse.

Ciclo di vita di un componente

component_lifecycle — Ciclo di vita di un componente

L’istanza del componente viene creata quando il DOM viene generato per il contenitore.
L’istanza viene allegata al DOM quando la testina di riproduzione raggiunge il fotogramma in cui è utilizzata l’istanza del componente. Quindi viene allegato un gestore di aggiornamento che viene chiamato a ogni Tick in fase di runtime. Il componente attiva inoltre in questo momento un evento attached con i seguenti dati evento {id: id_of_the_instance} sull’elemento di livello superiore.
Le proprietà vengono aggiornate ad ogni callback di aggiornamento. Tutti gli aggiornamenti delle proprietà sono memorizzati nella cache e vengono applicati immediatamente durante un gestore di Tick. Al momento le interpolazioni di proprietà personalizzate non sono supportate. Vengono aggiornate solo le proprietà di base, come trasformazione e visibilità.
Infine, quando la testina di riproduzione arriva a un fotogramma in cui l’istanza del componente è stata rimossa, avviene la rimozione dal DOM. A questo punto viene attivato un evento detached sull’elemento di livello superiore.

La classe base si chiama $.AnWidget e fornisce le seguenti esclusioni:

Nome	Obbligatorio	Descrizione
getCreateOptions()	No	Restituisce eventuali opzioni la cui applicazione è richiesta dal componente durante la creazione dell’istanza del componente. In un’esclusione tipica questo viene generalmente usato per assegnare un ID univoco a ciascuna istanza, tramite la variabile globale _widgetID. Questo verrà illustrato meglio nell’esempio fornito nella sezione successiva.
getCreateString()	Sì	Restituisce la stringa per la creazione del DOM dell’istanza. Questa stringa viene passata a jQuery per creare l’effettivo elemento DOM che viene poi allegato al DOM di base. Ad esempio, per un componente immagine verrà restituito <image>. In fase di runtime, l’elemento viene creato e il riferimento al wrapper jQuery viene memorizzato come segue nell’istanza del componente: this._element = $(this.getCreateElement()) // this._element – Wrapper jQuery per l’elemento DOM sottostante creato. È possibile anche creare elementi compositi, come descritto in una sezione di esempi.
getProperties()	No	Restituisce un array di nomi di proprietà configurabili. In genere, questo corrisponde alle proprietà configurate in components.json Ad esempio, per il componente video questo array contiene le voci seguenti: ["left", "top", "width", "height", "position", "transform-origin", "transform"]
getAttributes()	No	Restituisce un array di attributi configurabili. In genere, questo corrisponde a tutti gli attributi di cui avete consentito la configurazione in components.json Ad esempio, per il componente video questo array contiene le voci seguenti: ["id", "src", "controls", "autoplay", "loop", "class"]
attach(parent)	No	Questa funzione viene chiamata ogni volta che l’istanza del componente sta per essere allegata all’elemento DOM di livello superiore. L’implementazione predefinita esegue le seguenti operazioni (e altre): // Aggiunge l’elemento al DOM di livello superiore $(parent).append(this._element); //Memorizza il riferimento in this._$this this._$this = $(this._element); //Chiama l’aggiornamento forzato per applicare tutte le proprietà this.update(true); this._attached = true; //Attiva l’evento allegato all’elemento di livello superiore $(parent).trigger("attached", this.getEventData("attached")) Non è necessario escludere questa funzione. Tuttavia, per gli elementi compositi potrebbe essere necessario escluderla. Questo argomento verrà approfondito nella sezione degli esempi. Nota: puoi usare this._superApply(arguments) per chiamare qualsiasi metodo di classe base da qualsiasi esclusione.
detach()	No	Questa funzione viene chiamata ogni volta che l’istanza del componente sta per essere rimossa dal DOM. L’implementazione predefinita esegue le seguenti operazioni: //Rimuove l’elemento dal DOM this._$this.remove(); //Attiva l’evento “detached” sull’elemento di livello superiore $(parent).trigger("detached", this.getEventData("detached"));
setProperty(k,v)	No	Questa funzione viene utilizzata per impostare eventuali proprietà per l’istanza. Queste modifiche sono memorizzate nella cache e vengono applicate immediatamente durante la chiamata per aggiornare (update()) ogni fotogramma per ciascuna proprietà che contiene valori diversi.
update(force)	No	Questa funzione viene chiamata per ogni fotogramma quando il componente fa parte di un DOM ed è visibile. L’implementazione predefinita applica tutte le proprietà CSS e gli attributi che sono stati modificati o per i quali è impostato il parametro “force”.
show()	No	Rende visibile l’istanza dell’elemento. In genere non è necessario escludere questa funzione, ma potrebbe esserlo per gli elementi compositi.
hide()	No	Nasconde l’istanza dell’elemento. In genere non è necessario escludere questa funzione, ma potrebbe esserlo per gli elementi compositi.
getEventData(e)	No	Restituisce eventuali dati personalizzati per l’evento con il nome “e”. L’implementazione predefinita passa i dati {id: instance_id} per gli eventi “attached” e “detached”.
destroy()	No	Libera la memoria quando l’istanza del componente è rimossa dal DOM. In genere non è necessario escludere questa funzione.
applyProperties(e)	No	API assistente per l’applicazione di proprietà CSS al wrapper jQuery “e”.
applyAttributes(e)	No	API assistente per l’applicazione di attributi al wrapper jQuery “e”.

Localizzazione

La stringa di categoria, il nome visualizzato del componente e il nome della proprietà possono essere localizzati. Crea un file denominato strings.json in una cartella denominata locale nella cartella dei componenti. Inserisci le coppie chiave-valore per tutte le stringhe da localizzare e digita la chiave in components.js. Per altre lingue, è necessario fornire le stringhe nelle cartelle corrispondenti all’interno della cartella locale.

Creare un pacchetto e distribuire i componenti HTML5 personalizzati

Gli sviluppatori o i designer Animate possono consentire agli animatori di installare e utilizzare i componenti senza dover scrivere alcun codice, fornendo loro pacchetti di componenti pronti all’uso. In precedenza, per attivare le estensioni HTML5 gli animatori dovevano apprendere le strutture dei file, programmare e spostare manualmente i file in cartelle specifiche.

Prerequisiti

Qualsiasi componente creato da uno sviluppatore. Fate clic qui per informazioni su come creare i componenti.
Toolkit per la firma di estensioni CC.

Prima di effettuare la creazione di un pacchetto per il vostro componente, create un file MXI con i metadati del percorso di origine e destinazione dei componenti. Ad esempio,

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

Queste informazioni sul file di origine e destinazione sono necessarie per abilitare l'utility delle estensioni per l'installazione accurata del componente.

Creazione di pacchetti di componenti

Per creare un pacchetto di componenti HTML5 personalizzati:

Per creare un file MXI, immettete il contenuto come nel file di esempio abc.mxi utilizzando un editor di testo e salvatelo con l'estensione MXI.

Scarica

Ottieni file
Scarica un file di esempio abc.mxi.
Aggiungete il file del componente MXI e gli altri file associati in una cartella.
Create un file zip con estensione ZXP usando lo strumento di firma delle estensioni CC (ZXPSignCmd.exe). Utilizzate i seguenti comandi nello strumento ZXP per creare un file ZXP:

1. Create un certificato autofirmato utilizzando l'opzione -selfSignedCert.

Potete ignorare questo passaggio se disponete già di un certificato.
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
```
Il file FileName.p12 viene generato nella cartella corrente.

2. Firmate l'estensione con il seguente comando:
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 è il nome del progetto d'estensione. Nella cartella corrente, viene generato un file denominato projectName.zxp.

Distribuire i componenti

Potete condividere questo file di pacchetto di componenti projectName.zxp con altri utenti Animate.

Adobe consiglia di distribuire i prodotti attraverso il sito Web Adobe Add-ons. Potete effettuare la distribuzione pubblicamente (gratuitamente o meno) o in privato (gratuitamente per gli utenti nominati).

Installare i componenti condivisi

I designer o gli sviluppatori Animate possono installare il componente del file ZXP condiviso usando l'utility Gestisci estensioni.

Altri argomenti correlati

Ottieni supporto in modo più facile e veloce

Nuovo utente?