AIR.SWF 浏览器内 API

自定义无缝安装 badge.swf

除了使用 SDK 随附的 badge.swf 文件,您还可以创建自己的 SWF 文件以供在浏览器页面中使用。自定义的 SWF 文件可以通过以下方式与运行时进行交互:

所有这些功能都是通过在承载于 adobe.com 上的 SWF 文件 air.swf 中调用 API 提供的。您可以自定义 badge.swf 文件并从自己的 SWF 文件中调用 air.swf API。

另外,在浏览器中运行的 SWF 文件可以通过使用 LocalConnection 类与正在运行的 AIR 应用程序通信。有关详细信息,请参阅与其他 Flash Player 和 AIR 实例通信(针对 ActionScript 开发人员)或与其他 Flash Player 和 AIR 实例通信(针对 HTML 开发人员)。

重要说明: 本节中所述的功能(以及 air.swf 文件中的 API)要求最终用户在 Windows 或 Mac OS 的 Web 浏览器中安装 Adobe® Flash® Player 9 更新 3。在 Linux 中,无缝安装功能需要 Flash Player 10(10.0.12.36 版或更高版本)。您可以编写代码来检查已安装的 Flash Player 版本,如果未安装所需的 Flash Player 版本,可以为用户提供替代界面。例如,如果安装的是 Flash Player 的旧版本,您可以提供下载 AIR 文件版本的链接(而不是使用 badge.swf 文件或 air.swf API 来安装应用程序)。

使用 badge.swf 文件安装 AIR 应用程序

AIR SDK 和 Flex SDK 中包含一个 badge.swf 文件,通过此文件,您可轻松使用无缝安装功能。badge.swf 可以从网页中的链接安装运行时和 AIR 应用程序。为您提供了 badge.swf 文件及其源代码以供您在您的网站上分发。

在网页中嵌入 badge.swf 文件

  1. 找到下列文件(这些文件已在 AIR SDK 或 Flex SDK 的 samples/badge 目录中提供),然后将它们添加到您的 Web 服务器。

    • badge.swf

    • default_badge.html

    • AC_RunActiveContent.js

  2. 在文本编辑器中打开 default_badge.html 页。

  3. 在 default_badge.html 页中的 AC_FL_RunContent() JavaScript 函数中,调整以下参数的 FlashVars 参数定义:

    参数

    说明

    appname

    应用程序的名称,如果没有安装运行时,则由 SWF 文件显示。

    appurl

    (必需)。要下载的 AIR 文件的 URL。必须使用绝对(而非相对)URL。

    airversion

    (必需)。对于运行时 1.0 版,将此参数设置为 1.0。

    imageurl

    要在标志中显示的图像(可选)的 URL。

    buttoncolor

    下载按钮的颜色(以十六进制值的形式指定,例如 FFCC00)。

    messagecolor

    如果没有安装运行时,则为按钮下方显示的文本消息的颜色(以十六进制值的形式指定,如 FFCC00)。

  4. badge.swf 文件的最小大小为 217 像素宽 x 180 像素高。调整 AC_FL_RunContent() 函数的 widthheight 参数的值,以满足您的需要。

  5. 重命名 default_badge.html 文件并调整其代码(或将其包含在另一个 HTML 页中),以满足您的需要。

注: 对于加载 badge.swf 文件的 HTML embed 标签,不要设置 wmode 属性;将其保留为默认设置 ("window")。其他 wmode 设置将阻止在某些系统上安装。同样,使用其他 wmode 设置会产生错误:“Error #2044: Unhandled ErrorEvent:.text=Error #2074: The stage is too small to fit the download ui.”。

您也可以编辑和重新编译 badge.swf 文件。有关详细信息,请参阅修改 badge.swf 文件

从网页中的无缝安装链接安装 AIR 应用程序

将无缝安装链接添加到页面中后,用户即可通过在 SWF 文件中单击此链接来安装 AIR 应用程序。

  1. 在已安装 Flash Player(Windows 和 Mac OS 中为版本 9 更新 3 或更高版本,Linux 中为版本 10)的 Web 浏览器中导航到此 HTML 页。

  2. 在此网页中,单击 badge.swf 文件中的链接。

    • 如果您已安装运行时,请跳至下一步。

    • 如果您尚未安装运行时,将显示一个对话框,询问您是否要安装它。安装运行时(请参阅 Adobe AIR 安装),然后接着执行下一步。

  3. 在“安装”窗口中,保留默认设置处于选定状态不变,然后单击“继续”。

    在 Windows 计算机中,AIR 会自动执行以下操作:

    • 将应用程序安装到 c:\Program Files\ 中

    • 为此应用程序创建一个桌面快捷方式

    • 创建“开始”菜单快捷方式

    • 在“添加/删除程序”控制面板中添加一个应用程序条目

    在 Mac 操作系统中,安装程序会将该应用程序添加到 Applications 目录(例如,添加到 Mac 操作系统中的 /Applications 目录中)。

    在 Linux 计算机上,AIR 自动执行以下操作:

    • 将应用程序安装到 /opt 中。

    • 为此应用程序创建一个桌面快捷方式

    • 创建“开始”菜单快捷方式

    • 在系统包管理器中加入该应用程序的条目

  4. 选择所需选项,然后单击“安装”按钮。

  5. 安装完成后,单击“完成”。

修改 badge.swf 文件

Flex SDK 和 AIR SDK 提供了 badge.swf 文件的源文件。这些文件包含在 SDK 的 samples/badge 文件夹中:

源文件

说明

badge.fla

用于编译 badge.swf 文件的 Flash 源文件。badge.fla 文件编译成 SWF 9 文件(可以在 Flash Player 中加载)。

AIRBadge.as

定义在 basdge.fla 文件中使用的基类的 ActionScript 3.0 类。

您可以使用 Flash Professional 重新设计 badge.fla 文件的可视界面。

AIRBadge() 构造函数在 AIRBadge 类中定义,用于加载承载于 http://airdownload.adobe.com/air/browserapi/air.swf 上的 air.swf 文件。air.swf 文件包含用于使用无缝安装功能的代码。

成功加载 air.swf 文件时,会调用 onInit() 方法(在 AIRBadge 类中):

private function onInit(e:Event):void { 
    _air = e.target.content; 
    switch (_air.getStatus()) { 
        case "installed" : 
            root.statusMessage.text = ""; 
            break; 
        case "available" : 
            if (_appName && _appName.length > 0) { 
                root.statusMessage.htmlText = "<p align='center'><font color='#"  
                        + _messageColor + "'>In order to run " + _appName +  
                        ", this installer will also set up Adobe® AIR®.</font></p>"; 
            } else { 
                root.statusMessage.htmlText = "<p align='center'><font color='#"  
                        + _messageColor + "'>In order to run this application, " 
                        + "this installer will also set up Adobe® AIR®.</font></p>"; 
            } 
            break; 
        case "unavailable" : 
            root.statusMessage.htmlText = "<p align='center'><font color='#"  
                        + _messageColor  
                        + "'>Adobe® AIR® is not available for your system.</font></p>"; 
            root.buttonBg_mc.enabled = false; 
            break; 
    } 
}

此代码将全局 _air 变量设置为所加载的 air.swf 文件的主类。此类包括以下公共方法,badge.swf 文件通过访问这些方法来调用无缝安装功能:

方法

说明

getStatus()

确定计算机上是否已安装(或是否可以安装)运行时。有关详细信息,请参阅检查是否已安装运行时
  • runtimeVersion - 指示要安装的应用程序所需的运行时版本(例如"1.0.M6")的字符串。

installApplication()

在用户的计算机上安装指定的应用程序。有关详细信息,请参阅从浏览器安装 AIR 应用程序

  • url - 定义 URL 的字符串。必须使用绝对(而非相对)URL 路径。

  • runtimeVersion — 指示要安装的应用程序所需的运行时版本(例如 "2.5")的字符串。

  • arguments - 要传递给此应用程序的参数(如果此应用程序在安装后启动)。如果在应用程序描述符文件中将 allowBrowserInvocation 元素设置为 true,则应用程序会在安装后启动。(有关应用程序描述符文件的详细信息,请参阅 AIR 应用程序描述符文件。)如果因从浏览器进行无缝安装而导致应用程序启动(用户选择在安装后启动),则仅当传递参数时,应用程序的 NativeApplication 对象才调度 BrowserInvokeEvent 对象。请考虑您传递给应用程序的数据存在的安全隐患。有关详细信息,请参阅从浏览器启动安装的 AIR 应用程序

urlruntimeVersion 的设置通过容器 HTML 页中的 FlashVars 设置传入 SWF 文件。

如果应用程序在安装后自动启动,您可以使用 LocalConnection 通信让已安装的应用程序在调用时与 badge.swf 文件联系。有关详细信息,请参阅与其他 Flash Player 和 AIR 实例通信(针对 ActionScript 开发人员)或与其他 Flash Player 和 AIR 实例通信(针对 HTML 开发人员)。

您也可以调用 air.swf 文件的 getApplicationVersion() 方法来检查是否已安装应用程序。可以在开始应用程序安装过程之前调用此方法,亦可在安装开始之后进行调用。有关详细信息,请参阅从网页检查是否已安装 AIR 应用程序

加载 air.swf 文件

您可以创建自己的 SWF 文件,使之使用 air.swf 文件中的 API 从浏览器中的网页与运行时和 AIR 应用程序交互。air.swf 文件承载于 http://airdownload.adobe.com/air/browserapi/air.swf。若要从 SWF 文件中引用 air.swf API,请将 air.swf 文件加载到 SWF 文件所在的应用程序域中。下面的代码显示了将 air.swf 文件加载到执行加载的 SWF 文件所在的应用程序域中的示例:

var airSWF:Object; // This is the reference to the main class of air.swf 
var airSWFLoader:Loader = new Loader(); // Used to load the SWF 
var loaderContext:LoaderContext = new LoaderContext();  
                                // Used to set the application domain  
 
loaderContext.applicationDomain = ApplicationDomain.currentDomain; 
 
airSWFLoader.contentLoaderInfo.addEventListener(Event.INIT, onInit); 
airSWFLoader.load(new URLRequest("http://airdownload.adobe.com/air/browserapi/air.swf"),  
                    loaderContext); 
 
function onInit(e:Event):void  
{ 
    airSWF = e.target.content; 
}

一旦加载了 air.swf 文件(Loader 对象的 contentLoaderInfo 对象调度 init 事件时),您就可以调用任何 air.swf API,如下面部分所述。

注: 与 AIR SDK 和 Flex SDK 一起提供的 badge.swf 文件将自动加载 air.swf 文件。请参阅使用 badge.swf 文件安装 AIR 应用程序。本节中的说明适用于创建您自己的加载 air.swf 文件的 SWF 文件。

检查是否已安装运行时

SWF 文件可以通过在从 http://airdownload.adobe.com/air/browserapi/air.swf 加载的 air.swf 文件中调用 getStatus() 方法,检查是否已安装运行时。有关详细信息,请参阅加载 air.swf 文件

加载 air.swf 文件后,SWF 文件便可以调用 air.swf 文件的 getStatus() 方法,如下所示:

var status:String = airSWF.getStatus();

getStatus() 方法会根据计算机上运行时的状态,返回下列字符串值之一:

字符串值

说明

"available"

运行时可以安装在此计算机上,但当前未安装。

"unavailable"

运行时无法安装在此计算机上。

"installed"

运行时已安装在此计算机上。

如果浏览器中未安装所需的 Flash Player 版本(Windows 和 Mac OS 中为版本 9 更新 3 或更高版本,Linux 中为版本 10),则 getStatus() 方法会引发错误。

从网页检查是否已安装 AIR 应用程序

SWF 文件可以通过在从 http://airdownload.adobe.com/air/browserapi/air.swf 加载的 air.swf 文件中调用 getApplicationVersion() 方法,检查是否已安装 AIR 应用程序(具有匹配的应用程序 ID 和发行商 ID)。有关详细信息,请参阅加载 air.swf 文件

加载 air.swf 文件后,SWF 文件便可以调用 air.swf 文件的 getApplicationVersion() 方法,如下所示:

var appID:String = "com.example.air.myTestApplication"; 
var pubID:String = "02D88EEED35F84C264A183921344EEA353A629FD.1"; 
airSWF.getApplicationVersion(appID, pubID, versionDetectCallback); 
 
function versionDetectCallback(version:String):void 
{ 
    if (version == null) 
    { 
        trace("Not installed."); 
        // Take appropriate actions. For instance, present the user with 
        // an option to install the application. 
    } 
    else 
    { 
        trace("Version", version, "installed."); 
        // Take appropriate actions. For instance, enable the 
        // user interface to launch the application. 
    } 
}

getApplicationVersion() 方法具有如下参数:

参数

说明

appID

此应用程序的应用程序 ID。有关详细信息,请参阅 id

pubID

此应用程序的发行商 ID。有关详细信息,请参阅 publisherID。如果所讨论的应用程序没有发行商 ID,请将 pubID 参数设置为空字符串 (“”)。

callback

用作处理函数的回调函数。getApplicationVersion() 方法异步运行,在检测到已安装的版本(或没有已安装的版本)时,会调用此回调方法。回调方法定义必须包含一个参数,此参数为一个字符串,设置为已安装的应用程序的版本字符串。如果未安装此应用程序,则会将一个 null 值传递给此函数,如上一代码示例所示。

如果浏览器中未安装所需的 Flash Player 版本(Windows 和 Mac OS 中为版本 9 更新 3 或更高版本,Linux 中为版本 10),则 getApplicationVersion() 方法会引发错误。

注: 从 AIR 1.5.3 开始,将弃用发行商 ID。不再自动向应用程序分配发行商 ID。为了向后兼容,应用程序可以继续指定发行商 ID。

从浏览器安装 AIR 应用程序

SWF 文件可以通过在从 http://airdownload.adobe.com/air/browserapi/air.swf 加载的 air.swf 文件中调用 installApplication() 方法,安装 AIR 应用程序。有关详细信息,请参阅加载 air.swf 文件

加载 air.swf 文件后,SWF 文件便可以调用 air.swf 文件的 installApplication() 方法,如下面的代码中所示:

var url:String = "http://www.example.com/myApplication.air"; 
var runtimeVersion:String = "1.0"; 
var arguments:Array = ["launchFromBrowser"]; // Optional 
airSWF.installApplication(url, runtimeVersion, arguments); 

installApplication() 方法用于在用户的计算机上安装指定的应用程序。此方法具有以下参数:

参数

说明

url

一个字符串,定义要安装的 AIR 文件的 URL。必须使用绝对(而非相对)URL 路径。

runtimeVersion

一个字符串,指示要安装的应用程序所需的运行时版本(例如“1.0”)。

arguments

要传递给此应用程序的参数数组(如果此应用程序在安装后启动)。参数中只能识别字母数字字符。如果需要传递其他值,请考虑使用编码方案。

如果在应用程序描述符文件中将 allowBrowserInvocation 元素设置为 true,则应用程序会在安装后启动。(有关应用程序描述符文件的详细信息,请参阅 AIR 应用程序描述符文件。)如果因从浏览器进行无缝安装而导致应用程序启动(用户选择在安装后启动),则仅当已传递参数时,应用程序的 NativeApplication 对象才调度 BrowserInvokeEvent 对象。有关详细信息,请参阅从浏览器启动安装的 AIR 应用程序

仅当在用户事件(例如鼠标单击)的事件处理函数中调用 installApplication() 方法时,此方法才能执行。

如果浏览器中未安装所需的 Flash Player 版本(Windows 和 Mac OS 中为版本 9 更新 3 或更高版本,Linux 中为版本 10),则 installApplication() 方法会引发错误。

在 Mac 操作系统中,若要安装某一应用程序的更新版本,用户必须拥有足够的系统权限才能将新版本安装到应用程序目录中(如果此应用程序更新运行时,则还须拥有管理权限)。在 Windows 中,用户必须具有管理权限。

您也可以调用 air.swf 文件的 getApplicationVersion() 方法来检查是否已安装应用程序。可以在开始应用程序安装过程之前调用此方法,亦可在安装开始之后进行调用。有关详细信息,请参阅从网页检查是否已安装 AIR 应用程序。此应用程序运行后便可以通过使用 LocalConnection 类与浏览器中的 SWF 内容通信。有关详细信息,请参阅与其他 Flash Player 和 AIR 实例通信(针对 ActionScript 开发人员)或与其他 Flash Player 和 AIR 实例通信(针对 HTML 开发人员)。

从浏览器启动安装的 AIR 应用程序

若要使用浏览器调用功能(使其可以从浏览器启动),目标应用程序的应用程序描述符文件必须包含以下设置:

<allowBrowserInvocation>true</allowBrowserInvocation>

有关应用程序描述符文件的详细信息,请参阅 AIR 应用程序描述符文件

浏览器中的 SWF 文件可以通过在从 http://airdownload.adobe.com/air/browserapi/air.swf 加载的 air.swf 文件中调用 launchApplication() 方法,启动 AIR 应用程序。有关详细信息,请参阅加载 air.swf 文件

加载 air.swf 文件后,SWF 文件便可以调用 air.swf 文件的 launchApplication() 方法,如下面的代码所示:

var appID:String = "com.example.air.myTestApplication"; 
var pubID:String = "02D88EEED35F84C264A183921344EEA353A629FD.1"; 
var arguments:Array = ["launchFromBrowser"]; // Optional 
airSWF.launchApplication(appID, pubID, arguments);

launchApplication() 方法在 air.swf 文件(在用户界面 SWF 文件所在的应用程序域中加载)的顶级定义。调用此方法将导致 AIR 启动指定的应用程序(如果该应用程序已安装,且通过应用程序描述符文件中的 allowBrowserInvocation 设置允许浏览器调用)。此方法具有以下参数:

参数

说明

appID

要启动的应用程序的应用程序 ID。有关详细信息,请参阅 id

pubID

要启动的应用程序的发行商 ID。有关详细信息,请参阅 publisherID。如果所讨论的应用程序没有发行商 ID,请将 pubID 参数设置为空字符串 (“”)。

arguments

要传递给此应用程序的参数数组。此应用程序的 NativeApplication 对象调度 arguments 属性设置为此数组的 BrowserInvokeEvent 事件。参数中只能识别字母数字字符。如果需要传递其他值,请考虑使用编码方案。

仅当在用户事件(例如鼠标单击)的事件处理程序中调用 launchApplication() 方法时,此方法才执行。

如果浏览器中未安装所需的 Flash Player 版本(Windows 和 Mac OS 中为版本 9 更新 3 或更高版本,Linux 中为版本 10),则 launchApplication() 方法会引发错误。

如果在应用程序描述符文件中将 allowBrowserInvocation 元素设置为 false,则调用 launchApplication() 方法将不起任何作用。

在显示用于启动应用程序的用户界面之前,您可能需要在 air.swf 文件中调用 getApplicationVersion() 方法。有关详细信息,请参阅从网页检查是否已安装 AIR 应用程序

当通过浏览器调用功能调用此应用程序时,此应用程序的 NativeApplication 对象将调度 BrowserInvokeEvent 对象。有关详细信息,请参阅从浏览器调用 AIR 应用程序(针对 ActionScript 开发人员)或从浏览器调用 AIR 应用程序(针对 HTML 开发人员)。

如果使用浏览器调用功能,请务必考虑安全性问题。从浏览器调用 AIR 应用程序(针对 ActionScript 开发人员)和从浏览器调用 AIR 应用程序(针对 HTML 开发人员)中介绍了这些含义。

此应用程序运行后便可以通过使用 LocalConnection 类与浏览器中的 SWF 内容通信。有关详细信息,请参阅与其他 Flash Player 和 AIR 实例通信(针对 ActionScript 开发人员)或与其他 Flash Player 和 AIR 实例通信(针对 HTML 开发人员)。

注: 从 AIR 1.5.3 开始,将弃用发行商 ID。不再自动向应用程序分配发行商 ID。为了向后兼容,应用程序可以继续指定发行商 ID。