Paketflash.external
Klassepublic final class ExternalInterface
VererbungExternalInterface Inheritance Object

Sprachversion : ActionScript 3.0
Player-Version : Flash Player 9

Die ExternalInterface-Klasse ist die External-API. Hierbei handelt es sich um eine Anwendungsprogrammierschnittstelle, die eine unmittelbare Kommunikation zwischen ActionScript und dem Flash Player-Container (beispielsweise eine HTML-Seite mit JavaScript) ermöglicht. Adobe empfiehlt, ExternalInterface für die gesamte JavaScript-ActionScript-Kommunikation zu verwenden.

Sie können eine ActionScript-Funktion in Flash Player aufrufen, indem 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.0Windows 
Netscape ab Version 8.0Windows MacOS 
Mozilla ab Version 1.7.5Windows MacOS 
Firefox ab Version 1.0Windows 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

Damit die ExternalInterface-Klasse verwendet werden kann, muss der Webbrowser des Benutzers entweder ActiveX oder die NPRuntime-API unterstützen, 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 die Attribute id und name der Tags object und embed nicht die folgenden Zeichen enthalten:

. - + * / \

Aus ActionScript stehen auf HTML-Seiten folgende Funktionen zur Verfügung:

Aus JavaScript stehen auf HTML-Seiten folgende Funktionen zur Verfügung:

In Flash Player werden derzeit keine in HTML-Formulare eingebetteten SWF-Dateien unterstützt.

Beispiele anzeigen

Siehe auch

flash.system.fscommand()
Anforderungen und Vorzüge der externen API
Verwenden der ExternalInterface-Klasse

Öffentliche Eigenschaften
 EigenschaftDefiniert von
  available : Boolean
[static] [read-only] 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
[static] Gibt an, ob die externe Schnittstelle versuchen soll, ActionScript-Ausnahmen an den aktuellen Browser und JavaScript-Ausnahmen an Flash Player zu übergeben.
ExternalInterface
  objectID : String
[static] [read-only] Gibt in Internet Explorer das id-Attribut des object-Tags oder in Netscape das name-Attribut des embed-Tags zurück.
ExternalInterface
 Inheritedprototype : Object
[static] Ein Verweis auf das Prototypobjekt einer Klasse oder eines Funktionsobjekts.
Object
Öffentliche Methoden
 MethodeDefiniert von
  
addCallback(functionName:String, closure:Function):void
[static] Registriert eine ActionScript-Methode als vom Container aufrufbare Methode.
ExternalInterface
  
call(functionName:String, ... arguments):*
[static] Ruft eine vom Flash Player-Container bereitgestellte Funktion auf und übergibt keine oder beliebig viele Argumente.
ExternalInterface
 Inherited
hasOwnProperty(name:String):Boolean
Gibt an, ob für ein Objekt eine bestimmte Eigenschaft definiert wurde.
Object
 Inherited
isPrototypeOf(theClass:Object):Boolean
Gibt an, ob eine Instanz der Object-Klasse in der Prototypkette des Objekts vorhanden ist, das als Parameter angegeben wurde.
Object
 Inherited
propertyIsEnumerable(name:String):Boolean
Gibt an, ob die angegebene Eigenschaft vorhanden ist und durchlaufen werden kann.
Object
 Inherited
setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void
Legt die Verfügbarkeit einer dynamischen Eigenschaft für Schleifenoperationen fest.
Object
 Inherited
toString():String
Gibt das angegebene Objekt als String zurück.
Object
 Inherited
valueOf():Object
Gibt den Grundwert des angegebenen Objekts zurück.
Object
Eigenschaftsdetail
availableEigenschaft
available:Boolean  [read-only]

Sprachversion : ActionScript 3.0
Player-Version : Flash Player 9

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 External-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

Siehe auch

Abrufen von Informationen über den externen Container

Beispiel
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);
      }
    }
  }
marshallExceptionsEigenschaft 
public static var marshallExceptions:Boolean = false

Sprachversion : ActionScript 3.0

Gibt an, ob die externe Schnittstelle versuchen soll, ActionScript-Ausnahmen an den aktuellen Browser und JavaScript-Ausnahmen an Flash Player zu übergeben. Sie müssen diese Eigenschaft ausdrücklich auf true setzen, um JavaScript-Ausnahmen in ActionScript abzufangen und ActionScript-Ausnahmen in JavaScript abzufangen.

Player-Version: Flash Player 9 Update 3.

Siehe auch

addCallBack()
try..catch..finally-Anweisung

Beispiel

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!!!!") }
    }
}
objectIDEigenschaft 
objectID:String  [read-only]

Sprachversion : ActionScript 3.0
Player-Version : Flash Player 9

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

Siehe auch

Abrufen von Informationen über den externen Container
Methodendetail
addCallback()Methode
public static function addCallback(functionName:String, closure:Function):void

Sprachversion : ActionScript 3.0
Player-Version : Flash Player 9

Registriert eine ActionScript-Methode als vom Container aufrufbare Methode. Nach einem erfolgreichen Aufruf von addCallBack() kann die registrierte Funktion in Flash 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 in den folgenden Abschnitten:

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.


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 in der HTML-Seite im object-Tag der 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 )

Siehe auch

flash.system.Security.allowDomain()
Aufrufen von ActionScript-Code aus dem Container
call()Methode 
public static function call(functionName:String, ... arguments):*

Sprachversion : ActionScript 3.0
Player-Version : Flash Player 9

Ruft eine vom Flash Player-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 Flash Player innerhalb dieses HTML-Steuerelements ausführen. Bei der Integration einer HTML-Steuerung können Sie mit dem Flash 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 in der HTML-Seite, die den SWF-Inhalt enthält, den Parameter allowNetworking der Tags object und embed festlegen. Weitere Informationen finden Sie in den folgenden Abschnitten:

Parameter

functionName:String — Der alphanumerische Name der Funktion, die im Container aufgerufen wird.
 
... 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 in der HTML-Seite im object-Tag der 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 )

Siehe auch

Aufrufen von externem Code aus ActionScript
Beispiele Verwendung von Beispielen
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;

    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);
            }
        }
    }
}
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 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_de">
         </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-2007 Adobe Systems Incorporated. All rights reserved.
Fri Oct 12 2007, 2:03 AM GMT-07:00

 

Eine E-Mail an mich senden, wenn dieser Seite Kommentare hinzugefügt werden | Kommentarbericht

Aktuelle Seite: http://livedocs.adobe.com/flash/9.0_de/ActionScriptLangRefV3/flash/external/ExternalInterface.html