Nom
Dernière mise à jour le
24 mai 2023
Consultez cet article pour savoir comment créer des composants personnalisés pour les documents HTML5 Canvas.
Animate est livré avec différents composants par défaut. Toutefois, ces composants sont insuffisants pour votre projet. Consultez cette rubrique pour mieux comprendre comment créer des composants HTML5 personnalisés pour Animate.
La définition d’un composant comprend trois parties principales :
- Métadonnées : cette catégorie fournit des informations sur le composant, telles que le nom d’affichage, la version, le jeu de propriétés configurables, l’icône, etc. Ces données sont capturées dans un fichier appelé components.js. Vous pouvez grouper les composants dans une catégorie ; ce fichier vous permet de spécifier les métadonnées pour tous les composants d’une catégorie.
- Source : cette catégorie fournit des informations sur le composant source proprement dit. Ces informations sont incorporées au moment de l’exécution lorsque vous prévisualisez ou publiez une séquence à l’aide des composants.
- Actifs : cette catégorie fournit des informations sur toute dépendance d’exécution telle qu’une bibliothèque JavaScript ou des icônes et des actifs d’exécution et CSS. Les actifs peuvent être utilisés dans l’environnement de création d’Animate.
Une définition de composant comprend également des ressources associées à la localisation.
Animate recherche dans les dossiers suivants les composants HTML5 personnalisés et les charge au démarrage :
• Windows :
<AppData>/Local/Adobe/Adobe Animate 2017/fr_FR/Configuration/HTML5Components
• MAC :
~/Library/Application Support/Adobe/Animate 2017/fr_FR/Configuration/HTML5Components/
Le chemin du dossier ci-dessus correspond au français. Si vous utilisez Animate dans une autre langue, recherchez le nom du dossier spécifique à votre langue en remplaçant fr_FR.
Pour chaque dossier à l’emplacement contenant le fichier components.js, Animate crée une catégorie, dans laquelle il charge tous les composants.
Métadonnées du composant
Les métadonnées du composant sont capturées dans un fichier nommé components.js, qui est placé dans un dossier distinct dans le répertoire HTML5Components.
components.js
components.js
est un fichier JSON qui contient les sections suivantes :
- Catégorie : nom dans le panneau Composants pour cet ensemble de composants ; il peut être localisé.
- Composants : tableau où chaque entrée contient des métadonnées sur un composant. L’exemple ci-dessus ne comporte qu’un seul élément dans le tableau. Les métadonnées comportent les sections suivantes :
|
|
Obligatoire |
Description |
|---|---|---|
|
ClassName |
Oui |
Classe du composant spécifié dans le fichier source. Le nom de la classe prend en charge un seul niveau des espaces de noms. Par exemple, Vidéo.
|
|
Version |
Non |
Version de version du composant. Il sera utilisé pour les prochaines mises à niveau de composants. Toutefois, le flux n’est pas défini à ce stade. |
|
Source |
Oui |
Chemin d’accès relatif vers le fichier source principal du composant. Vous trouverez plus d’informations sur le contenu de la source dans la section suivante. |
|
Icône |
Non |
Chemin d’accès relatif vers l’icône du composant. Cette icône est utilisée dans le panneau des composants et sur la scène lorsque toute occurrence est créée pour le composant avec son nom. Si aucune icône n’est fournie, une icône par défaut est utilisée. Vous pouvez spécifier le nom png de l’icône à charger (généralement 32x32). Ou, si vous souhaitez prendre en charge deux icônes distinctes pour les interfaces utilisateur claire et sombre, fournissez deux fichiers .png en appliquant la convention de dénomination suivante : custom_icon_N.png – Icône de l’interface utilisateur sombre custom_icon_D.png – Icône de l’interface utilisateur claire Il vous suffit alors de spécifier le nom « custom_icon » comme valeur de ce champ. Les suffixes sont automatiquement ajoutés en fonction du paramétrage utilisateur actuel. |
|
Dimensions |
Non |
Par défaut des occurrences de composants. Chaque fois que l’utilisateur fait glisser et déplace un composant du panneau Composants sur la scène, une nouvelle occurrence est créée. Ce champ indique la taille initiale par défaut de l’occurrence du composant. La valeur doit être un tableau [width, height] ([largeur, hauteur]). Si aucune valeur n’est spécifiée, Animate utilise une taille par défaut. Par ailleurs, Animate confine la taille dans la plage [2,2] à [1000,1000]. |
|
Dépendances |
Non |
Ensemble de dépendances pour le composant. Tableau où chaque entrée fournit le chemin d’accès relatif vers une source locale (avec la clé = src) et le chemin d’accès au réseau de diffusion de contenu (avec la clé = cdn). Le chemin d’accès au réseau de diffusion de contenu n’est pas obligatoire ; il est utilisé lorsque vous employez des bibliothèques hébergées dans les paramètres de publication. Dans le cas contraire, la source locale sera utilisée lors de la prévisualisation ou de la publication. Notez le chemin d’accès relatif utilisé dans l’exemple ci-dessus (vidéo). Il charge les dépendances d’un niveau au-dessus, ce qui permet de partager certaines dépendances entre plusieurs jeux de composants. |
|
Propriétés |
Oui |
Il s’agit d’un tableau de propriétés. Lorsque vous créez toute occurrence de ce composant sur la scène, le jeu de propriétés configuré ici s’affiche automatiquement dans l’inspecteur des propriétés. Les utilisateurs de ce composant peuvent configurer ces propriétés dans Animate ; les propriétés configurées sont rendues disponibles lors de l’instanciation du composant au moment de l’exécution. Chaque entrée de propriété contient les clés suivantes :
|
Source de composant
Chaque composant doit avoir un fichier source associé qui fournit le code pour gérer les éléments suivants :
- la création de l’occurrence de composant au moment de l’exécution avec le jeu configuré de valeurs de propriété ;
- l’association et la dissociation avec l’objet DOM ;
- les mises à jour de la propriété de chaque image.
Afin de faciliter le développement des composants personnalisés, une classe de base est spécifiée, ainsi qu’une fonction utilitaire, dans le fichier anwidget.js. Cette interface sera améliorée à l’avenir mais sera rétrocompatible. Actuellement, seuls les composants DOM sont pris en charge ; cependant, la prise en charge des composants Canvas sera étendue. Pour l’instant, seuls les widgets sont pris en charge ; toutefois, l’infrastructure sera améliorée de manière à prendre en charge les comportements d’association (composants hors interface utilisateur).
Le fichier anwidget.js est présent dans le dossier HTML5Components/sdk du répertoire de la première exécution. Il fournit une classe de base AnWidget pour les composants personnalisés et une méthode d’utilitaire $.anwidget(<className>, {Object Prototype}) pour l’enregistrement d’un composant personnalisé. Puisque la mise en œuvre actuelle utilise jQuery, jQuery est toujours ajouté comme une dépendance lorsque vous utilisez les services fournis par un widget. Cependant, si vous ne souhaitez pas ajouter une dépendance implicite à jQuery, il vous faudra peut-être mettre en œuvre une classe de composant sans jQuery qui fournit la même interface qu’un widget.
Le code HTML contient ces sections (à l’exception de la balise div de préchargement) par défaut :
Notez que l’illustration ci-dessus reproduit l’ordre dans lequel les éléments sont ajoutés au DOM. La balise div dom_overlay_container apparaît au-dessus de la balise canvas.
Ne changez pas l’identifiant de la balise div dom_overlay_container, car certaines fonctions de notre première version dépendent de cet identifiant, tels les fragments de code.
Comme indiqué dans l’illustration ci-avant, la balise div dom_overlay_container s’affiche au-dessus de la balise canvas comme une superposition. Afin que les événements de souris soient correctement propagés dans la zone de travail canvas sous-jacente, nous utilisons pour cette balise div la propriété CSS {pointer-events: none}. Toutes les occurrences de composant configurées dans Animate dans votre projet sont instanciées et associées en tant qu’enfant de cette div dom_overlay_container. L’ordre relatif des occurrences de composant est préservé au moment de l’exécution, mais actuellement, toutes les occurrences de composant restent affichées comme une superposition. Nous définissons {pointer-events: all} pour toutes les occurrences de composant au moment de l’exécution, de façon à ce qu’elles reçoivent également les événements de souris.
Cycle de vie du composant
L’occurrence de composant est créée lorsque le DOM est conçu pour le conteneur.
L’occurrence est ensuite associée au DOM lorsque la tête de lecture atteint l’image où est utilisée l’occurrence du composant. Elle associe ensuite un gestionnaire de mises à jour qui est appelé à chaque cycle au moment de l’exécution. Le composant déclenche également un événement « attached » (associé) à ce moment avec les données d’événement {id: id_of_the_instance} sur l’élément parent.
Les propriétés sont mises à jour dans chaque rappel de mise à jour. Toutes les mises à jour de propriété sont mises en cache et appliquées au cours d’un traitement des cycles. Actuellement, les interpolations de propriétés personnalisées ne sont pas prises en charge. Seules les propriétés de base telles que la transformation et la visibilité sont mises à jour.
Lorsque la tête de lecture atteint une image d’où l’occurrence de composant est supprimée, nous la dissocions du DOM. Un événement « detached » (dissocié) est déclenché à ce moment sur l’élément parent.
La classe de base se nomme $.AnWidget ; elle fournit les remplacements suivants :
Nom |
Obligatoire |
Description |
|---|---|---|
getCreateOptions() |
Non |
Renvoie toutes les options que le composant souhaite voir appliquées lors de l’instanciation du composant. Un remplacement standard utilise généralement cette fonction pour attribuer un identifiant unique à chaque occurrence à l’aide de l’identifiant _widgetID variable global. Reportez-vous à l’exemple de la section suivante afin de mieux comprendre. |
getCreateString() |
Oui |
Renvoie la chaîne pour la création de l’occurrence du DOM. Cette chaîne est transmise à jQuery afin de créer l’élément DOM réel associé ensuite au DOM de base.
Par exemple, pour un composant d’image, elle doit renvoyer « <image> ».
Au moment de l’exécution, l’élément est créé et la référence au wrapper jQuery est stockée comme suit dans l’occurrence du composant :
this._element = $(this.getCreateElement())
// this._element - wrapper jQuery pour l'élément DOM sous-jacent créé.
Vous pouvez également créer des éléments composites ; les détails sont traités dans la section des exemples. |
getProperties() |
Non |
Renvoie un tableau de noms de propriétés CSS configurables. Généralement, ceci correspond à toutes les propriétés que vous avez configurées dans components.json.
Par exemple, pour le composant vidéo, ce tableau contient les entrées suivantes :
["left", "top", "width", "height", "position", "transform-origin", "transform"] |
getAttributes() |
Non |
Renvoie un tableau d’attributs configurables. Généralement, correspond à tous les attributs que vous êtes autorisé à configurer dans components.json.
Par exemple, pour le composant vidéo, ce tableau contient les entrées suivantes :
["id", "src", "controls", "autoplay", "loop", "class"] |
attach(parent) |
Non |
Cette fonction est appelée lorsque l’occurrence du composant est sur le point d’être associée à l’élément DOM « parent ».
La mise en œuvre par défaut effectue les opérations suivantes (entre autres) :
// Annexe l’élément au DOM parent $(parent).append(this._element);
//Stocke la référence dans this._$this this._$this = $(this._element);
// Invoque la mise à jour forcée à appliquer à toutes les propriétés this.update(true); this._attached = true ;
// Déclenche l’événement associé sur le parent $(parent).trigger("attached", this.getEventData("attached"))
Vous n’êtes pas obligé de remplacer cette fonction. Toutefois, il peut s’avérer nécessaire de la faire pour les éléments composites. Vous trouverez davantage de détails dans la section des exemples.
Remarque :Vous pouvez utiliser ceci._superApply(arguments) pour appeler n'importe quelle méthode de classe de base à partir de n'importe quel remplacement. |
detach() |
Non |
Cette fonction est appelée lorsque l’occurrence du composant est sur le point d’être supprimée de l’élément DOM. La mise en œuvre par défaut effectue les opérations suivantes :
// Supprime l’élément du DOM this._$this.remove(); // Déclenche l’événement detached (dissocié) sur le parent $(parent).trigger("detached", this.getEventData("detached")); |
setProperty(k,v) |
Non |
Cette fonction permet de définir une propriété de l’occurrence. Ces modifications sont placées en mémoire cache et appliquées immédiatement lors de l’appel de la mise à jour update() de chaque image pour chacune des propriétés qui a été modifiée (« dirty »). |
update(force) |
Non |
Cette fonction est appelée à chaque image lorsque le composant fait partie du DOM et est visible. La mise en œuvre par défaut applique toutes les propriétés CSS et les attributs qui ont changé ou si le paramètre force est défini sur true. |
show() |
Non |
Affiche l’occurrence de l’élément. Vous n’avez généralement pas besoin de le remplacer, mais il est possible que vous deviez le faire pour les éléments composites. |
hide() |
Non |
Masque l’occurrence de l’élément. Vous n’avez généralement pas besoin de le remplacer, mais il est possible que vous deviez le faire pour les éléments composites. |
getEventData(e) |
Non |
Renvoie les données personnalisées pour l’événement portant le nom « e ». La mise en œuvre par défaut transmet l’identifiant {id:instance_id} des données pour les événements attached et detached (associés et dissociés). |
destroy() |
Non |
Libère la mémoire lorsque l’occurrence du composant est dissociée du DOM. Vous n’avez généralement pas besoin de remplacer cette fonction. |
applyProperties(e) |
Non |
API d’assistance permettant d’appliquer les propriétés CSS à l’événement e. du wrapper jQuery. |
applyAttributes(e) |
Non |
API d’assistance permettant d’appliquer les attributs à l’événement e. du wrapper jQuery. |
Localisation
La chaîne de catégorie, le nom d’affichage du composant et le nom de propriété peuvent être localisés. Créez un fichier appelé strings.json dans un dossier nommé locale dans le dossier des composants. Indiquez les paires clé-valeur pour toutes les chaînes à localiser et utilisez la clé dans components.js. Pour les autres paramètres régionaux, vous devez fournir les chaînes dans des dossiers correspondants du dossier locale.
Mise en package et distribution de composants HTML5 personnalisés
Les développeurs ou les concepteurs Animate peuvent permettre aux animateurs d’installer et d’utiliser des composants sans codage, en fournissant des composants mis en package prêts à l’emploi. Auparavant, les animateurs devaient apprendre les structures de fichier, effectuer de la programmation et déplacer manuellement les fichiers vers des dossiers spécifiques pour activer les extensions HTML5.
Prérequis
- N’importe quel composant créé par un développeur. Cliquez ici pour obtenir des instructions sur la création de composants.
- Kit d’outils de signature CC Extensions.
Avant d’assembler vos composants, créez un fichier MXI avec les métadonnées de la source et le chemin de destination des composants. Par exemple :
<file source=« jquery-ui-1.12.0 » destination=« $FLASH\HTML5Components\jQueryUI\ » file-type=« ordinary » />
Ces informations sur les fichiers source et de destination sont nécessaires pour activer l’utilitaire d’extensions en vue d’une installation précise de votre composant.
Mise en package de composants
Pour mettre en package les composants HTML5 personnalisés, procédez comme suit :
Pour créer un fichier MXI, entrez le contenu semblable au fichier d’exemple abc.mxi à l’aide d’un éditeur de texte, puis enregistrez-le avec une extension MXI.
Ajoutez votre fichier de composant MXI et d’autres fichiers associés dans un dossier.
Créez un fichier zip d’extension ZXP à l’aide de l’outil de signature CC Extensions (ZXPSignCmd.exe). Utilisez les commandes suivantes dans l’outil ZXP Sign Command pour créer un fichier ZXP :
1. Créez un certificat auto-signé à l'aide de l'option -selfSignedCert.
Vous pouvez ignorer cette étape si vous disposez déjà d’un certificat.
ZXPSignCmd -selfSignedCert US NY MyCompany MyCommonName password FileName.p12
Le fichier FileName.p12 est généré dans le dossier actif.
2. Signez l’extension à l’aide de la commande suivante :
ZXPSignCmd -sign projectName projectName.zxp FileName.p12 password
projectName est le nom du projet d’extension. Dans le dossier actif, un fichier nommé projectName.zxp est généré.
Distribution des composants
Vous pouvez distribuer le fichier de composant mis en package projectName.zxp à n’importe quel utilisateur d’Animate.
Adobe vous recommande de distribuer vos produits via le site web Modules complémentaires d’Adobe. Vous pouvez distribuer des modules complémentaires publiquement (gratuits ou payants) ou en privé (gratuits pour des utilisateurs désignés).
Installation de composants distribués
Les concepteurs ou les développeurs Animate peuvent installer le composant de fichier ZXP distribué à l’aide de l’utilitaire Gérer les extensions.
Créez des animations interactives avec Animate
Animez des illustrations pour des dessins animés, des bannières, des jeux et des contenus web.
