实现 ActionScript 与容器之间的通信。
Object
ExternalInterface 类是用来支持在 ActionScript 和 SWF 容器(例如,含有 JavaScript 的 HTML 页或使用 Flash Player 播放 SWF 文件的桌面应用程序)之间进行直接通信的应用程序编程接口。
通过 ExternalInterface 类,您可以在 Flash 运行时中使用 HTML 页面中的 JavaScript 调用 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
适用于 Linux 的 Flash Player 9.0.31.0 及更高版本在以下浏览器中支持 ExternalInterface 类:
浏览器
Mozilla 1.7.x 及更高版本
Firefox 1.5.0.7 及更高版本
SeaMonkey 1.0.5 及更高版本
ExternalInterface 类要求用户的 Web 浏览器支持 ActiveX® 或由某些浏览器公开的 NPRuntime API 以实现插件脚本处理。即使上面未列出浏览器和操作系统组合,如果它们支持 NPRuntime API,则它们也应该支持 ExternalInterface 类。请访问 http://www.mozilla.org/projects/plugins/npruntime.html。
注意:在将 SWF 文件嵌入到 HTML 页中时,请确保设置 id 属性,并且 object 和 embed 标签的 id 和 name 属性不包含以下字符:
. - + ~~ / \
关于 Flash Player 应用程序的注意事项:Flash Player 版本 9.0.115.0 和更高版本允许。在 id 和 name 属性中使用 .(句点)字符。
关于 Flash Player 应用程序的注意事项:在运行于浏览器中的 Flash Player 10 和更高版本中,以编程方式使用此类打开弹出窗口可能会失败。不同的浏览器(和浏览器配置)可能会随时阻止弹出窗口;不能保证可以显示任何弹出窗口。不过,为了尽可能成功,请仅在作为用户操作的直接结果执行的代码中使用此类打开弹出窗口(例如,在鼠标单击或按键事件的事件处理函数中)。
利用 ActionScript,可以在 HTML 页上执行以下操作:
- 调用任何 JavaScript 函数。
- 传递任意数量、具有任意名称的参数。
- 传递各种数据类型(Boolean、Number、String 等等)。
- 接收来自 JavaScript 函数的返回值。
通过在 HTML 页上使用 JavaScript,可以:
- 调用 ActionScript 函数。
- 使用标准的函数调用表示法传递参数。
- 将值返回给 JavaScript 函数。
关于 Flash Player 应用程序的注意事项:当前,Flash Player 不支持在 HTML 表单内嵌入的 SWF 文件。
关于 AIR 应用程序的注意事项:在 Adobe AIR 中,ExternalInterface 类可用于在以下二者之间通信:一是在 HTMLLoader 控件中加载的 HTML 页面中的 JavaScript,一是在此 HTML 页面中嵌入的 SWF 内中的 ActionScript。
以下示例演示了在 Flash Player 与 HTML 容器之间发送数据的过程。
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);
}
}
}
}
为了测试前面的 ActionScript 代码,请使用以下 HTML 模板嵌入生成的 SWF 文件:
<!-- 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">
</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>