| Paket | flash.external |
| Klasse | public final class ExternalInterface |
| Vererbung | ExternalInterface  Object |
| Sprachversion: | ActionScript 3.0 |
| Laufzeitversionen: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Mit der ExternalInterface-Klasse können Sie eine ActionScript-Funktion in der Flash-Laufzeitumgebung aufrufen, wenn Sie JavaScript auf der HTML-Seite verwenden. Die ActionScript-Funktion gibt dann einen Wert zurück, den JavaScript unmittelbar als Rückgabewert des Aufrufs entgegennimmt.
Diese Funktionalität ersetzt die Methode fscommand().
Verwenden Sie die ExternalInterface-Klasse in den folgenden Kombinationen aus Browser und Betriebssystem:
| Browser | Betriebssystem | Betriebssystem |
|---|---|---|
| Internet Explorer ab Version 5.0 | Windows | |
| Netscape ab Version 8.0 | Windows | MacOS |
| Mozilla ab Version 1.7.5 | Windows | MacOS |
| Firefox ab Version 1.0 | Windows | MacOS |
| Safari ab Version 1.3 | MacOS |
Flash Player für Linux ab Version 9.0.31.0 unterstützt die ExternalInterface-Klasse in den folgenden Browsern:
| Browser |
|---|
| Mozilla ab Version 1.7.x |
| Firefox ab Version 1.5.0.7 |
| SeaMonkey ab Version 1.0.5 |
Die ExternalInterface-Klasse erfordert, dass der Webbrowser des Benutzers entweder ActiveX® oder die NPRuntime-API unterstützt, die von einigen Browsern für das Plug-In-Scripting verwendet wird. Auch wenn eine Kombination aus Browser und Betriebssystem oben nicht aufgeführt ist, sollte sie die ExternalInterface-Klasse unterstützen, sofern die NPRuntime-API unterstützt wird. Weitere Informationen finden Sie unter http://www.mozilla.org/projects/plugins/npruntime.html.
Hinweis: Achten Sie beim Einbetten von SWF-Dateien in HTML-Seiten darauf, dass das id-Attribut gesetzt ist und das id- und name -Attribut des object- und embed-Tags die folgenden Zeichen nicht enthalten:
. - + * / \
Hinweis für Flash Player-Anwendungen: In Flash Player ab Version 9.0.115.0 ist das Zeichen . (Punkt) innerhalb des id- und name-Attributs zulässig.
Hinweis für Flash Player-Anwendungen: Wenn Flash Player 10 oder höher in einem Browser ausgeführt wird, ist das programmgesteuerte Öffnen von Popupfenstern mithilfe dieser Klasse möglicherweise nicht erfolgreich. Verschiedene Browser (und Browserkonfigurationen) blocken eventuell Popupfenster. Es kann daher nicht sichergestellt werden, dass Popupfenster eingeblendet werden. Den größten Erfolg verspricht diese Klasse beim Öffnen eines Popupfensters in Code, der als direktes Ergebnis einer Benutzeraktion ausgeführt wird, z. B. in einer Ereignisprozedur für ein Mausklick- oder Tastendruckereignis.
Aus ActionScript stehen auf HTML-Seiten folgende Funktionen zur Verfügung:
- Aufrufen beliebiger JavaScript-Funktionen
- Übergeben einer beliebigen Anzahl von Argumenten mit frei wählbaren Namen
- Übergeben unterschiedlicher Datentypen (Boolean, Number, String usw.)
- Empfangen eines Rückgabewerts aus der JavaScript-Funktion
Aus JavaScript stehen auf HTML-Seiten folgende Funktionen zur Verfügung:
- Aufrufen einer ActionScript-Funktion
- Übergeben von Argumenten mithilfe der Funktionsaufruf-Standardnotation
- Zurückgeben eines Werts an die JavaScript-Funktion
Hinweis für Flash Player-Anwendungen: Flash Player unterstützt zurzeit keine SWF-Dateien, die in HTML-Formulare eingebettet sind.
Hinweis für AIR-Anwendungen: In Adobe AIR kann die ExternalInterface-Klasse für die Kommunikation zwischen JavaScript in einer HTML-Seite, die in einem HTMLLoader-Steuerelement geladen ist, und ActionScript in SWF-Inhalten, die in dieser HTML-Seite eingebettet sind, verwendet werden.
Verwandte API-Elemente
Vererbte öffentliche Eigenschaften ausblenden
Vererbte öffentliche Eigenschaften anzeigen| Eigenschaft | Definiert von | ||
|---|---|---|---|
| available : Boolean [statisch] [schreibgeschützt]
Gibt an, ob dieser Player in einem Container ausgeführt wird, der über eine externe Schnittstelle verfügt. | ExternalInterface | ||
 | constructor : Object
Ein Verweis auf das Klassenobjekt oder die Konstruktorfunktion für eine angegebene Objektinstanz. | Object | |
| marshallExceptions : Boolean = false [statisch]
Gibt an, ob die externe Schnittstelle eine Übergabe von ActionScript-Ausnahmen an den aktuellen Browser und von JavaScript-Ausnahmen an den Player versuchen soll. | ExternalInterface | ||
| objectID : String [statisch] [schreibgeschützt]
Gibt in Internet Explorer das id-Attribut des object-Tags oder in Netscape das name-Attribut des embed-Tags zurück. | ExternalInterface | ||
| Methode | Definiert von | ||
|---|---|---|---|
[statisch]
Registriert eine ActionScript-Methode als vom Container aufrufbare Methode. | ExternalInterface | ||
[statisch]
Ruft eine vom SWF-Container bereitgestellte Funktion auf und übergibt keine oder beliebig viele Argumente. | ExternalInterface | ||
|
Gibt an, ob für ein Objekt eine bestimmte Eigenschaft definiert wurde. | Object | |
|
Gibt an, ob eine Instanz der Object-Klasse in der Prototypkette des Objekts vorhanden ist, das als Parameter angegeben wurde. | Object | |
|
Gibt an, ob die angegebene Eigenschaft vorhanden ist und durchlaufen werden kann. | Object | |
|
Legt die Verfügbarkeit einer dynamischen Eigenschaft für Schleifenoperationen fest. | Object | |
|
Gibt die Stringdarstellung dieses Objekts zurück, formatiert entsprechend den Konventionen des Gebietsschemas. | Object | |
|
Gibt das angegebene Objekt als String zurück. | Object | |
|
Gibt den Grundwert des angegebenen Objekts zurück. | Object | |
available | Eigenschaft |
available:Boolean [schreibgeschützt] | Sprachversion: | ActionScript 3.0 |
| Laufzeitversionen: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Gibt an, ob dieser Player in einem Container ausgeführt wird, der über eine externe Schnittstelle verfügt. Wenn die externe Schnittstelle zur Verfügung steht, lautet der Wert dieser Eigenschaft true, ansonsten false.
Hinweis: Überprüfen Sie beim Einsatz der externen API mit HTML stets, dass der HTML-Code vollständig geladen wurde, bevor Sie versuchen, JavaScript-Methoden aufzurufen.
Implementierung
public static function get available():BooleanBeispiel ( Verwendung dieses Beispiels )
available-Eigenschaft festgestellt, ob der Player in einem Container ausgeführt wird, der eine externe Schnittstelle anbietet.
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 | Eigenschaft |
public static var marshallExceptions:Boolean = false| Sprachversion: | ActionScript 3.0 |
| Laufzeitversionen: | AIR 1.0, Flash Player 9.0.115.0, Flash Lite 4 |
Gibt an, ob die externe Schnittstelle eine Übergabe von ActionScript-Ausnahmen an den aktuellen Browser und von JavaScript-Ausnahmen an den Player versuchen soll. Sie müssen diese Eigenschaft ausdrücklich auf true setzen, um JavaScript-Ausnahmen in ActionScript abzufangen und ActionScript-Ausnahmen in JavaScript abzufangen.
Verwandte API-Elemente
Beispiel ( Verwendung dieses Beispiels )
addCallback()-Methode beim entsprechenden Browser registriert. Die neue Funktion gibt eine Ausnahme aus, sodass im Browser ausgeführter JavaScript-Code diese abfangen kann. Dieses Beispiel enthält auch eine try..catch-Anweisung, um alle Ausnahmen abzufangen, die vom Browser ausgegeben werden, wenn die Funktion throwit() aufgerufen wird.
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 | Eigenschaft |
addCallback | () | Methode |
public static function addCallback(functionName:String, closure:Function):void| Sprachversion: | ActionScript 3.0 |
| Laufzeitversionen: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Registriert eine ActionScript-Methode als vom Container aufrufbare Methode. Nach einem erfolgreichen Aufruf von addCallBack() kann die registrierte Funktion im Player mit einem JavaScript- oder ActiveX-Code im Container aufgerufen werden.
Hinweis: Bei lokalem Inhalt, der in einem Browser ausgeführt wird, kann die Funktion ExternalInterface.addCallback() nur aufgerufen werden, wenn sich die SWF-Datei und die Webseite, in die sie eingebettet ist, in der lokalen vertrauenswürdigen Sicherheits-Sandbox befinden. Weitere Informationen finden Sie im Flash Player Developer Center im Abschnitt Sicherheit.
Parameter
functionName:String — Der Name, über den der Container die Funktion aufrufen kann.
| |
closure:Function — Der aufzurufende Funktionsabschluss. Dies kann eine autonome Funktion oder ein Methodenabschluss sein, der auf eine Methode einer Objektinstanz verweist. Durch das Übergeben eines Methodenabschlusses können Sie die Callback-Funktion sogar an eine Methode einer bestimmten Objektinstanz leiten.
Hinweis: Durch das Wiederholen von |
Auslöser
Error — Der Container unterstützt keine eingehenden Aufrufe. Eingehende Aufrufe werden nur in Internet Explorer für Windows und in Browsern unterstützt, die die NPRuntime-API verwenden, z. B. Mozilla ab Version 1.7.5 oder Firefox ab Version 1.0.
| |
SecurityError — Eine Callback-Funktion mit dem angegebenen Namen wurde von ActionScript bereits in einer Sandbox eingefügt, auf die Sie keinen Zugriff haben. Diese Callback-Funktion kann nicht überschrieben werden. Um dieses Problem zu umgehen, schreiben Sie den ActionScript um, der ursprüngliche die Methode addCallback() aufgerufen hat, sodass die Methode Security.allowDomain() aufgerufen wird.
| |
SecurityError — Die Containerumgebung ist Teil einer Sicherheits-Sandbox, auf die der aufrufende Programmcode keinen Zugriff hat. Befolgen Sie die nachstehenden Schritte, um das Problem zu beheben:
|
Verwandte API-Elemente
call | () | Methode |
public static function call(functionName:String, ... arguments):*| Sprachversion: | ActionScript 3.0 |
| Laufzeitversionen: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Ruft eine vom SWF-Container bereitgestellte Funktion auf und übergibt keine oder beliebig viele Argumente. Falls die Funktion nicht zur Verfügung steht, gibt der Aufruf null zurück, ansonsten den Ergebniswert der Funktion. Eine Rekursion ist nicht zulässig in Opera- oder Netscape-Browsern; bei diesen Browsern löst ein rekursiver Aufruf die Antwort null aus. (Rekursion wird für Internet Explorer- und Firefox-Browser unterstützt.)
Wenn es sich bei dem Container um eine HTML-Seite handelt, ruft diese Methode eine JavaScript-Funktion in einem script-Element auf.
Ist der Container dagegen ein anderer ActiveX-Container, löst diese Methode das FlashCall ActiveX-Ereignis mit dem angegebenen Namen aus, das der Container dann verarbeitet.
Wenn der Container das Netscape-Plug-In hostet, können Sie entweder eine benutzerdefinierte Unterstützung für die neue NPRuntime-Schnittstelle programmieren oder ein entsprechendes HTML-Steuerelement einbetten und den Player innerhalb dieses HTML-Steuerelements ausführen. Beim Einbetten einer HTML-Steuerung können Sie mit dem Player über eine JavaScript-Schnittstelle kommunizieren, die den Kontakt zur eigenen Container-Anwendung sicherstellt.
Hinweis: Bei lokalem Inhalt, der in einem Browser ausgeführt wird, kann die Funktion ExternalInterface.call() nur aufgerufen werden, wenn sich die SWF-Datei und die Webseite, in die sie eingebettet ist, (falls vorhanden) in der lokalen vertrauenswürdigen Sicherheits-Sandbox befinden. Sie können eine SWF-Datei daran hindern, diese Methode aufzurufen, indem Sie auf der HTML-Seite, die den SWF-Inhalt enthält, den Parameter allowNetworking der object- und embed-Tags festlegen. Weitere Informationen finden Sie im Flash Player Developer Center im Abschnitt Sicherheit.
Hinweis für Flash Player-Anwendungen: In Flash Player 10 und Flash Player 9 mit Update 5 schränken manche Webbrowser diese Methode ein, wenn ein Popupblocker aktiviert ist. In diesem Szenario können Sie diese Methode nur als Reaktion auf ein Benutzerereignis erfolgreich aufrufen, z. B. in einer Ereignisprozedur für ein Mausklick- oder Tastendruckereignis.
Parameter
functionName:String — Der alphanumerische Name der Funktion, die im Container aufgerufen wird. Die Verwendung eines nicht alphanumerischen Dateinamens löst den Laufzeitfehler 2155 aus. Zur Vearbeitung des Fehlers können Sie einen try..catch-Block verwenden.
| |
... arguments — Die Argumente, die für die Funktion im Container übergeben werden. Sie können beliebig viele durch Komma getrennte Parameter angeben. Diese können einen beliebigen ActionScript-Datentyp aufweisen. Beim Aufrufen einer JavaScript-Funktion werden die ActionScript-Datentypen automatisch in JavaScript-Typen konvertiert. Bei anderen ActiveX-Containern werden die Parameter in der Anforderungsmeldung kodiert.
|
* — Die vom Container zurückgegebenen Ergebnisdaten. Wenn der Aufruf fehlschlägt, weil beispielsweise die Funktion nicht im Container enthalten ist, die Schnittstelle nicht zur Verfügung steht oder eine Rekursion bzw. ein Sicherheitsproblem (mit einem Netscape- oder Opera-Browser) aufgetreten ist, wird null zurückgegeben und ein Fehler ausgelöst.
|
Auslöser
Error — Der Container unterstützt keine ausgehenden Aufrufe. Ausgehende Aufrufe werden nur in Internet Explorer für Windows und in Browsern unterstützt, die die NPRuntime-API verwenden, z. B. Mozilla ab Version 1.7.5 oder Firefox ab Version 1.0.
| |
SecurityError — Die Containerumgebung ist Teil einer Sicherheits-Sandbox, auf die der aufrufende Programmcode keinen Zugriff hat. Befolgen Sie die nachstehenden Schritte, um das Problem zu beheben:
|
Beispiel ( Verwendung dieses Beispiels )
//
// 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, 10:04 AM Z