ExternalInterface

公告

ExternalInterface	属性 \| 方法 \| 示例

包	flash.external
类	public final class ExternalInterface
继承	ExternalInterface Object

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

ExternalInterface 类是外部 API，在 ActionScript 和 Flash Player 的容器之间实现直接通讯的应用程序编程接口，例如，含有 JavaScript 的 HTML 页。推荐对所有 JavaScript 与 ActionScript 之间的通信使用 ExternalInterface。

在 HTML 页中使用 JavaScript，可以调用 Flash Player 中的 ActionScript 函数。 ActionScript 函数可以返回一个值，JavaScript 会立即接收它作为该调用的返回值。

此功能替代了较旧的 fscommand() 方法。

在以下浏览器和操作系统的组合中可以使用 ExternalInterface 类：

浏览器	操作系统	操作系统
Internet Explorer 5.0 及更高版本	Windows
Netscape 8.0 及更高版本	Windows	Macintosh
Mozilla 1.7.5 及更高版本	Windows	Macintosh
Firefox 1.0 及更高版本	Windows	Macintosh
Safari 1.3 及更高版本		Macintosh

ExternalInterface 类要求用户的 Web 浏览器支持 ActiveX 或由某些浏览器公开的 NPRuntime API 以实现插件脚本处理。请访问 http://www.mozilla.org/projects/plugins/npruntime.html。

注意：在将 SWF 文件嵌入到 HTML 页中时，请确保 <object> 和 <embed> 标签的 id 和 name 属性不包括诸如以下的字符：（句点）、-、+、*、/ 和 \。

利用 ActionScript，可以在 HTML 页上执行以下操作：

调用任何 JavaScript 函数。
传递任意数量、具有任意名称的参数。
传递各种数据类型（Boolean、Number、String 等等）。
接收来自 JavaScript 函数的返回值。

通过在 HTML 页上使用 JavaScript，可以：

调用 ActionScript 函数。
使用标准的函数调用表示法传递参数。
将值返回给 JavaScript 函数。

注意：Flash Player 当前不支持嵌入到 HTML 表单中的 SWF 文件。

查看示例

另请参见

flash.system.fscommand()
外部 API 要求和优点
使用 ExternalInterface 类

公共属性

隐藏继承的公共属性

显示继承的公共属性

	属性		定义方
		available : Boolean [static] [read-only] 指示此播放器是否位于提供外部接口的容器中。	ExternalInterface
		constructor : Object 对类对象或给定对象实例的构造函数的引用。	Object
		objectID : String [static] [read-only] 在 Internet Explorer 中，返回 <object> 标签的 id 属性；在 Netscape 中，返回 <embed> 标签的 name 属性。	ExternalInterface
		prototype : Object [static] 对类或函数对象的原型对象的引用。	Object

公共方法

隐藏继承的公共方法

显示继承的公共方法

	方法		定义方
		addCallback(functionName:String, closure:Function):void [static] 将 ActionScript 方法注册为可从容器调用。	ExternalInterface
		call(functionName:String, ... arguments):* [static] 调用由 Flash Player 容器公开的函数，不传递参数或传递多个参数。	ExternalInterface
		hasOwnProperty(name:String):Boolean 指示对象是否已经定义了指定的属性。	Object
		isPrototypeOf(theClass:Object):Boolean 指示 Object 类的实例是否在指定为参数的对象的原型链中。	Object
		propertyIsEnumerable(name:String):Boolean 指示指定的属性是否存在、是否可枚举。	Object
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void 设置循环操作动态属性的可用性。	Object
		toString():String 返回指定对象的字符串表示形式。	Object
		valueOf():Object 返回指定对象的原始值。	Object

属性详细信息

available

属性

available:Boolean [read-only]

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

指示此播放器是否位于提供外部接口的容器中。如果外部接口可用，则此属性为 true；否则，为 false。

注意：将 External 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);
}
}
}

objectID

属性

objectID:String [read-only]

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

在 Internet Explorer 中，返回 <object> 标签的 id 属性；在 Netscape 中，返回 <embed> 标签的 name 属性。

实现
public static function get objectID():String

另请参见

获取有关外部容器的信息

方法详细信息

addCallback

()

方法

public static function addCallback(functionName:String, closure:Function):void

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

将 ActionScript 方法注册为可从容器调用。成功调用 addCallBack() 后，容器中的 JavaScript 或 ActiveX 代码可以调用在 Flash Player 中注册的函数。

安全提示：对于运行在浏览器中的 local 内容，只有当 SWF 文件以及包含网页位于 local-trusted 安全沙箱中时，对 ExternalInterface.addCallback() 方法的调用才有效。有关详细信息，请参阅以下部分：

security chapter（在《ActionScript 3.0 编程》一书中）和有关 LiveDocs 的最新注释
Flash Player 9 Security White Paper

参数

	`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` — 包含环境属于调用代码无权访问的安全沙箱。修正此问题：在包含 HTML 页中的 SWF 文件的 `<object>` 标签中，设置以下参数： `<param name="allowScriptAccess" value="always" />` 在 SWF 文件中，添加以下 ActionScript： `flash.system.Security.allowDomain(sourceDomain)`

另请参见

flash.system.Security.allowDomain()
从容器中调用 ActionScript 代码

call

()

方法

public static function call(functionName:String, ... arguments):*

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

调用由 Flash Player 容器公开的函数，不传递参数或传递多个参数。如果所需的函数不可用，则调用返回 null；否则，将返回由该函数提供的值。不允许使用递归；递归调用会生成 null 响应。

如果容器是 HTML 页，则此方法在 <script> 元素中调用 JavaScript 函数。

如果该容器是其它某个 ActiveX 容器，则此方法会使用指定的名称触发 FlashCall ActiveX 事件，并且该容器会处理该事件。

如果该容器承载 Netscape 插件，您可以写入对新 NPRuntime 接口的自定义支持或嵌入 HTML 控件以及在 HTML 控件内嵌入 Flash Player。如果嵌入 HTML 控件，就可以通过与本机容器应用程序通迅的 JavaScript 接口与 Flash Player 进行通讯。

安全提示：对于运行在浏览器中的 local 内容，只有当 SWF 文件以及包含网页（如果有）位于 local-trusted 安全沙箱中时，才允许调用 ExternalInterface.call() 方法。还可以在包含 SWF 内容的 HTML 页中设置 object 和 embed 标签的 allowNetworking 参数，防止 SWF 文件使用此方法。有关详细信息，请参阅以下部分：

security chapter（在《ActionScript 3.0 编程》一书中）和有关 LiveDocs 的最新注释
Flash Player 9 Security White Paper

参数

	`functionName:String` — 要在容器中调用的函数的名称。

	`... arguments` — 传递到容器中的函数的参数。您可以指定零个或多个参数，参数之间用逗号分隔。这些参数可以是任何 ActionScript 数据类型。当调用 JavaScript 函数时，ActionScript 类型自动封装到 JavaScript 类型中；当调用其它某个 ActiveX 容器时，将在请求消息中对参数进行编码。

* — 从容器接收的响应。如果调用失败（例如，当容器中没有这种函数时、接口不可用时、发生递归时，或出现安全问题时），则返回 null 并引发错误。

引发

	`Error` — 如果容器不支持传出调用，将引发错误。只有 Windows 的 Internet Explorer 和使用 NPRuntime API 的浏览器（如 Mozilla 1.7.5 及其更高版本，或 Firefox 1.0 及其更高版本）才支持。

	`SecurityError` — 包含环境属于调用代码无权访问的安全沙箱。通过给包含环境中的 `allowScriptAccess` 设置一个合适的值（通常通过使用 HTML 中的 `allowScriptAccess` `<object>` / `<embed>` 标签来进行），可以解决此问题。

另请参见

从 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="center"
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>

posted on 2007-11-02 08:25 作者名阅读(2733) 评论(0) 编辑收藏举报

会员力量，点亮园子希望

刷新页面返回顶部

烂草堆

公告

ExternalInterface