使用 ExternalInterface 类Flash Player 9 和更高版本,Adobe AIR 1.0 和更高版本 ActionScript 与容器应用程序之间的通信方式有两种:ActionScript 可以调用容器中定义的代码(如 JavaScript 函数),或者容器中的代码可以调用被指定为可调用函数的 ActionScript 函数。在这两种情况下,都可以将信息发送给被调用的代码,而将结果返回给执行调用的代码。 为了便于这种通信,ExternalInterface 类包含了两个静态属性和两个静态方法。这些属性和方法可用于获取有关外部接口连接的信息,从 ActionScript 执行容器中的代码,以及使 ActionScript 函数可供容器调用。 获取有关外部容器的信息ExternalInterface.available 属性指示当前的 Flash Player 是否位于提供外部接口的容器中。如果外部接口可用,则此属性为 true;否则,为 false。在使用 ExternalInterface 类中的任何其他功能之前,应始终进行检查以确保当前容器支持外部接口通信,如下所示: if (ExternalInterface.available) { // Perform ExternalInterface method calls here. } 注: ExternalInterface.available 属性报告当前容器是否为支持 ExternalInterface 连接的容器类型。它不会报告当前浏览器中是否启用了 JavaScript。
通过使用 ExternalInterface.objectID 属性,您可以确定 Flash Player 实例的唯一标识符(具体来说,是指 Internet Explorer 中 object 标签的 id 属性,或者是指使用 NPRuntime 接口的浏览器中 embed 标签的 name 属性)。这个唯一的 ID 代表浏览器中的当前 SWF 文档,并可用于对 SWF 文档进行引用 — 例如,在容器 HTML 页中调用 JavaScript 函数时进行引用。当 Flash Player 容器不是 Web 浏览器时,此属性为 null。 从 ActionScript 中调用外部代码ExternalInterface.call() 方法执行容器应用程序中的代码。它至少需要一个参数,即包含容器应用程序中要调用函数的名称的字符串。传递给 ExternalInterface.call() 方法的其他任何参数均作为函数调用的参数传递给容器。 // calls the external function "addNumbers" // passing two parameters, and assigning that function's result // to the variable "result" var param1:uint = 3; var param2:uint = 7; var result:uint = ExternalInterface.call("addNumbers", param1, param2); 如果容器为 HTML 页,此方法将调用具有指定名称的 JavaScript 函数,必须在包含 HTML 页中的 script 元素中定义该函数。JavaScript 函数的返回值被传递回 ActionScript。 <script language="JavaScript"> // adds two numbers, and sends the result back to ActionScript function addNumbers(num1, num2) { return (num1 + num2); } </script> 如果容器为其他的 ActiveX 容器,此方法将导致 Flash Player ActiveX 控件调度它的 FlashCall 事件。Flash Player 将指定的函数名及所有参数序列化为一个 XML 字符串。容器可以在事件对象的 request 属性中访问该信息,并用它来确定如何执行它自己的代码。为了将值返回 ActionScript,容器代码会调用 ActiveX 对象的 SetReturnValue() 方法,并将结果(序列化为一个 XML 字符串)作为该方法的参数进行传递。有关用于此通信的 XML 格式的详细信息,请参阅外部 API 的 XML 格式。 无论容器为 Web 浏览器还是为其他 ActiveX 容器,只要调用失败或容器方法没有指定返回值,都将返回 null。如果包含环境属于调用代码无权访问的安全沙箱,ExternalInterface.call() 方法将引发 SecurityError 异常。可以通过在包含环境中为 allowScriptAccess 设置合适的值来解决此问题。例如,要在 HTML 页中更改 allowScriptAccess 的值,请编辑 object 和 embed 标签中的相应属性。 从容器中调用 ActionScript 代码容器只能调用函数中的 ActionScript 代码,不能调用任何其他 ActionScript 代码。若要从容器应用程序调用 ActionScript 函数,必须执行两项操作:向 ExternalInterface 类注册该函数,然后从容器的代码调用该函数。 首先,必须注册 ActionScript 函数,指示其应能够为容器所用。使用 ExternalInterface.addCallback() 方法,如下所示: function callMe(name:String):String { return "busy signal"; } ExternalInterface.addCallback("myFunction", callMe); addCallback() 方法有两个参数。第一个参数为 String 类型的函数名,容器将籍此名称得知要调用的函数。第二个参数为容器调用定义的函数名时要执行的实际 ActionScript 函数。由于这些名称是截然不同的,因此可以指定将由容器使用的函数名,即使实际的 ActionScript 函数具有不同的名称。这在函数名未知的情况下特别有用 — 例如,指定了匿名函数或需要在运行时确定要调用的函数。 一旦向 ExternalInterface 类注册了 ActionScript 函数,容器就可以实际调用该函数。完成该操作的具体方法依容器的类型而定。例如,在 Web 浏览器的 JavaScript 代码中,使用已注册的函数名调用 ActionScript 函数,就像它是 Flash Player 浏览器对象的方法(即表示 object 或 embed 标签的 JavaScript 对象的方法)。也就是说,将传递参数并返回结果,就如同调用本地函数一样。 <script language="JavaScript"> // callResult gets the value "busy signal" var callResult = flashObject.myFunction("my name"); </script> ... <object id="flashObject"...> ... <embed name="flashObject".../> </object> 或者,在运行于台式机应用程序中的 SWF 文件中调用 ActionScript 函数时,必须将已注册的函数名及所有参数序列化为一个 XML 格式的字符串。然后,将该 XML 字符串作为一个参数来调用 ActiveX 控件的 CallFunction() 方法,以实际执行该调用。有关用于此通信的 XML 格式的详细信息,请参阅外部 API 的 XML 格式。 不管是哪种情况,ActionScript 函数的返回值都被传递回容器代码,当调用方为浏览器中的 JavaScript 代码时直接作为值返回,而当调用方为 ActiveX 容器时则会序列化为 XML 格式字符串。 外部 API 的 XML 格式ActionScript 与承载 Shockwave Flash ActiveX 控件的应用程序间的通信使用特定的 XML 格式对函数调用和值进行编码。外部 API 使用的 XML 格式分为两种。一种格式用于表示函数调用。另一种格式用于表示各个值;此格式用于函数中的参数及函数返回值。函数调用的 XML 格式用于对 ActionScript 的调用和来自 ActionScript 的调用。对于来自 ActionScript 的函数调用,Flash Player 将 XML 传递给容器;而对于来自容器的调用,Flash Player 需要容器应用程序将向其传递一个此格式的 XML 字符串。下面的 XML 片断说明了一个 XML 格式的函数调用示例: <invoke name="functionName" returntype="xml"> <arguments> ... (individual argument values) </arguments> </invoke> 根节点为 invoke 节点。它具有两个属性:name,指示要调用的函数的名称;以及 returntype,总是为 xml。如果函数调用包括参数,则 invoke 节点具有一个 arguments 子节点,该节点的子节点是使用单个值格式(下面将予以说明)进行了格式设置的参数值。 每个值(包括函数参数和函数返回值)均使用一个格式设置方案,除了实际值之外,该方案还包括数据类型信息。下表列出了 ActionScript 类以及用于对该数据类型的值进行编码的 XML 格式:
注: 该表举例说明了 ActionScript 类,并且还列出了等效 C# 类;但是,外部 API 可用来与支持 ActiveX 控件的任何编程语言或运行时进行通信,而不仅限于 C# 应用程序。
通过将外部 API 用于 ActiveX 容器应用程序来构建您自己的应用程序时,您可能会发现,编写代理以执行将本机函数调用转换为序列化 XML 格式的任务是非常方便的。有关使用 C# 编写的代理类的示例,请参阅深入 ExternalInterfaceProxy 类内部。 |
|