使用 ExternalInterface 类

ExternalInterface.available 属性指示当前的 Flash Player 是否位于提供外部接口的容器中。如果外部接口可用，则此属性为 true ；否则，为 false 。在使用 ExternalInterface 类中的任何其他功能之前，应始终进行检查以确保当前容器支持外部接口通信，如下所示：

if (ExternalInterface.available) 
{ 
    // Perform ExternalInterface method calls here. 
}

通过使用 ExternalInterface.objectID 属性，您可以确定 Flash Player 实例的唯一标识符（具体来说，是指 Internet Explorer 中 object 标签的 id 属性，或者是指使用 NPRuntime 接口的浏览器中 embed 标签的 name 属性）。这个唯一的 ID 代表浏览器中的当前 SWF 文档，并可用于对 SWF 文档进行引用 — 例如，在容器 HTML 页中调用 JavaScript 函数时进行引用。当 Flash Player 容器不是 Web 浏览器时，此属性为 null 。

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 函数，必须执行两项操作：向 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 格式字符串。

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 格式：

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

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

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

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

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