| 套件 | flash.external |
| 類別 | public final class ExternalInterface |
| 繼承 | ExternalInterface  Object |
| 語言版本: | ActionScript 3.0 |
| 執行階段版本: | AIR 1.0, Flash Player 9, Flash Lite 4 |
使用 ExternalInterface 類別，您可以在 HTML 頁面中使用 JavaScript，在 Flash 執行階段中呼叫 ActionScript 函數。ActionScript 函數可以傳回一個值，JavaScript 會立即接收做為該呼叫的傳回值。
這個功能會取代 fscommand() 方法。
您可以在下列瀏覽器與作業系統的組合中使用 ExternalInterface 類別：
| 瀏覽器 | 作業系統 | 作業系統 |
|---|---|---|
| Internet Explorer 5.0 和更新版本 | Windows | |
| Netscape 8.0 和更新版本 | Windows | MacOS |
| Mozilla 1.7.5 和更新版本 | Windows | MacOS |
| Firefox 1.0 和更新版本 | Windows | MacOS |
| Safari 1.3 和更新版本 | MacOS |
Flash Player for Linux 9.0.31.0 版和更新版本在下列瀏覽器中支援 ExternalInterface 類別：
| 瀏覽器 |
|---|
| Mozilla 1.7.x 和更新版本 |
| Firefox 1.5.0.7 和更新版本 |
| SeaMonkey 1.0.5 和更新版本 |
ExternalInterface 類別要求使用者的網頁瀏覽器必須支援 ActiveX® 或由某些瀏覽器所公開的 NPRuntime API 以供編寫外掛程式 Script。即使瀏覽器和作業系統的組合不在上列項目之中，但只要它們支援 NPRuntime API，應該就會支援 ExternalInterface 類別。 請參閱 http://www.mozilla.org/projects/plugins/npruntime.html。
注意：在 HTML 網頁內嵌 SWF 檔時，請確定 id 特質已設定，而且 object 的 id 和 name 特質以及 embed 標籤未包含下列字元：
. - + * / \
Flash Player 應用程式的注意事項：Flash Player 9.0.115.0 版本以及之後版本允許 . (句點) 字元出現在 id 和 name 特質中。
Flash Player 應用程式的注意事項：在瀏覽器中執行的 Flash Player 10 和更新版本中，使用這個類別以程式設計的方式開啟彈出式視窗可能不會成功。各種瀏覽器 (和瀏覽器組態設定) 可能隨時封鎖彈出式視窗，所以無法保證彈出式視窗一定會出現。但為了確保最大的成功機會，最好只在為了回應使用者動作 (例如，按下滑鼠或按下按鍵事件的事件處理常式中) 而直接執行的程式碼中使用這個類別來開啟彈出式視窗。
透過 JavaScript，您可以在 HTML 網頁執行下列動作：
- 呼叫任何 JavaScript 函數。
- 用任何名稱來傳遞任何數目的引數。
- 傳遞不同的資料類型 (Boolean、Number、String 等等)。
- 接收來自 JavaScript 函數的傳回值。
透過 JavaScript，您可以在 HTML 網頁執行下列動作：
- 呼叫 ActionScript 函數。
- 使用標準函數呼叫標記法來傳遞引數。
- 將值傳回 JavaScript 函數。
Flash Player 應用程式的注意事項：目前 Flash Player 不支援在 HTML 表單內嵌 SWF 檔案。
AIR 應用程式注意事項：在 Adobe AIR 中，ExternalInterface 類別可以用來在 HTMLLoader 控制項中載入之 HTML 頁面的 JavaScript，與該 HTML 頁面中所內嵌 SWF 內容的 ActionScript 通訊。
更多範例
Accessing Flex from JavaScript
About ExternalInterface API security in Flex
相關 API 元素
隱藏繼承公用屬性
顯示繼承公用屬性| 屬性 | 定義自 | ||
|---|---|---|---|
| available : Boolean [靜態] [唯讀]
指出這個播放程式是否在提供外部介面的容器內。 | ExternalInterface | ||
 | constructor : Object
類別物件的參照或是特定物件實體的建構函數。 | Object | |
| marshallExceptions : Boolean = false [靜態]
指出外部介面是否應該嘗試傳遞 ActionScript 例外給目前瀏覽器，及傳遞 JavaScript 例外給播放程式。 | ExternalInterface | ||
| objectID : String [靜態] [唯讀]
傳回 Internet Explorer 中 object 標籤的 id 特質，或 Netscape 中 embed 標籤的 name 特質。 | ExternalInterface | ||
| 方法 | 定義自 | ||
|---|---|---|---|
[靜態]
將 ActionScript 方法註冊為可從容器呼叫。 | ExternalInterface | ||
[靜態]
呼叫 SWF 容器公開的函數，傳遞 0 個或更多引數。 | ExternalInterface | ||
|
指出物件是否有已定義的指定屬性。 | Object | |
|
指出 Object 類別的實體是否位於指定為參數的物件原型鏈中。 | Object | |
|
指出指定的屬性是否存在，以及是否可列舉。 | Object | |
|
為迴圈作業設定動態屬性的可用性。 | Object | |
|
傳回代表此物件的字串，根據地區特定慣例進行格式化。 | Object | |
|
會傳回指定之物件的字串形式。 | Object | |
|
會傳回指定之物件的基本值。 | Object | |
available | 屬性 |
available:Boolean [唯讀] | 語言版本: | ActionScript 3.0 |
| 執行階段版本: | AIR 1.0, Flash Player 9, Flash Lite 4 |
指出這個播放程式是否在提供外部介面的容器內。 如果可使用外部介面，則此屬性為 true；否則為 false。
注意：將 External API 與 HTML 搭配使用時，務必確認 HTML 已經完成載入後，再嘗試呼叫任何 JavaScript 方法。
實作
public static function get available():Boolean範例 ( 如何使用本範例 )
available 屬性來判斷播放程式是否在提供外部介面的容器內。
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 | 屬性 |
public static var marshallExceptions:Boolean = false| 語言版本: | ActionScript 3.0 |
| 執行階段版本: | AIR 1.0, Flash Player 9.0.115.0, Flash Lite 4 |
指出外部介面是否應該嘗試傳遞 ActionScript 例外給目前瀏覽器，及傳遞 JavaScript 例外給播放程式。您必須將這個屬性明確設定為 true，才能在 ActionScript 中捕捉 JavaScript 例外，及在 JavaScript 中捕捉 ActionScript 例外。
相關 API 元素
範例 ( 如何使用本範例 )
addCallback() 方法向包含的瀏覽器註冊這個函數。 新函數會擲出例外，讓瀏覽器中執行的 JavaScript 程式碼可以捕捉它。 這個範例也包含 try..catch 陳述式，以捕捉瀏覽器在呼叫 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 | 屬性 |
addCallback | () | 方法 |
public static function addCallback(functionName:String, closure:Function):void| 語言版本: | ActionScript 3.0 |
| 執行階段版本: | AIR 1.0, Flash Player 9, Flash Lite 4 |
將 ActionScript 方法註冊為可從容器呼叫。成功叫用 addCallBack() 後，容器內的 JavaScript 或 ActiveX 程式碼就可以呼叫播放程式中的已註冊函數。
注意：對於在瀏覽器內執行的 local 內容，只有當 SWF 檔和內含的網頁位於本機信任的安全執行程序之內時，呼叫 ExternalInterface.addCallback() 方法才有作用。如需詳細資訊，請參閱「Flash Player 開發人員中心」主題：「安全性」。
參數
functionName:String — 容器叫用函數所依據的名稱。
| |
closure:Function — 要叫用的函數結束項。 這可能是獨立函數，或是參照物件實體方法的方法結束項。 藉由傳遞方法結束項，您可以將回呼導向特定物件實體的方法。
注意：在具有 |
擲回值
Error — 容器不支援連入呼叫。 只有 Windows 的 Internet Explorer 和使用 NPRuntime API 的瀏覽器 (例如 Mozilla 1.7.5 和更新版本或 Firefox 1.0 和更新版本) 支援連入呼叫。
| |
SecurityError — ActionScript 已經將具有指定名稱的回呼加入至您無法存取的執行程序中，因此您無法覆寫該回呼。 如果要解決這個問題，請重新編寫原先呼叫 addCallback() 方法的 ActionScript，讓它也呼叫 Security.allowDomain() 方法。
| |
SecurityError — 這個容納環境屬於呼叫程式碼無法存取的安全執行程序。 若要解決這個問題，請執行下列步驟：
|
相關 API 元素
call | () | 方法 |
public static function call(functionName:String, ... arguments):*| 語言版本: | ActionScript 3.0 |
| 執行階段版本: | AIR 1.0, Flash Player 9, Flash Lite 4 |
呼叫 SWF 容器公開的函數，傳遞 0 個或更多引數。如果無法取得想要的函數，該呼叫會傳回 null，否則會傳回函數所提供的值。 Opera 或 Netscape 瀏覽器「不」允許遞迴。在這些瀏覽器上，遞迴呼叫會產生 null 回應 (Internet Explorer 和 Firefox 瀏覽器不支援遞迴)。
如果容器是 HTML 網頁，則此方法會叫用 script 元素中的 JavaScript 函數。
如果容器是其他 ActiveX 容器，則此方法會傳送特定名稱的 FlashCall ActiveX 事件，由容器處理該事件。
如果容器掛載著 Netscape 外掛程式，您就可以為新的 NPRuntime 介面撰寫自訂支援，或是嵌入 HTML 控制項，再將播放程式嵌入 HTML 控制項內。如果嵌入的是 HTML 控制項，您就可以原生容器應用程式的 JavaScript 介面，來與播放程式進行通訊。
注意：對於在瀏覽器內執行的 local 內容，只有當 SWF 檔和內含的網頁 (如果有) 位於本機信任的安全執行程序之內時，才允許呼叫 ExternalInterface.call() 方法。 您也可以拒絕 SWF 檔使用這個方法，方式是在包含 SWF 內容的 HTML 網頁中，設定 object 和 embed 標籤的 allowNetworking 參數。 如需詳細資訊，請參閱「Flash Player 開發人員中心」主題：「安全性」。
Flash Player 應用程式的注意事項：在 Flash Player 10 和 Flash Player 9 更新 5 中，如果啟用了彈出式視窗封鎖程式，某些網頁瀏覽器會限制這個方法。在此狀況中，只有在回應使用者事件 (例如，在按下滑鼠或按下按鍵事件的事件處理常式中) 時，才能成功呼叫這個方法。
參數
functionName:String — 要在容器中呼叫之函數的英數字元名稱。使用非英數字元的函數名稱會導致執行階段錯誤 (錯誤 2155)。您可以使用 try..catch 區塊來處理錯誤。
| |
... arguments — 要傳遞至容器中函數的引數。 您可以指定零個或多個參數 (以逗號分隔)。 它們可以是任何 ActionScript 資料類型。 呼叫 JavaScript 函數時，ActionScript 類型會自動轉換成 JavaScript 類型，呼叫其他 ActiveX 容器時，則會將參數編碼在要求訊息內。
|
* — 從容器收到的回應。 如果呼叫失敗 (例如，容器中沒有這個函數、無法取得介面、發生遞迴 (使用 Netscape 或 Opera 瀏覽器時)，或者出現安全性問題)，便會傳回 null，並擲出錯誤。
|
擲回值
Error — 容器不支援外送呼叫。 只有 Windows 的 Internet Explorer 和使用 NPRuntime API 的瀏覽器 (例如 Mozilla 1.7.5 和更新版本或 Firefox 1.0 和更新版本) 支援外送呼叫。
| |
SecurityError — 這個容納環境屬於呼叫程式碼無法存取的安全執行程序。 若要解決這個問題，請執行下列步驟：
|
範例 ( 如何使用本範例 )
//
// 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, 03:47 PM Z