Packageflash.external
Classepublic final class ExternalInterface
HéritageExternalInterface Inheritance Object

Version du langage: ActionScript 3.0
Versions du moteur d'exécution: AIR 1.0 Flash Player 9

La classe ExternalInterface est l'API External, une interface de programmation qui permet une communication directe entre ActionScript et le conteneur Flash Player, par exemple une page HTML avec JavaScript. Adobe recommande l'utilisation de l'API ExternalInterface pour toutes les communications JavaScript-ActionScript.

Vous pouvez appeler une fonction ActionScript dans Flash Player, à l'aide de JavaScript dans la page HTML. La fonction ActionScript peut renvoyer une valeur que JavaScript reçoit immédiatement comme valeur de renvoi de l'appel.

Cette fonctionnalité remplace la méthode fscommand().

Utilisez la classe ExternalInterface pour les combinaisons suivantes de navigateurs et de systèmes d'exploitation :

NavigateurSystème d'exploitationSystème d'exploitation
Internet Explorer 5.0 et versions ultérieuresWindows 
Netscape 8.0 et versions ultérieuresWindows MacOS 
Mozilla 1.7.5 et versions ultérieuresWindows MacOS 
Firefox 1.0 et versions ultérieuresWindows MacOS 
Safari 1.3 et versions ultérieures  MacOS 

Flash Player pour Linux version 9.0.31.0 et supérieure prend en charge la classe ExternalInterface dans les navigateurs suivants :

Navigateur
Mozilla 1.7.x et supérieure
Firefox 1.5.0.7 et versions ultérieures
SeaMonkey 1.0.5 et supérieure

La classe ExternalInterface nécessite la prise en charge, par le navigateur Web de l'utilisateur, d'ActiveX® ou de l'API NPRuntime qui est exposée par certains navigateurs pour les scripts de plug-ins. Même si une combinaison navigateur/système d'exploitation n'apparaît pas dans la liste ci-dessus, elle devrait prendre en charge la classe ExternalInterface si elle gère l'API NPRuntime. Visitez le site http://www.mozilla.org/projects/plugins/npruntime.html.

Remarque : lors de l'incorporation de fichiers SWF dans une page HTML, vérifiez que l'attribut id est défini et que les attributs id et name des balises object et embed ne comportent aucun des caractères suivants : 

. - + * / \

Remarque : Flash Player 9.0.115.0 et versions ultérieures autorisent le caractère . (point) dans les attributs id et name.

Dans Flash Player 10 et les versions ultérieures s'exécutant dans un navigateur, il est possible que vous ne puissiez pas utiliser cette classe par programmation pour ouvrir une fenêtre contextuelle. Certains navigateurs (et configurations de navigateur) peuvent bloquer les fenêtres contextuelles ; il n'est donc pas possible de garantir l'ouverture de toutes les fenêtres contextuelles. Toutefois, pour un résultat optimal, utilisez cette classe pour ouvrir une fenêtre contextuelle uniquement dans le code qui s'exécute comme conséquence directe de l'action d'un utilisateur (par exemple, un événement de type clic de souris ou pression de touche.)

A partir d'ActionScript, vous pouvez effectuer les opérations suivantes sur la page HTML :

A partir de JavaScript, vous pouvez effectuer les opérations suivantes sur la page HTML :

Flash Player ne gère actuellement pas les fichiers SWF intégrés à des formulaires HTML.

Remarque : pour le moment, Adobe AIR ne prend pas en charge la classe ExternalInterface.

Consulter les exemples

Voir aussi

flash.system.fscommand()
Avantages et conditions requises de l'API externe
Utilisation de la classe ExternalInterface
Contrôle de l'accès URL externe

Propriétés publiques
 PropriétéDéfini par
  available : Boolean
[statique] [lecture seule] Indique si ce lecteur se trouve dans un conteneur doté d'une interface externe.
ExternalInterface
 Inheritedconstructor : Object
Référence à l'objet de classe ou à la fonction constructeur d'une occurrence donnée d'un objet.
Object
  marshallExceptions : Boolean = false
[statique] Indique si l'interface externe doit tenter de transmettre des exceptions ActionScript au navigateur en cours et des exceptions JavaScript à Flash Player.
ExternalInterface
  objectID : String
[statique] [lecture seule] Renvoie l'attribut id de la balise object dans Internet Explorer, ou l'attribut name de la balise embed dans Netscape.
ExternalInterface
 Inheritedprototype : Object
[statique] Référence à l'objet prototype d'un objet de classe ou fonction.
Object
Méthodes publiques
 MéthodeDéfini par
  
addCallback(functionName:String, closure:Function):void
[statique] Enregistre une méthode ActionScript comme pouvant être appelée à partir du conteneur.
ExternalInterface
  
call(functionName:String, ... arguments):*
[statique] Appelle une fonction présentée par le conteneur Flash Player en transmettant la valeur zéro ou d'autres arguments.
ExternalInterface
 Inherited
hasOwnProperty(name:String):Boolean
Indique si la propriété spécifiée d'un objet est définie.
Object
 Inherited
isPrototypeOf(theClass:Object):Boolean
Indique si une occurrence de la classe Object figure dans la chaîne de prototype de l'objet spécifié en tant que paramètre.
Object
 Inherited
propertyIsEnumerable(name:String):Boolean
Indique si la propriété spécifiée existe et est énumérable.
Object
 Inherited
setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void
Définit la disponibilité d'une propriété dynamique pour les opérations en boucle.
Object
 Inherited
toString():String
Renvoie la représentation sous forme de chaîne de l'objet spécifié.
Object
 Inherited
valueOf():Object
Renvoie la valeur primitive de l'objet spécifié.
Object
Détails de la propriété
availablepropriété
available:Boolean  [lecture seule]

Version du langage: ActionScript 3.0
Versions du moteur d'exécution: AIR 1.0 Flash Player 9

Indique si ce lecteur se trouve dans un conteneur doté d'une interface externe. Si l'interface externe est disponible, cette propriété est true ; sinon, elle est false.

Remarque : si vous utilisez l'API External avec HTML, assurez-vous toujours que le chargement du code HTML est terminé avant de tenter d'appeler toute méthode JavaScript.



Implémentation
    public static function get available():Boolean

Voir aussi

Utilisation de la classe ExternalInterface
Obtention d'informations sur le conteneur externe

Exemple
L'exemple suivant utilise la propriété available pour déterminer si le lecteur se trouve dans un conteneur doté d'une interface externe. 
package {
       import flash.text.TextField;
       import flash.display.MovieClip;
       import flash.external.ExternalInterface;
     
       public class extint_test extends MovieClip {
         public function extint_test() {
           var isAvailable:Boolean = ExternalInterface.available;
           var availTxt:TextField = new TextField();
           availTxt.text = isAvailable.toString();
           addChild(availTxt);
         }
       }
     }
marshallExceptionspropriété 
public static var marshallExceptions:Boolean = false

Version du langage: ActionScript 3.0
Versions du moteur d'exécution: AIR 1.0 Flash Player 9.0.115.0

Indique si l'interface externe doit tenter de transmettre des exceptions ActionScript au navigateur en cours et des exceptions JavaScript à Flash Player. Vous devez définir explicitement cette propriété sur true pour récupérer les exceptions JavaScript dans ActionScript et les exceptions ActionScript dans JavaScript.

Voir aussi

addCallback()
try..catch..dernière instruction

Exemple
L'exemple suivant crée une fonction ActionScript et l'enregistre avec le navigateur récepteur à l'aide de la méthode addCallback(). La nouvelle fonction émet une exception afin que le code JavaScript qui s'exécute dans le navigateur puisse la récupérer. Cet exemple contient également une instruction try..catch pour récupérer toutes les exceptions émises par le navigateur lors de l'appel de la fonction throwit(). 
package
{
    import flash.external.*
    import flash.net.*;
    import flash.display.*;
    import flash.system.System;
    public class ext_test extends Sprite {
    function ext_test():void {
        ExternalInterface.marshallExceptions = true;
        ExternalInterface.addCallback("g", g);

        try {
        ExternalInterface.call("throwit");
        } catch(e:Error) {
        trace(e)
        }
    }
    function g() { throw new Error("exception from actionscript!!!!") }
    }
}
objectIDpropriété 
objectID:String  [lecture seule]

Version du langage: ActionScript 3.0
Versions du moteur d'exécution: AIR 1.0 Flash Player 9

Renvoie l'attribut id de la balise object dans Internet Explorer, ou l'attribut name de la balise embed dans Netscape.



Implémentation
    public static function get objectID():String

Voir aussi

Utilisation de la classe ExternalInterface
Obtention d'informations sur le conteneur externe
Détails de la méthode
addCallback()méthode
public static function addCallback(functionName:String, closure:Function):void

Version du langage: ActionScript 3.0
Versions du moteur d'exécution: AIR 1.0 Flash Player 9

Enregistre une méthode ActionScript comme pouvant être appelée à partir du conteneur. Lorsque l'invocation de addCallBack() a réussi, la fonction enregistrée dans Flash Player peut être appelée par le code JavaScript ou ActiveX dans le conteneur.

Remarque : pour le contenu local s'exécutant dans un navigateur, les appels à la méthode ExternalInterface.addCallback() fonctionneront uniquement si le fichier SWF et la page web le contenant se trouvent dans le sandbox de sécurité approuvé en local. Pour plus d'informations, consultez les références suivantes :

Paramètres

functionName:String — Nom utilisé par le conteneur pour appeler la fonction.
 
closure:Function — La fermeture de fonction à appeler. Il peut s'agir d'une fonction autonome ou d'une méthode de fermeture qui référence une méthode d'occurrence d'objet. En transmettant une fermeture de méthode, vous pouvez dirigez le rappel vers une méthode d'une occurrence d'un objet particulier.


Valeur émise
Error — Le conteneur ne prend pas en charge les appels entrants. Les appels entrants ne sont gérés que dans Internet Explorer pour Windows et les navigateurs qui utilisent l'API NPRuntime, tels que Mozilla 1.7.5 et versions ultérieures, ou Firefox 1.0 et versions ultérieures.
 
SecurityError — Un rappel avec le nom spécifié a déjà été ajouté par ActionScript dans un sandbox auquel vous n'avez pas accès. Il vous est impossible de le remplacer. Pour contourner ce problème, réécrivez le code ActionScript qui appelait au départ la méthode addCallback() de sorte qu'il appelle également la méthode Security.allowDomain().
 
SecurityError — L'environnement conteneur appartient à un sandbox de sécurité auquel le code effectuant l'appel n'a pas accès. Pour résoudre ce problème, exécutez la procédure suivante :
  1. Dans la balise object associée au fichier SWF intégré à la page HTML, définissez le paramètre suivant :

    <param name="allowScriptAccess" value="always" />

  2. Dans le fichier SWF, ajoutez le code ActionScript suivant :

    flash.system.Security.allowDomain(sourceDomain )

Voir aussi

flash.system.Security.allowDomain()
Utilisation de la classe ExternalInterface
Appel du code ActionScript à partir du conteneur
call()méthode 
public static function call(functionName:String, ... arguments):*

Version du langage: ActionScript 3.0
Versions du moteur d'exécution: AIR 1.0 Flash Player 9

Appelle une fonction présentée par le conteneur Flash Player en transmettant la valeur zéro ou d'autres arguments. Si la fonction n'est pas disponible, l'appel renvoie null ; sinon, elle renvoie la valeur fournie par la fonction. La récursion n'est pas autorisée dans les navigateurs Opera et Netscape. Dans ces derniers, un appel récursif produit une réponse null. (La récursion est prise en charge par les navigateurs Internet Explorer et Firefox.)

Si le conteneur correspond à une page HTML, cette méthode appelle une fonction JavaScript dans un élément script.

Si le conteneur est un autre conteneur de type ActiveX, cette méthode distribue l'événement FlashCall ActiveX au nom spécifié ; le conteneur traite alors l'événement.

Si le conteneur renferme le plug-in Netscape, vous pouvez soit écrire le support personnalisé pour la nouvelle interface NPRuntime, soit intégrer un contrôle HTML et intégrer Flash Player au contrôle HTML. Si vous intégrez un contrôle HTML, vous pouvez communiquer avec Flash Player via une interface JavaScript qui dialogue avec l'application conteneur native.

Remarque : pour du contenu local s'exécutant dans un navigateur, les appels à la méthode ExternalInterface.call() ne sont autorisés que si le fichier SWF et la page Web qui le contient (le cas échéant) se trouvent dans le sandbox de sécurité local approuvé. Vous pouvez également empêcher un fichier SWF d'utiliser cette méthode en définissant le paramètre allowNetworking des balises object et embed dans la page HTML qui stocke le contenu SWF. Pour plus d'informations, consultez les références suivantes :

Dans Flash Player 10 et Flash Player 9 Mise à jour 5, certains navigateurs Web ne prennent pas en charge cette méthode si un bloqueur de fenêtres publicitaires intempestives est activé. Dans ce cas, l'appel de cette méthode aboutit uniquement en réponse à un événement utilisateur (par exemple, un événement de type clic de souris ou pression de touche).

Paramètres

functionName:String — Nom alphanumérique de la fonction à appeler dans le conteneur. L'utilisation d'un nom de fonction non alphanumérique entraîne une erreur d'exécution (erreur 2155). Vous pouvez utiliser un bloc try..catch pour gérer cette erreur.
 
... arguments — Arguments à transmettre à la fonction dans le conteneur. Vous pouvez ne spécifier aucun paramètre ou en spécifier plusieurs en les séparant par des virgules. Ces paramètres peuvent être de tout type de donnée ActionScript. Si vous faites appel à une fonction JavaScript, les types ActionScript sont automatiquement convertis en types JavaScript. Si l'appel s'adresse à un autre conteneur ActiveX, les paramètres sont encodés dans le message de requête.

Valeur renvoyée
* — Réponse émanant du conteneur. Si l'appel a échoué (imaginons que cette fonction ne figure pas dans le conteneur, qu'un problème de sécurité soit survenu, que l'interface n'est pas disponible ou encore qu'une erreur de récursivité s'est produite avec un navigateur Netscape ou Opera), la valeur null est renvoyée et une erreur est signalée.

Valeur émise
Error — Le conteneur ne prend pas en charge les appels sortants. Les appels sortants ne sont gérés que dans Internet Explorer pour Windows et les navigateurs qui utilisent l'API NPRuntime, tels que Mozilla 1.7.5 et versions ultérieures, ou Firefox 1.0 et versions ultérieures.
 
SecurityError — L'environnement conteneur appartient à un sandbox de sécurité auquel le code effectuant l'appel n'a pas accès. Pour résoudre ce problème, exécutez la procédure suivante :
  1. Dans la balise object associée au fichier SWF intégré à la page HTML, définissez le paramètre suivant :

    <param name="allowScriptAccess" value="always" />

  2. Dans le fichier SWF, ajoutez le code ActionScript suivant :

    flash.system.Security.allowDomain(sourceDomain )

Voir aussi

Utilisation de la classe ExternalInterface
Appel de code externe à partir d'ActionScript
Contrôle de l'accès URL externe
Exemples Utilisation des exemples
ExternalInterfaceExample.as

L'exemple suivant illustre l'envoi des données entre Flash Player et un conteneur HTML. 
package {
    import flash.display.Sprite;
    import flash.events.*;
    import flash.external.ExternalInterface;
    import flash.text.TextField;
    import flash.utils.Timer;
    import flash.text.TextFieldType;
    import flash.text.TextFieldAutoSize;

    public class ExternalInterfaceExample extends Sprite {
        private var input:TextField;
        private var output:TextField;
        private var sendBtn:Sprite;

        public function ExternalInterfaceExample() {
            input = new TextField();
            input.type = TextFieldType.INPUT;
            input.background = true;
            input.border = true;
            input.width = 350;
            input.height = 18;
            addChild(input);

            sendBtn = new Sprite();
            sendBtn.mouseEnabled = true;
            sendBtn.x = input.width + 10;
            sendBtn.graphics.beginFill(0xCCCCCC);
            sendBtn.graphics.drawRoundRect(0, 0, 80, 18, 10, 10);
            sendBtn.graphics.endFill();
            sendBtn.addEventListener(MouseEvent.CLICK, clickHandler);
            addChild(sendBtn);

            output = new TextField();
            output.y = 25;
            output.width = 450;
            output.height = 325;
            output.multiline = true;
            output.wordWrap = true;
            output.border = true;
            output.text = "Initializing...\n";
            addChild(output);

            if (ExternalInterface.available) {
                try {
                    output.appendText("Adding callback...\n");
                    ExternalInterface.addCallback("sendToActionScript", receivedFromJavaScript);
                    if (checkJavaScriptReady()) {
                        output.appendText("JavaScript is ready.\n");
                    } else {
                        output.appendText("JavaScript is not ready, creating timer.\n");
                        var readyTimer:Timer = new Timer(100, 0);
                        readyTimer.addEventListener(TimerEvent.TIMER, timerHandler);
                        readyTimer.start();
                    }
                } catch (error:SecurityError) {
                    output.appendText("A SecurityError occurred: " + error.message + "\n");
                } catch (error:Error) {
                    output.appendText("An Error occurred: " + error.message + "\n");
                }
            } else {
                output.appendText("External interface is not available for this container.");
            }
        }
        private function receivedFromJavaScript(value:String):void {
            output.appendText("JavaScript says: " + value + "\n");
        }
        private function checkJavaScriptReady():Boolean {
            var isReady:Boolean = ExternalInterface.call("isReady");
            return isReady;
        }
        private function timerHandler(event:TimerEvent):void {
            output.appendText("Checking JavaScript status...\n");
            var isReady:Boolean = checkJavaScriptReady();
            if (isReady) {
                output.appendText("JavaScript is ready.\n");
                Timer(event.target).stop();
            }
        }
        private function clickHandler(event:MouseEvent):void {
            if (ExternalInterface.available) {
                ExternalInterface.call("sendToJavaScript", input.text);
            }
        }
    }
}
Afin de tester l'ancien code ActionScript, incorporez le fichier SWF généré à l'aide du modèle HTML suivant : 
<!-- saved from url=(0014)about:internet -->
 <html lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 <title>ExternalInterfaceExample</title>
 <script language="JavaScript">
     var jsReady = false;
     function isReady() {
         return jsReady;
     }
     function pageInit() {
         jsReady = true;
         document.forms["form1"].output.value += "\n" + "JavaScript is ready.\n";
     }
     function thisMovie(movieName) {
         if (navigator.appName.indexOf("Microsoft") != -1) {
             return window[movieName];
         } else {
             return document[movieName];
         }
     }
     function sendToActionScript(value) {
         thisMovie("ExternalInterfaceExample").sendToActionScript(value);
     }
     function sendToJavaScript(value) {
         document.forms["form1"].output.value += "ActionScript says: " + value + "\n";
     }
 </script>
 </head>
 <body onload="pageInit();">
 
     <object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
             id="ExternalInterfaceExample" width="500" height="375"
             codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab">
         <param name="movie" value="ExternalInterfaceExample.swf" />
         <param name="quality" value="high" />
         <param name="bgcolor" value="#869ca7" />
         <param name="allowScriptAccess" value="sameDomain" />
         <embed src="ExternalInterfaceExample.swf" quality="high" bgcolor="#869ca7"
             width="500" height="375" name="ExternalInterfaceExample" align="middle"
             play="true" loop="false" quality="high" allowScriptAccess="sameDomain"
             type="application/x-shockwave-flash"
             pluginspage="http://www.macromedia.com/go/getflashplayer">
         </embed>
     </object>
 
     <form name="form1" onsubmit="return false;">
         <input type="text" name="input" value="" />
         <input type="button" value="Send" onclick="sendToActionScript(this.form.input.value);" /><br />
         <textarea cols="60" rows="20" name="output" readonly="true">Initializing...</textarea>
     </form>
 
 </body>
 </html>



© 2004-2008 Adobe Systems Incorporated. All rights reserved.
Thu Jan 8 2009, 03:00 AM -08:00