Consultez cet article pour savoir comment créer des composants personnalisés pour les documents HTML5 Canvas.

Animate CC 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 CC.

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.

Remarque :

Une définition de composant comprend également des ressources associées à la localisation.

componentsJS
Exemple de configuration de dossier d’une catégorie de composants personnalisée

Animate CC recherche dans les dossiers suivants les composants HTML5 personnalisés et les charge au démarrage :

• Windows :

<AppData>/Local/Adobe/Adobe Animate CC 2017/fr_FR/Configuration/HTML5Components

 

• MAC :

 

~/Library/Application Support/Adobe/Animate CC 2017/fr_FR/Configuration/HTML5Components/

Remarque :

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 CC 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

metadata-code
Exemple de métadonnées pour un composant vidéo.

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 :

Nom

Obligatoire

Description

ClassName

Oui

Nom de 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

Numéro de version du composant. Il est 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 de détails 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 lorsqu’une 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

Taille 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 utilisez des bibliothèques hébergées dans les paramètres de publication. Sinon, 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 une 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 CC ; 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 :

  1. Nom : nom affiché dans l’inspecteur des propriétés pour cette propriété. Il doit s’agir d’un nom convivial. Il peut être localisé.
  2. Variable : Nom interne utilisé pour cette propriété. Les valeurs configurées sont disponibles avec ce nom de variable au moment de l’exécution. Ce sujet sera abordé plus en détail dans des sections ultérieures.
  3. Type : spécifie le type de la propriété. Dans Animate CC, les types suivants sont pris en charge :
    1. Booléen - Case à cocher dans l’inspecteur des propriétés.
    2. Nombre - Case numérique dans l’inspecteur des propriétés.
    3. Chaîne - Zone de texte de l’inspecteur des propriétés.
    4. Liste - Permet à l’utilisateur de configurer un tableau de valeurs.
    5. Collection - Permet aux utilisateurs de configurer une liste de paires <clé, valeur>. (Voir la liste déroulante)
    6. Chemin du fichier - Permet à l’utilisateur de parcourir les fichiers locaux et d’en sélectionner un. La valeur de la chaîne est fournie au moment de l’exécution. Le fichier est automatiquement copié dans la sortie publiée dans le dossier « assets » et le chemin d’accès relatif est rendu disponible au moment de l’exécution.
    7. Chemin d’accès à l’image - Permet à l’utilisateur de parcourir les images et d’en sélectionner une. Le fichier est automatiquement copié dans la sortie publiée du dossier d’images configuré et le chemin d’accès relatif est rendu disponible au moment de l’exécution.
    8. Chemin d’accès au contenu vidéo : permet à l’utilisateur de parcourir et de choisir n’importe quelle source vidéo au format web (mp4, ogg, ogv, webm). L’élément configuré est copié dans le dossier « videos » dans la sortie publiée.
    9. Couleur - Sélecteur de couleurs dans l’inspecteur des propriétés.

4. Valeur par défaut : valeur par défaut de la propriété. La valeur par défaut et la propriété doivent être du même type.

Source de composant

Chaque composant doit disposer d’un fichier source associé qui fournit le code permettant de gérer :

  • 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.

 

AnWidget
Modèle HTML

Le code HTML contient ces sections (à l’exception de la balise div de préchargement) par défaut :

animation_container
Sections HTML par défaut (à l’exception de la balise div de préchargement)

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.

Remarque :

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 CC 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

component_lifecycle
Cycle de vie du composant

  1. L’occurrence de composant est créée lorsque le DOM est conçu pour le conteneur.

  2. 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.

  3. 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.

  4. 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 la fonction this._superApply(arguments) pour invoquer une méthode de classe de base depuis 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.

localization
Chaîne .json

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

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 : 

  1. 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.

    Download

    Telechargement

  2. Ajoutez votre fichier de composant MXI et d’autres fichiers associés dans un dossier.

    Add-MXI-file-to-component
  3. 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 autosigné à l’aide de l’option -selfSignedCert.

    Vous pouvez ignorer cette étape si vous disposez déjà d’un certificat.

    Self-signature
    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 :

    Create-ZXP-file
    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.

Remarque :

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). En savoir plus sur le partage de produits en privé.

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.

Pour plus d’informations, voir Installation de composants distribués

Ce produit est distribué sous licence Creative Commons Attribution - Pas d’utilisation commerciale - Partage à l’identique 3.0 non transposé  Les publications Twitter™ et Facebook ne sont pas couvertes par les dispositions Creative Commons.

Mentions légales   |   Politique de confidentialité en ligne