| Package | flash.external |
| Classe | public final class ExternalInterface |
| Héritage | ExternalInterface  Object |
| Version du langage: | ActionScript 3.0 |
| Versions du moteur d’exécution: | AIR 1.0, Flash Player 9, Flash Lite 4 |
La classe ExternalInterface permet d’appeler une fonction ActionScript dans le moteur d’exécution de Flash à 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 :
| Navigateur | Système d’exploitation | Système d’exploitation |
|---|---|---|
| Internet Explorer 5.0 et versions ultérieures | Windows | |
| Netscape 8.0 et versions ultérieures | Windows | MacOS |
| Mozilla 1.7.5 et versions ultérieures | Windows | MacOS |
| Firefox 1.0 et versions ultérieures | Windows | 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’intégration 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 concernant les applications de Flash Player : Flash Player 9.0.115.0 et les versions ultérieures autorisent l’utilisation du caractère . (point) dans les attributs id et name.
Remarque concernant les applications de Flash Player : 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 :
- appeler toute fonction JavaScript ;
- transmettre un nombre illimité d’arguments, quel que soit leur nom ;
- transmettre divers types de données (Boolean, Number, String, etc.) ;
- recevoir une valeur renvoyée par la fonction JavaScript.
A partir de JavaScript, vous pouvez effectuer les opérations suivantes sur la page HTML :
- appeler une fonction ActionScript ;
- transmettre des arguments en utilisant la notation d’appel de fonction standard ;
- renvoyer une valeur à la fonction JavaScript.
Remarque concernant les applications de Flash Player : Flash Player ne prend actuellement pas en charge les fichiers SWF intégrés à des formulaires HTML.
Remarque concernant les applications d’AIR : dans Adobe AIR, la classe ExternalInterface peut être utilisée pour communiquer entre JavaScript dans une page HTML chargée dans un contrôle HTMLLoader et ActionScript dans un contenu SWF incorporé à cette page HTML.
Plus d’exemples
Exemple d’API externe : communications entre ActionScript et JavaScript dans un navigateur Web
Contrôle de l’accès URL externe
Informations complémentaires
Principes de base de l’utilisation de l’API externe
Avantages de l’API externe et conditions requises
Format XML de l’API externe
Eléments de l’API associés
Masquer les propriétés publiques héritées
Afficher les propriétés publiques héritées| 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 | ||
 | constructor : 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 actuel et des exceptions JavaScript au lecteur. | 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 | ||
| Méthode | Défini par | ||
|---|---|---|---|
[statique]
Enregistre une méthode ActionScript comme pouvant être appelée à partir du conteneur. | ExternalInterface | ||
[statique]
Appelle une fonction présentée par le conteneur SWF en transmettant la valeur zéro ou d’autres arguments. | ExternalInterface | ||
|
Indique si la propriété spécifiée d’un objet est définie. | Object | |
|
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 | |
|
Indique si la propriété spécifiée existe et est énumérable. | Object | |
|
Définit la disponibilité d’une propriété dynamique pour les opérations en boucle. | Object | |
|
Renvoie la représentation de chaîne de cet objet, formatée selon les paramètres régionaux en vigueur. | Object | |
|
Renvoie la représentation sous forme de chaîne de l’objet spécifié. | Object | |
|
Renvoie la valeur primitive de l’objet spécifié. | Object | |
available | propriété |
available:Boolean [lecture seule] | Version du langage: | ActionScript 3.0 |
| Versions du moteur d’exécution: | AIR 1.0, Flash Player 9, Flash Lite 4 |
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 externe 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():BooleanPlus d’exemples
Exemple ( Comment utiliser cet exemple )
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);
}
}
}
marshallExceptions | proprié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, Flash Lite 4 |
Indique si l’interface externe doit tenter de transmettre des exceptions ActionScript au navigateur actuel et des exceptions JavaScript au lecteur. 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.
Eléments de l’API associés
Exemple ( Comment utiliser cet exemple )
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!!!!") }
}
}
objectID | propriété |
objectID:String [lecture seule] | Version du langage: | ActionScript 3.0 |
| Versions du moteur d’exécution: | AIR 1.0, Flash Player 9, Flash Lite 4 |
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():StringPlus d’exemples
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, Flash Lite 4 |
Enregistre une méthode ActionScript comme pouvant être appelée à partir du conteneur. Lorsque l’appel de addCallBack() a abouti, la fonction enregistrée dans le lecteur 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() fonctionnent uniquement si le fichier SWF et la page Web le contenant se trouvent dans le sandbox de sécurité approuvé localement. Pour plus d’informations, voir la rubrique du Pôle de développement d’Adobe Flash Player : Sécurité (disponible en anglais uniquement).
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.
Remarque : répéter |
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 :
|
Plus d’exemples
Eléments de l’API associés
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, Flash Lite 4 |
Appelle une fonction présentée par le conteneur SWF 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 le lecteur au contrôle HTML. Si vous intégrez un contrôle HTML, vous pouvez communiquer avec le lecteur via une interface JavaScript qui dialogue avec l’application conteneur native.
Remarque : pour le 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é approuvé localement. 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, voir la rubrique du Pôle de développement Flash Player : Sécurité (disponible en anglais uniquement).
Remarque concernant les applications de Flash Player : 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 à l’événement d’un utilisateur (notamment lorsque celui-ci clique sur une souris ou appuie sur une 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.
|
* — 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 :
|
Plus d’exemples
Appel de code externe à partir d’ActionScript
Contrôle de l’accès URL externe
Exemple ( Comment utiliser cet exemple )
//
// Requires:
// - A Flash Professional Label component on the Stage with an instance name of "lbl".
// - A Flash Professional Button component on the Stage with an instance name of "button".
//
var xmlResponse:String = "<invoke name=\"isReady\" returntype=\"xml\"><arguments><number>1</number><number>" + stage.stageWidth + "</number><number>" + stage.stageHeight + "</number></arguments></invoke>";
lbl.text = "ExternalInterface.available: " + ExternalInterface.available;
lbl.width = 200;
button.enabled = ExternalInterface.available;
button.addEventListener(MouseEvent.CLICK, button_click);
function button_click(evt:MouseEvent):void {
ExternalInterface.call("alert", xmlResponse);
}
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;
import flash.system.Security;
public class ExternalInterfaceExample extends Sprite
{
private var input:TextField;
private var output:TextField;
private var sendBtn:Sprite;
public function ExternalInterfaceExample()
{
// constructor code
Security.allowDomain("*");
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");
output.appendText("ExternalInterface.objectID = " + ExternalInterface.objectID + "\n");
Timer(event.target).stop();
}
}
private function clickHandler(event:MouseEvent):void {
if (ExternalInterface.available) {
ExternalInterface.call("sendToJavaScript", input.text);
}
}
}
}
<!-- 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 sendToActionScript(value) {
document.getElementById("ExternalInterfaceExample").sendToActionScript(value);
}
function sendToJavaScript(value) {
document.forms["form1"].output.value += "ActionScript says: " + value + "\n";
}
</script>
</head>
<body onload="pageInit();">
<object id="ExternalInterfaceExample" name="ExternalInterfaceExample"
type="application/x-shockwave-flash" data="ExternalInterfaceExample.swf" width="550" height="400">
<param name="movie" value="ExternalInterfaceExample.swf"/>
<param name="quality" value="high"/>
<param name="allowscriptaccess" value="always"/>
<a href="http://www.adobe.com/go/getflash">
<img src="http://www.adobe.com/images/shared/download_buttons/get_flash_player.gif" alt="Get Adobe Flash player"/>
</a>
</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>
Tue Jun 12 2018, 09:30 AM Z