| Pakiet | flash.external |
| Klasa | public final class ExternalInterface |
| Dziedziczenie | ExternalInterface  Object |
| Wersja języka: | ActionScript 3.0 |
| Wersje środowiska wykonawczego: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Za pomocą klasy ExternalInterface można wywołać funkcję ActionScript w środowisku wykonawczym Flash z wykorzystaniem JavaScript na stronie HTML. Funkcja ActionScript może zwrócić wartość, a kod JavaScript odbierze ją niezwłocznie jako wartość zwróconą z wywołania.
Ta funkcjonalność zastępuje metodę fscommand().
Klasa ExternalInterface może być stosowana w następujących kombinacjach przeglądarek i systemów operacyjnych:
| Przeglądarka | System operacyjny | System operacyjny |
|---|---|---|
| Internet Explorer 5.0 i późniejsze wersje | Windows | |
| Netscape 8.0 i późniejsze wersje | Windows | MacOS |
| Mozilla 1.7.5 i późniejsze wersje | Windows | MacOS |
| Firefox 1.0 i późniejsze wersje | Windows | MacOS |
| Safari 1.3 i późniejsze wersje | MacOS |
Program Flash Player for Linux w wersji 9.0.31.0 i późniejszych obsługuje klasę ExternalInterface w następujących przeglądarkach:
| Przeglądarka |
|---|
| Mozilla 1.7.x i późniejsze wersje |
| Firefox 1.5.0.7 i późniejsze wersje |
| SeaMonkey 1.0.5 i późniejsze wersje |
Klasa ExternalInterface wymaga obsługi elementów sterujących ActiveX® lub interfejsu API NPRuntime udostępnianego przez niektóre przeglądarki dla skryptów działających we wtyczkach. Nawet jeśli dana kombinacja przeglądarki i systemu operacyjnego nie jest wymieniona powyżej, klasa ExternalInterface powinna być obsługiwana, o ile przeglądarka obsługuje interfejs API NPRuntime. Zobacz http://www.mozilla.org/projects/plugins/npruntime.html.
Uwaga: W przypadku osadzania plików SWF na stronie HTML należy się upewnić, że dla atrybutu id ustawiona jest wartość, a atrybuty id i name znaczników object i embed nie zawierają następujących znaków:
. - + * / \
Uwaga dla aplikacji w programie Flash Player: odtwarzacz Flash Player wersja 9.0.115.0 i zezwala na . (kropka) w atrybutach id i name.
Uwaga dla aplikacji w programie Flash Player W programie Flash Player 10 i nowszych wersjach działających w przeglądarce użycie tej klasy do programowego otwarcia okna podręcznego może zakończyć się niepowodzeniem. Różne przeglądarki (i konfiguracje przeglądarek) mogą blokować podręczne okna w każdej chwili; nie można zagwarantować, że podręczne okno zostanie wyświetlone. Jednak, aby zwiększyć szansę na powodzenie, należy użyć tej metody w celu otwarcia podręcznego okna tylko w kodzie, który wykonywany jako bezpośredni wynik działania użytkownika (np. w module obsługi zdarzenia dla zdarzenia kliknięcia myszą lub naciśnięcia klawisza).
Z poziomu kodu ActionScript można wykonać następujące operacje na stronie HTML:
- Wywoływać dowolne funkcje JavaScript.
- Przekazywać dowolną liczbę argumentów o dowolnych nazwach.
- Przekazywać dane różnych typów (Boolean, Number, String itd.).
- Odbierać wartości zwrotne z funkcji JavaScript.
Z poziomu kodu JavaScript na stronie HTML można:
- Wywoływać funkcje ActionScript.
- Przekazywać argumenty, korzystając ze standardowego zapisu wywołania funkcji.
- Zwracać wartości do funkcji JavaScript.
Uwaga dla aplikacji programu Flash Player: Program Flash Player nie obsługuje aktualnie plików SWF osadzonych w formularzach HTML.
Uwaga dla aplikacji AIR: W środowisku Adobe AIR klasa ExternalInterface może być używana w celu nawiązania komunikacji między kodem JavaScript na stronie HTML załadowanej w elemencie sterującym HTMLLoader a kodem ActionScript w treści SWF osadzonej na stronie HTML.
Powiązane elementy interfejsu API
Ukryj dziedziczone właściwości publiczne
Pokaż dziedziczone właściwości publiczne| Właściwość | Zdefiniowane przez | ||
|---|---|---|---|
| available : Boolean [statyczny] [tylko do odczytu]
Wskazuje, czy ten odtwarzacz działa w kontenerze zapewniającym interfejs zewnętrzny. | ExternalInterface | ||
 | constructor : Object
Odwołanie do obiektu klasy lub funkcji konstruktora, dotyczące danej instancji obiektu. | Object | |
| marshallExceptions : Boolean = false [statyczny]
Określa, czy interfejs zewnętrzny powinien podejmować próby przekazywania wyjątków ActionScript do bieżącej przeglądarki, a wyjątków JavaScript do odtwarzacza. | ExternalInterface | ||
| objectID : String [statyczny] [tylko do odczytu]
Zwraca atrybut id znacznika object w przeglądarce Internet Explorer lub atrybut name znacznika embed w przeglądarce Netscape. | ExternalInterface | ||
| Metoda | Zdefiniowane przez | ||
|---|---|---|---|
[statyczny]
Rejestruje metodę ActionScript jako metodę, którą można wywoływać z kontenera. | ExternalInterface | ||
[statyczny]
Wywołuje funkcję uwidocznioną przez kontener SWF, przekazując zero lub więcej argumentów. | ExternalInterface | ||
|
Wskazuje, czy dla obiektu zdefiniowano określoną właściwość. | Object | |
|
Wskazuje, czy instancja klasy Object należy do łańcucha prototypów obiektu określonego jako parametr. | Object | |
|
Wskazuje, czy określona właściwość istnieje i jest przeliczalna. | Object | |
|
Ustawia dostępność właściwości dynamicznej używanej w pętlach. | Object | |
|
Zwraca ciąg reprezentujący obiekt — sformatowany zgodnie z konwencjami właściwymi dla ustawień regionalnych. | Object | |
|
Zwraca ciąg reprezentujący określony obiekt. | Object | |
|
Zwraca pierwotną wartość dla określonego obiektu. | Object | |
available | właściwość |
available:Boolean [tylko do odczytu] | Wersja języka: | ActionScript 3.0 |
| Wersje środowiska wykonawczego: | AIR 1.0, Flash Player 9, Flash Lite 4 |
wskazuje, czy ten odtwarzacz działa w kontenerze zapewniającym interfejs zewnętrzny. Jeśli interfejs zewnętrzny jest dostępny, ta właściwość ma wartość true; w przeciwnym razie ma wartość false.
Uwaga: Używając zewnętrznego interfejsu API ze stronami HTML, należy przed pierwszym wywołaniem metody JavaScript sprawdzić, czy zakończyło się ładowanie kodu HTML.
Implementacja
public static function get available():BooleanPrzykład ( Sposób korzystania z tego przykładu )
available w celu określenia, czy odtwarzacz działa w kontenerze udostępniającym interfejs zewnętrzny.
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 | właściwość |
public static var marshallExceptions:Boolean = false| Wersja języka: | ActionScript 3.0 |
| Wersje środowiska wykonawczego: | AIR 1.0, Flash Player 9.0.115.0, Flash Lite 4 |
Określa, czy interfejs zewnętrzny powinien podejmować próby przekazywania wyjątków ActionScript do bieżącej przeglądarki, a wyjątków JavaScript do odtwarzacza. Należy jawnie ustawić tę właściwość na true, aby przechwytywać wyjątki JavaScript w kodzie ActionScript i przechwytywać wyjątki ActionScript w kodzie JavaScript.
Powiązane elementy interfejsu API
Przykład ( Sposób korzystania z tego przykładu )
addCallback(). Nowa funkcja generuje wyjątek, tak aby kod JavaScript działający w przeglądarce mógł go przechwycić. Przykład zawiera także instrukcję try..catch, która przechwytuje wyjątki generowane przez przeglądarkę po wywołaniu funkcji 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 | właściwość |
objectID:String [tylko do odczytu] | Wersja języka: | ActionScript 3.0 |
| Wersje środowiska wykonawczego: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Zwraca atrybut id znacznika object w przeglądarce Internet Explorer lub atrybut name znacznika embed w przeglądarce Netscape.
Implementacja
public static function get objectID():StringaddCallback | () | metoda |
public static function addCallback(functionName:String, closure:Function):void| Wersja języka: | ActionScript 3.0 |
| Wersje środowiska wykonawczego: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Rejestruje metodę ActionScript jako metodę, którą można wywoływać z kontenera. Po pomyślnym wywołaniu funkcji addCallBack() zarejestrowana funkcja z odtwarzacza może zostać wywołana przez kod JavaScript lub ActiveX w kontenerze.
Uwaga: W przypadku treści lokalnej działającej w przeglądarce wywołania metody ExternalInterface.addCallback() działają pod warunkiem, że plik SWF i zawierająca go strona sieci Web znajdują się w lokalnie zaufanym obszarze izolowanym. Więcej informacji zawiera temat Bezpieczeństwo w Centrum programistów programu Flash Player.
Parametry
functionName:String — Nazwa, pod którą kontener może wywoływać funkcję.
| |
closure:Function — Zamknięcie funkcji, którą należy wywołać. Może to być funkcja autonomiczna lub zamknięcie metody odwołujące się do metody w instancji obiektu. Przekazując zamknięcie metody można skierować wywołanie zwrotne do metody konkretnej instancji obiektu.
Uwaga: Powtórzenie metody |
Zgłasza
Error — Kontener nie obsługuje wywołań przychodzących. Wywołania przychodzące są obsługiwane tylko w programie Internet Explorer dla systemu Windows i przeglądarkach obsługujących interfejs API NPRuntime, takich jak Mozilla 1.7.5 i późniejsze wersje lub Firefox 1.0 i późniejsze wersje.
| |
SecurityError — Funkcja wywołania zwrotnego o określonej nazwie została już dodana przez skrypt ActionScript w obszarze izolowanym, do którego bieżący kod nie ma dostępu; nie można nadpisać tamtej funkcji wywołania zwrotnego. Aby obejść ten problem, należy zmodyfikować kod ActionScript, który pierwotnie wywoływał metodę addCallback(), tak aby wywoływał także metodę Security.allowDomain().
| |
SecurityError — Środowisko kontenera należy do obszaru izolowanego, do którego kod wywołujący nie ma dostępu. Aby rozwiązać ten problem, należy wykonać następujące kroki:
|
Powiązane elementy interfejsu API
call | () | metoda |
public static function call(functionName:String, ... arguments):*| Wersja języka: | ActionScript 3.0 |
| Wersje środowiska wykonawczego: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Wywołuje funkcję uwidocznioną przez kontener SWF, przekazując zero lub więcej argumentów. Jeśli funkcja jest niedostępna, wywołanie zwraca null; w przeciwnym razie zwraca wartośc przekazaną przez funkcję. Wywołania rekurencyjne nie są dozwolone w przeglądarkach Opera i Netscape; w tych przeglądarkach wywołanie rekurencyjne spowoduje zwrócenie odpowiedzi null. (Wywołania rekurencyjne są obsługiwane w przeglądarkach Internet Explorer i Firefox).
Jeśli kontenerem jest strona HTML, ta metoda wywołuje funkcję JavaScript w elemencie script.
Jeśli kontenerem jest inny kontener ActiveX, ta metoda wywołuje zdarzenie ActiveX FlashCall z określoną nazwą, a kontener przetwarza zdarzenie.
Jeśli kontener zawiera wtyczkę Netscape, można napisać niestandardowy kod obsługujący nowy interfejs NPRuntime lub osadzić element sterujący HTML, a w nim odtwarzacz. W przypadku osadzenia elementu sterującego HTML można komunikować się z odtwarzaczem przez interfejs JavaScript natywnej aplikacji-kontenera.
Uwaga: W przypadku treści lokalnej działającej w przeglądarce wywołania metody ExternalInterface.call() są dozwolone pod warunkiem, że plik SWF i zawierająca go strona sieci Web (jeśli istnieje) znajdują się w lokalnie zaufanym obszarze izolowanym. Istnieje także możliwość uniemożliwienia plikowi SWF korzystania z tej metody poprzez ustawienie parametru allowNetworking znaczników object oraz embed na stronie HTML zawierającej treść SWF. Więcej informacji zawiera temat Bezpieczeństwo w Centrum programistów programu Flash Player.
Uwaga dla aplikacji w programie Flash Player:W programie Flash Player 10 oraz Flash Player 9 Update 5 niektóre przeglądarki sieci Web ograniczają tę metodę, jeśli jest włączona funkcja blokowania podręcznych okien. W takim przypadku metodę można wywołać pomyślnie tylko w odpowiedzi na zdarzenie użytkownika (np. w module obsługi zdarzenia dla zdarzenia kliknięcia myszą lub naciśnięcia klawisza).
Parametry
functionName:String — Alfanumeryczna nazwa funkcji, którą należy wywołać w kontenerze. Użycie funkcji o nazwie zawierającej znaki inne niż alfanumeryczne powoduje zgłoszenie błędu w czasie wykonywania (błąd 2155). Do obsługi błędu można użyć bloku try..catch.
| |
... arguments — Argumenty, które mają być przekazane do funkcji w kontenerze. Można określić zero lub więcej parametrów, oddzielając je przecinkami. Mogą należeć do dowolnego typu danych języka ActionScript. Gdy wywoływana jest funkcja języka JavaScript, typy języka ActionScript są automatycznie konwertowane na typy języka JavaScript; gdy wywoływany jest inny kontener ActiveX, parametry są kodowane w komunikacie żądania.
|
* — Odpowiedź odebrana z kontenera. Jeśli wywołanie nie powiedzie się — na przykład gdy w kontenerze nie ma takiej funkcji, interfejs jest niedostępny, wywołanie jest rekurencyjne (dotyczy przeglądarek Netscape i Opera) lub wystąpił problem z zabezpieczeniami — zwracana jest wartość null i generowany jest błąd.
|
Zgłasza
Error — Kontener nie obsługuje wywołań wychodzących. Wywołania wychodzące są obsługiwane tylko w programie Internet Explorer dla systemu Windows i przeglądarkach obsługujących interfejs API NPRuntime, takich jak Mozilla 1.7.5 i późniejsze wersje lub Firefox 1.0 i późniejsze wersje.
| |
SecurityError — Środowisko kontenera należy do obszaru izolowanego, do którego kod wywołujący nie ma dostępu. Aby rozwiązać ten problem, należy wykonać następujące kroki:
|
Przykład ( Sposób korzystania z tego przykładu )
//
// 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, 12:06 PM Z