Utilisation de l'API JavaScript



L'API Flash JavaScript permet d’écrire des scripts destinés à effectuer plusieurs actions dans l’environnement de développement Flash (pendant que l'utilisateur exécute le programme Flash). Cette fonctionnalité est différente du langage ActionScript qui permet d’écrire des scripts destinés à effectuer des actions dans l'environnement Flash Player (pendant la lecture d’un fichier SWF). Elle diffère également des commandes JavaScript utilisables dans les pages qui s'affichent dans un navigateur Web.

Grâce à l'utilisation de l'API JavaScript, vous écrivez des scripts d'application Flash qui permettent de simplifier le processus de programmation. Par exemple, vous pouvez écrire des scripts pour automatiser des tâches répétitives ou ajouter des outils personnalisés au panneau Outils.

L’API JavaScript de Flash a été conçue sur le même modèle que les API JavaScript d'Adobe® Dreamweaver® et d'Adobe® Fireworks® (elles-mêmes basées sur l’API JavaScript de Netscape). L’API JavaScript de Flash repose sur un modèle d'objet document (DOM, Document Object Model) qui permet d’accéder aux documents Flash à l’aide d’objets créés en JavaScript. Elle comporte tous les éléments de l’API JavaScript de Netscape, ainsi que le DOM de Flash. Les objets qui sont ajoutés, ainsi que leurs méthodes et propriétés, sont décrits dans le présent document. Vous pouvez utiliser tous les éléments du langage JavaScript natif dans un script Flash, mais seuls les éléments dont l’utilisation est logique dans le contexte d’un document Flash prendront effet.

L'API JavaScript contient également un certain nombre de méthodes qui permettent d’implémenter des extensions par une combinaison de code JavaScript et C personnalisé. Pour plus d'informations, consultez la section Extensibilité de niveau C.

L’interpréteur JavaScript de Flash est la version 1.5 du moteur SpiderMonkey de Mozilla, disponible sur le Web à l’adresse suivante www.mozilla.org/js/spidermonkey/. SpiderMonkey, l’une des deux implémentations de référence du langage JavaScript développé par Mozilla.org, est intégré au navigateur Mozilla.

SpiderMonkey implémente le langage JavaScript de base tel qu’il est défini par la spécification ECMAScript (ECMA-262) édition 3 et est conforme à tous les niveaux à celle-ci. Seuls les objets hôte propres au navigateur (qui ne figurent pas dans la spécification ECMA-262) ne sont pas pris en charge. De même, de nombreux guides de référence JavaScript établissent une distinction entre le langage JavaScript de base et le langage JavaScript côté client (associé au navigateur). Seul le langage JavaScript de base s'applique à l'interpréteur Flash JavaScript.

    Création de fichiers JSFL

    Pour créer et modifier des fichiers JavaScript Flash, ou fichiers JSFL, utilisez Adobe Flash CS4 Professional ou un éditeur de texte de votre choix. Si vous utilisez Flash, ces fichiers auront par défaut l’extension .jsfl. Pour rédiger un script, sélectionnez Fichier > Nouveau > Fichier Flash JavaScript.

    Il est également possible de créer un fichier JSFL en sélectionnant des commandes dans le panneau Historique. Puis, cliquez sur le bouton Enregistrer du panneau Historique ou choisissez Enregistrer comme commande dans le menu. Le fichier de commandes est alors enregistré dans le dossier Commands avec l’extension JSFL (voir Enregistrement des fichiers JSFL). Vous pouvez ensuite l’ouvrir et le modifier comme tout autre fichier script.

    Le panneau Historique fournit lui aussi d'autres options utiles. Vous pouvez copier les commandes sélectionnées dans le presse-papiers et visualiser les commandes JavaScript qui sont générées pendant votre travail dans Flash.

    Pour copier des commandes dans le presse-papiers à partir du panneau Historique :

    1. Sélectionnez une ou plusieurs commandes dans le panneau Historique.

    2. Effectuez l'une des opérations suivantes :

      • Cliquez sur le bouton Copier.

      • Dans le menu du panneau, sélectionnez Copier ces étapes.

    Pour visualiser les commandes JavaScript dans le panneau Historique :

    • Dans le menu du panneau, choisissez Affichage > JavaScript dans le panneau.

    Enregistrement des fichiers JSFL

    Vous pouvez rendre les scripts JSFL disponibles dans l'environnement de programmation Flash en les stockant dans un ou plusieurs sous-dossiers du dossier Configuration. Par défaut, le dossier Configuration se trouve à l'emplacement suivant :

    • Windows® Vista™ :

      lecteur d'amorçage\Utilisateurs\nom d'utilisateur\Local Settings\Application Data\Adobe\Flash CS4\langue\Configuration\

    • Windows XP :

      lecteur d'amorçage\Documents and Settings\nom d'utilisateur\Local Settings\Application Data\Adobe\Flash CS4\langue\Configuration\

    • Mac OS® X :

      DD Macintosh/Users/nom d'utilisateur/Library/Application Support/Adobe/Flash CS4/langue/Configuration/

    Pour déterminer l'emplacement du dossier Configuration, utilisez fl.configDirectory ou fl.configURI, comme dans l'exemple suivant : 

    // store directory to a variable  
var configDir = fl.configDirectory; 
// display directory in the Output panel 
fl.trace(fl.configDirectory);

    Dans le dossier Configuration, les dossiers suivants peuvent contenir des scripts auxquels vous pouvez accéder dans l'environnement de programmation : Behaviors (pour prendre en charge l'interface utilisateur des comportements), Commands (pour les scripts qui figurent dans le menu Commandes), JavaScript (pour les scripts utilisés par l'Assistant de script), Tools (pour les outils extensibles du panneau Outils) et WindowSWF (pour les panneaux qui s'affichent dans le menu Fenêtres). Ce document aborde les scripts utilisés pour les commandes et les outils.

    Si vous modifiez un script dans le dossier Commands, il est immédiatement disponible dans Flash. Si vous modifiez un script pour un outil extensible, fermez et redémarrez Flash, ou utilisez la commande fl.reloadTools(). Toutefois, si vous avez utilisé un script pour ajouter un outil extensible au panneau Outils puis que vous modifiez ce script, supprimez l'outil du panneau Outils puis ajoutez-le de nouveau, ou fermez Flash et redémarrez-le, pour que l'outil modifié soit disponible.

    Pour être accessibles à partir de l’environnement de programmation, les fichiers de commandes et d'outils peuvent être stockés en deux endroits différents.

    • Pour les scripts qui prennent la forme d'éléments du menu Commandes, enregistrez les fichiers JSFL dans le dossier Commands qui se trouve à l'emplacement suivant :

      Système d'exploitation

      Emplacement

      Windows Vista

      lecteur d'amorçage\Users\nom d'utilisateur\Local Settings\Application Data\Adobe\Flash CS4\langue\Configuration\Commands

      Windows XP

      lecteur d'amorçage\Documents and Settings\utilisateur\Local Settings\Application Data\Adobe\ FlashCS4\langue\Configuration\Commands

      Mac OS X

      Disque dur Macintosh/Utilisateurs/utilisateur/Library/Application Support/Adobe/FlashCS4/langue/Configuration/Commands

    • Pour les scripts qui prennent la forme d'outils extensibles dans le panneau Outils, enregistrez les fichiers JSFL dans le dossier Tools qui se trouve à l'emplacement suivant :

      Système d'exploitation

      Emplacement

      Windows Vista

      lecteur d'amorçage\Users\nom d'utilisateur\Local Settings\Application Data\Adobe\Flash CS4\langue\Configuration\Tools

      Windows XP

      lecteur d'amorçage\Documents and Settings\utilisateur\Local Settings\Application Data\Adobe\FlashCS4\langue\Configuration\Tools

      Mac OS X

      Disque dur Macintosh/Utilisateurs/utilisateur/Library/Application Support/Adobe/FlashCS4/langue/Configuration/Tools

    Si d'autres fichiers doivent accompagner un fichier JSFL, par exemple des fichiers XML, enregistrez-les dans le même répertoire que ce fichier JSFL.

    Exécution des scripts

    Il existe plusieurs manières d'exécuter des scripts. Les plus courantes sont développées dans la section ci-dessous.

    Pour exécuter un script affiché ou en cours de modification :

    • Cliquez du bouton droit (touche Commande sous Macintosh) et choisissez Exécuter le script.

    • Cliquez sur l'icône Exécuter le script de la barre d'outils de la fenêtre du script.

    Cette option vous permet d'exécuter un script avant de l'avoir enregistré. Elle vous permet également d'exécuter un script même si aucun fichier FLA n'est ouvert.

    Pour exécuter un script stocké dans le dossier Commands, effectuez l'une des actions suivantes :

    • Dans l'environnement de programmation, choisissez Commandes > Nom du script.

    • Utilisez un raccourci clavier que vous aurez attribué au script. Pour attribuer un raccourci clavier, utilisez Edition > Raccourcis clavier, puis choisissez Commandes du menu dessin dans la liste déroulante Commandes. Développez le noeud Commandes de l'arborescence afin d'afficher la liste des scripts disponibles.

    Pour exécuter un script de commandes qui ne réside pas dans le dossier Commands, effectuez l'une des actions suivantes :

    • Dans l'environnement de programmation, choisissez Commandes > Exécuter une commande, puis sélectionnez le script à exécuter.

    • Depuis un script, utilisez la commande fl.runScript().

    • Dans le système de fichiers, double-cliquez sur le fichier de script.

    Pour ajouter dans le panneau Outils un élément implémenté dans un fichier JSFL :

    1. Copiez le fichier JSFL de cet outil (ainsi que les éventuels autres fichiers associés) dans le dossier Tools (voir Enregistrement des fichiers JSFL).

    2. Choisissez Edition > Personnaliser le panneau Outils (Windows) ou Flash > Personnaliser le panneau Outils (Macintosh).

    3. Ajoutez le nouvel outil à la liste des outils disponibles.

    4. Cliquez sur OK.

    Vous pouvez ajouter des commandes individuelles de l'API JavaScript dans un fichier ActionScript à l’aide de la fonction MMExecute() décrite dans le Guide de référence du langage ActionScript 3.0. Toutefois, la fonction MMExecute() n’est exécutée que dans le contexte d’un élément d’interface utilisateur personnalisé, par exemple comme composant de l'inspecteur Propriétés, ou dans un panneau SWF au sein de l’environnement de programmation. Même si elles sont appelées par ActionScript, les commandes API JavaScript sont inopérantes dans Flash Player ou hors de l'environnement de programmation.

    Pour lancer une commande à partir d'un script ActionScript :

    • Employez la syntaxe suivante (vous pouvez concaténer plusieurs commandes en une seule chaîne) :

      MMExecute(Javascript command string);

      Vous pouvez également exécuter un script à partir de la ligne de commande.

    Pour exécuter un script à partir de la ligne de commande de Windows :

    • Utilisez la syntaxe suivante (en ajoutant les informations requises concernant le chemin d'accès) :

      "flash.exe" myTestFile.jsfl

    Pour exécuter un script à partir de l'application « Terminal » sur Macintosh :

    • Utilisez la syntaxe suivante (en ajoutant les informations requises concernant le chemin d'accès) :

      osascript -e 'tell application "flash" to open alias "Mac OS X:Users:user:myTestFile.jsfl" '

      La commande osascript peut elle aussi exécuter du code AppleScript dans un fichier. Par exemple, vous pouvez placer le texte suivant dans un fichier nommé myScript :

      tell application "flash" 
open alias "Mac OS X:Users:user:myTestFile.jsfl" 
end tell

      Ensuite, pour exécuter le script, utilisez la commande suivante :

      osascript myScript