| 包 | flash.external |
| 类 | public final class ExternalInterface |
| 继承 | ExternalInterface  Object |
| 语言版本: | ActionScript 3.0 |
| 运行时版本: | AIR 1.0, Flash Player 9, Flash Lite 4 |
通过 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。
相关 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 容器公开的函数，传递零个参数或传递多个参数。 | 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。
注意：将外部 API 与 HTML 一起使用时，应始终在尝试调用任何 JavaScript 方法之前检查 HTML 是否已完成加载。
实现
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 代码调用。
注意：对于在浏览器中运行的本地内容，仅当 SWF 文件以及包含它的网页位于受信任的本地安全沙箱中时，对 ExternalInterface.addCallback() 方法的调用才有效。有关详细信息，请参阅 Flash Player 开发人员中心主题：安全性。
参数
functionName:String — 容器可用于调用函数的名称。
| |
closure:Function — 要调用的 closure 函数。这可能是一个独立的函数，或者可能是引用对象实例方法的 closure 方法。通过传递 closure 方法，可以将回调定向到特定对象实例的方法。
注意：对闭包值为 |
引发
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 容器公开的函数，传递零个参数或传递多个参数。如果该函数不可用，调用将返回 null；否则，它返回由该函数提供的值。不允许在 Opera 或 Netscape 浏览器中使用递归；在这些浏览器上，递归调用将生成 null 响应。（Internet Explorer 和 Firefox 浏览器上支持递归。）
如果该容器是 HTML 页，则此方法在 script 元素中调用 JavaScript 函数。
如果该容器是某个其他 ActiveX 容器，此方法将使用指定的名称调度 FlashCall ActiveX 事件，并且该容器将处理该事件。
如果容器承载 Netscape 插件，您可以编写对新 NPRuntime 接口的自定义支持，或嵌入 HTML 控件并在此控件内嵌入播放器。如果嵌入 HTML 控件，可以通过本机容器应用程序的 JavaScript 接口与播放器通信。
注意：对于在浏览器中运行的本地内容，仅当 SWF 文件以及包含它的网页（如果有）位于受信任的本地安全沙箱中时，才允许调用 ExternalInterface.call() 方法。此外，还可以在包含 SWF 内容的 HTML 页中设置 object 和 embed 标签的 allowNetworking 参数，以防止 SWF 文件使用此方法。有关详细信息，请参阅 Flash Player 开发人员中心主题：安全性。
关于 Flash Player 应用程序的注意事项：在 Flash Player 10 和 Flash Player 9 Update 5 中，如果启用了弹出窗口阻止程序，某些 Web 浏览器会限制此方法。在这种情况下，只有在响应用户事件（例如，在鼠标单击或按键事件的事件处理函数中）时才能成功调用此方法。
参数
functionName:String — 要在容器中调用的函数的字母数字名称。若使用非字母数字函数名称，则将导致出现运行时错误（错误 2155）。可以使用 try..catch 块处理此错误。
| |
... arguments — 传递到容器中的函数的参数。您可以指定零个或多个参数，参数之间用逗号分隔。它们可以是任何 ActionScript 数据类型。如果调用的是 JavaScript 函数，则会自动将 ActionScript 类型转换为 JavaScript 类型；如果调用的是某个其他 ActiveX 容器，则会在请求消息中对参数进行编码。
|
* — 从容器接收的响应。如果调用失败，则会返回 null 并引发错误；例如，如果容器中没有此类函数、接口不可用、发生递归（使用 Netscape 或 Opera 浏览器）或出现安全问题。
|
引发
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, 11:04 AM Z