使用 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 的值,请编辑 objectembed 标签中的相应属性。

从容器中调用 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 浏览器对象的方法(即表示 objectembed 标签的 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# 类/值

格式

注释

null

null

<null/>

 

Boolean true

bool true

<true/>

 

Boolean false

bool false

<false/>

 

String

string

<string>字符串值</string>

 

Number、int、uint

single、double、int、uint

<number>27.5</number> 
<number>-12</number>
 

Array(元素可以是混合类型)

允许混合类型元素的集合,如 ArrayList 或 object[]

<array> 
    <property id="0"> 
        <number>27.5</number> 
    </property> 
    <property id="1"> 
        <string>Hello there!</string> 
    </property> 
    ... 
</array>

property 节点定义各个元素,而 id 属性为从零开始的数值索引。

Object

含有字符串键和对象值的字典,如具有字符串键的 HashTable

<object> 
    <property id="name"> 
        <string>John Doe</string> 
    </property> 
    <property id="age"> 
        <string>33</string> 
    </property> 
    ... 
</object>

property 节点定义各个属性,而 id 属性为属性名称(字符串)。

其他内置或自定义的类

 
<null/> or  
<object></object>

ActionScript 将其他对象编码为 null 或空对象。不管是哪种情况,所有属性值都会丢失。

注: 该表举例说明了 ActionScript 类,并且还列出了等效 C# 类;但是,外部 API 可用来与支持 ActiveX 控件的任何编程语言或运行时进行通信,而不仅限于 C# 应用程序。

通过将外部 API 用于 ActiveX 容器应用程序来构建您自己的应用程序时,您可能会发现,编写代理以执行将本机函数调用转换为序列化 XML 格式的任务是非常方便的。有关使用 C# 编写的代理类的示例,请参阅深入 ExternalInterfaceProxy 类内部