ActionScript® 3.0 Referenzhandbuch für die Adobe® Flash®-Plattform
Home  |  Liste der Pakete und Klassen ausblenden |  Pakete  |  Klassen  |  Neue Funktionen  |  Stichwortverzeichnis  |  Anhänge  |  Warum auf Englisch?
Filter: Daten werden vom Server abgerufen...
Daten werden vom Server abgerufen...
flash.external 

ExternalInterface  - AS3

Paketflash.external
Klassepublic final class ExternalInterface
VererbungExternalInterface Inheritance Object

Sprachversion: ActionScript 3.0
Laufzeitversionen: AIR 1.0, Flash Player 9, Flash Lite 4

Die ExternalInterface-Klasse ist eine API (Application Programming Interface), die die direkte Kommunikation zwischen ActionScript und dem SWF-Container ermöglicht; zum Beispiel eine HTML-Seite mit JavaScript oder eine Desktopanwendung, die Flash Player für die Anzeige einer SWF-Datei verwendet.

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:

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

Beispiele anzeigen

Verwandte API-Elemente



Öffentliche Eigenschaften
 EigenschaftDefiniert 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
 Inheritedconstructor : 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
Öffentliche Methoden
 MethodeDefiniert von
  
addCallback(functionName:String, closure:Function):void
[statisch] Registriert eine ActionScript-Methode als vom Container aufrufbare Methode.
ExternalInterface
  
call(functionName:String, ... arguments):*
[statisch] Ruft eine vom SWF-Container bereitgestellte Funktion auf und übergibt keine oder beliebig viele Argumente.
ExternalInterface
 Inherited
Gibt an, ob für ein Objekt eine bestimmte Eigenschaft definiert wurde.
Object
 Inherited
Gibt an, ob eine Instanz der Object-Klasse in der Prototypkette des Objekts vorhanden ist, das als Parameter angegeben wurde.
Object
 Inherited
Gibt an, ob die angegebene Eigenschaft vorhanden ist und durchlaufen werden kann.
Object
 Inherited
Legt die Verfügbarkeit einer dynamischen Eigenschaft für Schleifenoperationen fest.
Object
 Inherited
Gibt die Stringdarstellung dieses Objekts zurück, formatiert entsprechend den Konventionen des Gebietsschemas.
Object
 Inherited
Gibt das angegebene Objekt als String zurück.
Object
 Inherited
Gibt den Grundwert des angegebenen Objekts zurück.
Object
Eigenschaftendetails

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():Boolean

Beispiel  ( Verwendung dieses Beispiels )
Im folgenden Beispiel wird mithilfe der 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 )
Im folgenden Beispiel wird eine ActionScript-Funktion erstellt und mithilfe der 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 
objectID:String  [schreibgeschützt]

Sprachversion: ActionScript 3.0
Laufzeitversionen: AIR 1.0, Flash Player 9, Flash Lite 4

Gibt in Internet Explorer das id-Attribut des object-Tags oder in Netscape das name-Attribut des embed-Tags zurück.



Implementierung
    public static function get objectID():String
Methodendetails

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 addCallback() für eine vorhandene Rückruffunktion mit einem null-Abschlusswert wird der Rückruf entfernt.


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:
  1. Legen Sie auf der HTML-Seite im object-Tag für die SWF-Datei den folgenden Parameter fest:

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

  2. Fügen Sie in der SWF-Datei den folgenden ActionScript-Code ein:

    flash.system.Security.allowDomain( sourceDomain )

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.

Rückgabewerte
* — 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:
  1. Legen Sie auf der HTML-Seite im object-Tag für die SWF-Datei den folgenden Parameter fest:

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

  2. Fügen Sie in der SWF-Datei den folgenden ActionScript-Code ein:

    flash.system.Security.allowDomain( sourceDomain )


Beispiel  ( Verwendung dieses Beispiels )

Im folgenden Beispiel wird gezeigt, wie Sie mit der ExternalInterface-Klasse (flash.external.ExternalInterface) einen String von Flash Player an den HTML-Container senden können, wo der String mithilfe der JavaScript-Funktion alert() angezeigt wird. Beispiel bereitgestellt von ActionScriptExamples.com.
//
// 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);
}
ExternalInterfaceExample.as

Im folgenden Beispiel wird die Datenübertragung zwischen Flash Player und einem HTML-Container demonstriert.
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);
            }
        }
    }
}


Zum Testen des vorausgegangenen ActionScript-Codes müssen Sie die erzeugte SWF-Datei mithilfe der folgenden HTML-Vorlage einbetten:
 <!-- 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>
 




[ X ]Warum auf Englisch?
Inhalt des ActionScript 3.0-Referenzhandbuchs wird in englischer Sprache angezeigt

Nicht alle Teile des ActionScript 3.0-Referenzhandbuchs wurden in alle Sprachen übersetzt. Wenn der Text zu einem Sprachelement nicht übersetzt wurde, wird er auf Englisch angezeigt. Zum Beispiel wurden die Informationen zur ga.controls.HelpBox-Klasse nicht in andere Sprachen übersetzt. In der deutschen Version des Referenzhandbuchs erscheint der Abschnitt zur ga.controls.HelpBox-Klasse deshalb auf Englisch.