flash.external.ExternalInterface (Flex 3.2)

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

语言版本:

ActionScript 3.0

运行时版本:

AIR 1.0 Flash Player 9

ExternalInterface 类是外部 API，这是一个在 ActionScript 和 Flash Player 容器之间实现直接通信的应用程序编程接口，例如，包含 JavaScript 的 HTML 页。Adobe 建议使用 ExternalInterface 实现 JavaScript 与 ActionScript 之间的所有通信。

在 Flash Player 中，可以使用 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 9.0.115.0 版和更高版本允许在 id 和 name 属性中使用 .（句点）字符。

在浏览器中运行的 Flash Player 10 和更高版本中，以编程方式使用此类打开弹出窗口可能不会成功。不同的浏览器（和浏览器配置）可能会随时阻止弹出窗口；不能保证可以显示任何弹出窗口。不过，为了尽可能成功，请仅在作为用户操作的直接结果执行的代码中使用此类打开弹出窗口（例如，在鼠标单击或按键事件的事件处理函数中）。

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

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

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

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

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

注意：Adobe AIR 当前不支持 ExternalInterface 类。

查看示例

另请参见

flash.system.fscommand()
Accessing JavaScript functions from Flex
Accessing Flex from JavaScript
About ExternalInterface API security in Flex
External API requirements and advantages
Using the ExternalInterface class

	属性	定义方
		available : Boolean [静态] [只读 (read-only)] 指示此播放器是否位于提供外部接口的容器中。	ExternalInterface
		constructor : Object 对类对象或给定对象实例的构造函数的引用。	Object
		marshallExceptions : Boolean = false [静态] 指示外部接口是否应该尝试将 ActionScript 异常传递到当前浏览器并将 JavaScript 异常传递到 Flash Player。	ExternalInterface
		objectID : String [静态] [只读 (read-only)] 在 Internet Explorer 中返回 object 标签的 id 属性，或者在 Netscape 中返回 embed 标签的 name 属性。	ExternalInterface
		prototype : Object [静态] 对类或函数对象的原型对象的引用。	Object

	方法	定义方
		addCallback(functionName:String, closure:Function):void [静态] 将 ActionScript 方法注册为可从容器调用。	ExternalInterface
		call(functionName:String, ... arguments):* [静态] 调用由 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

运行时版本:

AIR 1.0 Flash Player 9

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

注意：将外部 API 与 HTML 一起使用时，应始终在尝试调用任何 JavaScript 方法之前检查 HTML 是否已完成加载。

实现
public static function get available():Boolean

另请参见

Getting information about the external container

示例

下面的示例使用 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

指示外部接口是否应该尝试将 ActionScript 异常传递到当前浏览器并将 JavaScript 异常传递到 Flash Player。必须显式将此属性设置为 true，以便在 ActionScript 中捕获 JavaScript 异常以及在 JavaScript 中捕获 ActionScript 异常。

另请参见

addCallBack()
try..catch..finally 语句

示例

下面的示例创建一个 ActionScript 函数，并使用 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

属性

objectID:String [只读 (read-only)]

语言版本:

ActionScript 3.0

运行时版本:

AIR 1.0 Flash Player 9

在 Internet Explorer 中返回 object 标签的 id 属性，或者在 Netscape 中返回 embed 标签的 name 属性。

实现
public static function get objectID():String

另请参见

Getting information about the external container

方法详细信息

addCallback

()

方法

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

语言版本:

ActionScript 3.0

运行时版本:

AIR 1.0 Flash Player 9

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

注意：对于在浏览器中运行的本地内容，仅当 SWF 文件以及包含它的网页位于受信任的本地安全沙箱中时，对 ExternalInterface.addCallback() 方法的调用才有效。有关详细信息，请参阅以下部分：

“安全性”一章（位于《ActionScript 3.0 编程》一书中）和有关 LiveDocs 的最新评论
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` — 包含环境属于调用代码无权访问的安全沙箱。若要解决此问题，请按照下列步骤操作：在包含 SWF 文件的 HTML 页中，在该文件的 `object` 标签中设置以下参数： `<param name="allowScriptAccess" value="always" />` 在 SWF 文件中，添加以下 ActionScript： `flash.system.Security.allowDomain(sourceDomain )`

另请参见

flash.system.Security.allowDomain()
Calling ActionScript code from the container

call

()

方法

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

语言版本:

ActionScript 3.0

运行时版本:

AIR 1.0 Flash Player 9

调用由 Flash Player 容器公开的函数，不传递参数或传递多个参数。如果该函数不可用，调用将返回 null；否则，它返回由该函数提供的值。不允许在 Opera 或 Netscape 浏览器中使用递归；在这些浏览器上，递归调用将生成 null 响应。（Internet Explorer 和 Firefox 浏览器上支持递归。）

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

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

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

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

“安全性”一章（位于《ActionScript 3.0 编程》一书中）和有关 LiveDocs 的最新评论
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` — 包含环境属于调用代码无权访问的安全沙箱。若要解决此问题，请按照下列步骤操作：在包含 SWF 文件的 HTML 页中，在该文件的 `object` 标签中设置以下参数： `<param name="allowScriptAccess" value="always" />` 在 SWF 文件中，添加以下 ActionScript： `flash.system.Security.allowDomain(sourceDomain )`

另请参见

Calling external code from ActionScript

示例如何使用示例

ExternalInterfaceExample.as

以下示例演示了在 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>

Adobe® Flex™ 3.2 语言参考		全部包 \| 全部类 \| 语言元素 \| 索引 \| 附录 \| 约定 \| 框架无框架
ExternalInterface	属性 \| 方法 \| 事件 \| 样式 \| 效果 \| 常量 \| 示例