设置 AIR 应用程序属性



除了组成 AIR 应用程序的所有文件和其他资源外,每个 AIR 应用程序还需要一个应用程序描述符文件。应用程序描述符文件是定义应用程序基本属性的 XML 文件。

如果使用 Adobe® Flex™ Builder™ 3,则在创建 Adobe® AIR™ 项目时会自动生成应用程序描述符文件。如果使用 Adobe® Flex™ 3 或 AIR™ SDK 开发 AIR 应用程序,则必须手动创建此文件。示例描述符文件 descriptor-sample.xml 位于 SDK 安装的 samples 目录中。

应用程序描述符文件结构

应用程序描述符文件包含影响整个应用程序的属性,例如它的名称、版本、版权等等。任何文件名都可用于应用程序描述符文件。当使用 Flex Builder 或 ADT 打包应用程序时,应用程序描述符文件会重命名为 application.xml 并放在包内的特定目录中。

下面是一个应用程序描述符文件示例:

<?xml version="1.0" encoding="utf-8" ?> 
<application xmlns="http://ns.adobe.com/air/application/1.1"> 
    <id>com.example.HelloWorld</id> 
    <version>2.0</version> 
    <filename>Hello World</filename> 
    <name>Example Co. AIR Hello World</name> 
     <description> 
        <text xml:lang="en">This is a example.</text> 
        <text xml:lang="fr">C'est un exemple.</text> 
        <text xml:lang="es">Esto es un ejemplo.</text> 
    </description> 
    <copyright>Copyright (c) 2006 Example Co.</copyright> 
    <initialWindow> 
        <title>Hello World</title> 
        <content> 
            HelloWorld-debug.swf 
        </content> 
        <systemChrome>none</systemChrome> 
        <transparent>true</transparent> 
        <visible>true</visible> 
        <minimizable>true</minimizable> 
        <maximizable>false</maximizable> 
        <resizable>false</resizable> 
        <width>640</width> 
        <height>480</height> 
        <minSize>320 240</minSize> 
        <maxSize>1280 960</maxSize> 
    </initialWindow>  
    <installFolder>Example Co/Hello World</installFolder> 
    <programMenuFolder>Example Co</programMenuFolder> 
    <icon> 
        <image16x16>icons/smallIcon.png</image16x16> 
        <image32x32>icons/mediumIcon.png</image32x32> 
        <image48x48>icons/bigIcon.png</image48x48> 
        <image128x128>icons/biggestIcon.png</image128x128>  
    </icon> 
    <customUpdateUI>true</customUpdateUI> 
    <allowBrowserInvocation>false</allowBrowserInvocation> 
    <fileTypes> 
        <fileType> 
            <name>adobe.VideoFile</name> 
            <extension>avf</extension> 
            <description>Adobe Video File</description> 
            <contentType>application/vnd.adobe.video-file</contentType> 
            <icon> 
                <image16x16>icons/avfIcon_16.png</image16x16> 
                <image32x32>icons/avfIcon_32.png</image32x32> 
                <image48x48>icons/avfIcon_48.png</image48x48> 
                <image128x128>icons/avfIcon_128.png</image128x128> 
            </icon> 
        </fileType> 
    </fileTypes> 
</application>

在应用程序描述符文件中定义属性

应用程序描述符文件的根包含具有若干属性 (attribute) 的 application 属性 (property):

<application version="1.0" xmlns="http://ns.adobe.com/air/application/1.1">

xmlns AIR 命名空间,必须将其定义为默认 XML 命名空间。该命名空间因每个 AIR 主版本而异(但不会因次要修补程序而异)。命名空间的最后一部分(例如“1.0”)指示应用程序所需的运行时版本。

minimumPatchLevel 可选。使用 minimumPatchLevel 属性可指定应用程序所需的最低 Adobe AIR 修补级别。通常,AIR 应用程序仅通过定义应用程序描述符文件中的命名空间来指定其需要的 AIR 版本。该命名空间因每个 AIR 主版本(例如 1.0 或 1.1)而异。该命名空间不会因修补程序版本而异。修补程序版本仅包含一组有限的修正内容,而不包含任何 API 更改内容。通常,应用程序不指定其需要哪个修补程序版本。但是,修补程序版本中的修正内容能够修正应用程序中的某一问题。在此情况下,应用程序可以为 minimumPatchLevel 属性指定一个值,以确保在安装应用程序之前应用相应修补程序。如有必要,AIR 应用程序安装程序会提示用户下载并安装所需版本或修补程序。以下示例显示为 minimumPatchLevel 属性指定了值的应用程序元素:

<application version="1.0" 
    xmlns="http://ns.adobe.com/air/application/1.1" 
    minimumPatchLevel="5331">

定义基本应用程序信息

以下元素定义应用程序的 ID、版本、名称、文件名、说明和版权信息:

<id>com.example.samples.TestApp</id> 
<version>2.0</version> 
<filename>TestApp</filename> 
<name> 
    <text xml:lang="en">Hello AIR</text> 
    <text xml:lang="fr">Bonjour AIR</text> 
    <text xml:lang="es">Hola AIR</text> 
</name> 
<description>An MP3 player.</description> 
<copyright>Copyright (c) 2008 YourCompany, Inc.</copyright>

id 应用程序的唯一标识符字符串,称为应用程序 ID。该属性的值只能使用以下字符:

  • 0 - 9

  • a - z

  • A - Z

  • .(点)

  • -(连字符)

该值必须包含 1 到 212 个字符。此元素是必需的。

id 字符串通常使用以点分隔的层次结构,以与反向 DNS 域地址、Java™ 包或类名或者 Mac OS® X 统一类型标识符保持一致。不强制使用类似于 DNS 的形式,而且 AIR 不会在名称和实际 DNS 域之间创建任何关联。

version 指定应用程序的版本信息。(它与运行时版本无关)。version 字符串是应用程序定义的指示符。AIR 不会以任何方式解释版本字符串。因此,不会假设版本“3.0”比版本“2.0”更新。示例包括:“1.0”、“.4”、“0.5”、“4.9”和“1.3.4a”。此元素是必需的。

filename 该字符串在安装应用程序时用作应用程序的文件名(不带扩展名)。该应用程序文件将在运行时启动相应 AIR 应用程序。如果未提供 name 值,则 filename 也将用作安装文件夹的名称。此元素是必需的。

filename 属性可包含任何 Unicode (UTF-8) 字符,但以下字符(在各种文件系统中都禁止将这些字符用作文件名)除外:

字符

十六进制代码

因系统而异

0x00 - x1F

*

x2A

"

x22

:

x3A

>

x3C

<

x3E

?

x3F

\

x5C

|

x7C

filename 值不能以句点结尾。

name(可选,但建议使用) 由 AIR 应用程序安装程序显示的标题。

如果指定单个文本节点(而非多个 text 元素),则无论系统语言为哪种语言,AIR 应用程序安装程序都将使用此名称:

<name>Test Application</name> 

AIR 1.0 应用程序描述符架构只允许为该名称定义一个简单文本节点(而非多个 text 元素)。

在 AIR 1.1 中,您可以在 name 元素中指定多种语言。例如,以下示例用三种语言(英语、法语和西班牙语)指定名称:

<name> 
    <text xml:lang="en">Hello AIR</text> 
    <text xml:lang="fr">Bonjour AIR</text> 
    <text xml:lang="es">Hola AIR</text> 
</name> 

每个文本元素的 xml:lang 属性用于指定语言代码,有关具体定义,请参阅 RFC4646 (http://www.ietf.org/rfc/rfc4646.txt)。

AIR 应用程序安装程序会使用与用户操作系统的用户界面语言最匹配的名称。例如,假如在某一安装中,应用程序描述符文件的 name 元素包含适用于 en(英语)区域设置的值。如果操作系统将 en(英语)标识为用户界面语言,则 AIR 应用程序安装程序将使用此 en 名称。如果系统用户界面语言为 en-US(美式英语),则该应用程序也使用此 en 名称。但是,如果用户界面语言为 en-US,而应用程序描述符文件同时定义了 en-US 名称和 en-GB 名称,则 AIR 应用程序安装程序将使用相应的 en-US 值。如果应用程序定义的任何名称与系统用户界面语言均不匹配,则 AIR 应用程序安装程序将使用在应用程序描述符文件中定义的第一个 name 值。

如果未指定 name 元素,则 AIR 应用程序安装程序会将 filename 显示为应用程序名称。

name 元素仅定义在 AIR 应用程序安装程序中使用的应用程序标题。AIR 1.1 应用程序安装程序支持以下多种语言:繁体中文、简体中文、英语、法语、德语、意大利语、日语、韩语、巴西葡萄牙语、俄语和西班牙语。AIR 应用程序安装程序将根据系统用户界面语言来(为文本而不是应用程序标题和说明)选择其显示语言。此语言选择与应用程序描述符文件中的设置无关。

name 元素定义可供运行的已安装应用程序使用的区域设置。有关开发多语言应用程序的详细信息,请参阅本地化 AIR 应用程序

description(可选) 将在 AIR 应用程序安装程序中显示的应用程序说明。

如果指定单个文本节点(而非多个文本元素),则无论系统语言为哪种语言,AIR 应用程序安装程序都将使用此说明:

<description>This is a sample AIR application.</description> 

AIR 1.0 应用程序描述符架构只允许为该名称定义一个简单文本节点(而非多个 text 元素)。

在 AIR 1.1 中,您可以在 description 元素中指定多种语言。例如,以下示例用三种语言(英语、法语和西班牙语)指定说明:

<description> 
    <text xml:lang="en">This is a example.</text> 
    <text xml:lang="fr">C'est un exemple.</text> 
    <text xml:lang="es">Esto es un ejemplo.</text> 
</description> 

每个文本元素的 xml:lang 属性用于指定语言代码,有关具体定义,请参阅 RFC4646 (http://www.ietf.org/rfc/rfc4646.txt)。

AIR 应用程序安装程序会使用与用户操作系统的用户界面语言最匹配的说明。例如,假如在某一安装中,应用程序描述符文件的 description 元素包含适用于 en(英语)区域设置的值。如果用户系统将 en(英语)标识为用户界面语言,则 AIR 应用程序安装程序将使用此 en 名称。如果系统用户界面语言为 en-US(美式英语),则该应用程序也使用此 en 名称。但是,如果系统用户界面语言为 en-US,而应用程序描述符文件同时定义了 en-US 名称和 en-GB 名称,则 AIR 应用程序安装程序将使用相应的 en-US 值。如果应用程序定义的任何名称与系统用户界面语言均不匹配,则 AIR 应用程序安装程序将使用在应用程序描述符文件中定义的第一个 description 值。

有关开发多语言应用程序的详细信息,请参阅本地化 AIR 应用程序

copyright(可选) AIR 应用程序的版权信息。在 Mac OS 中,版权文本会显示在已安装应用程序的“关于”对话框中。在 Mac OS 中,在应用程序的 Info.plist 文件中的 NSHumanReadableCopyright 字段内也使用版权信息。

定义安装文件夹和程序菜单文件夹

安装文件夹和程序菜单文件夹通过以下属性设置进行定义:

<installFolder>Acme</installFolder> 
<programMenuFolder>Acme/Applications</programMenuFolder>

installFolder(可选) 标识默认安装目录的子目录。

在 Windows 中,默认安装子目录为 Program Files 目录。在 Mac OS 中,默认安装子目录为 /Applications 目录。例如,如果 installFolder 属性设置为“Acme”而应用程序命名为“ExampleApp”,则在 Windows 中,应用程序将安装在 C:\Program Files\Acme\ExampleApp 中,而在 MacOS 中,应用程序将安装在 /Applications/Acme/Example.app 中。

如果要指定嵌套子目录,请使用正斜杠 (/) 字符作为目录分隔符,如下所示:

<installFolder>Acme/Power Tools</installFolder>

installFolder 属性可包含任何 Unicode (UTF-8) 字符,但那些禁止在各种文件系统中用作文件夹名称的字符除外(有关例外字符的列表,请参阅上文中的 filename 属性)。

installFolder 属性为可选属性。如果未指定 installFolder 属性,则应用程序将根据 name 属性安装在默认安装目录的子目录中。

programMenuFolder(可选) 标识应用程序快捷方式在 Windows 操作系统的“所有程序”菜单中的放置位置。(目前在其他操作系统中忽略此设置。)对该属性值中允许使用的字符的限制与对 installFolder 属性的限制相同。请 将正斜杠 (/) 字符用作此值的最后一个字符。

定义初始应用程序窗口的属性

当加载 AIR 应用程序时,运行时将使用 initialWindow 元素中的值为应用程序创建初始窗口。然后,运行时会将 content 元素中指定的 SWF 或 HTML 文件加载到该窗口中。

以下为 initialWindow 元素的示例:

<initialWindow> 
    <content>AIRTunes.swf</content> 
    <title>AIR Tunes</title> 
    <systemChrome>none</systemChrome> 
    <transparent>true</transparent> 
    <visible>true</visible> 
    <minimizable>true</minimizable> 
    <maximizable>true</maximizable> 
    <resizable>true</resizable> 
    <width>400</width> 
    <height>600</height> 
    <x>150</x> 
    <y>150</y> 
    <minSize>300 300</minSize> 
    <maxSize>800 800</maxSize> 
</initialWindow>

initialWindow 元素的各子元素设置根内容文件将加载到其中的窗口的属性。

content content 元素指定的值是应用程序主内容文件的 URL。该文件可以是 SWF 文件,也可以是 HTML 文件。该 URL 是相对于根应用程序安装文件夹指定的。(如果使用 ADL 运行 AIR 应用程序,则该 URL 相对于包含应用程序描述符文件的文件夹。可以使用 ADL 的 root-dir 参数指定其他根目录。)

注: 因为将 content 元素的值视为 URL,所以必须根据RFC 1738FC 1738 中定义的规则对内容文件名称中的字符进行 URL 编码。例如,空格字符必须编码为 %20

title(可选) 窗口标题。

systemChrome(可选) 如果将此属性设置为 standard,则将显示操作系统提供的标准系统镶边。如果将其设置为 none,则不显示任何系统镶边。当使用 Flex mx:WindowedApplication 组件时,如果未设置标准系统镶边,则该组件将应用其自定义镶边。系统镶边设置在运行时无法更改。

transparent(可选) 如果希望应用程序窗口支持 Alpha 混合,则设置为“true”。透明窗口绘制起来可能比较慢且需要更多内存。透明设置在运行时无法更改。

重要说明: systemChromenone 时,只能将 transparent 设置为 true

visible(可选) 默认值为 false。仅当希望主窗口在创建后马上可见时,才设置为 true,这也将在放置窗口组件时显示对窗口所做的更改。除非在 MXML 定义中将 visible 属性设置为 false,否则 Flex mx:WindowedApplication 组件会自动显示并激活窗口,然后立即调度 applicationComplete 事件。

您可能想要使主窗口最初保持隐藏,以便不显示对窗口位置、窗口大小和其内容的布局所做的更改。然后,可以通过对此窗口调用 activate() 方法或将 visible 属性设置为 true 来显示此窗口。有关详细信息,请参阅使用本机窗口

x、y、width、height(可选) 应用程序主窗口的初始边界。如果未设置这些值,则窗口大小将由根 SWF 文件中的设置确定,对于 HTML,则将由操作系统确定。

minSize、maxSize(可选) 窗口的最小和最大大小。如果未设置这些值,则将由操作系统确定这些值。

minimizable、maximizable、resizable(可选) 指定窗口是否可以最小化、最大化,以及是否可以调整大小。默认情况下,这些设置设为 true

注: 在操作系统(例如 Mac OS X)中,最大化窗口是一种调整大小操作,若要阻止窗口缩放或调整大小,maximizable 和 resizable 必须同时设置为 false

指定图标文件

icon 属性指定一个或多个要用于应用程序的图标文件。包含图标是可选的。如果未指定 icon 属性,则操作系统将显示默认图标。

指定路径相对于应用程序的根目录。图标文件必须为 PNG 格式。可以指定以下所有图标尺寸:

<icon> 
    <image16x16>icons/smallIcon.png</image16x16> 
    <image32x32>icons/mediumIcon.png</image32x32> 
    <image48x48>icons/bigIcon.png</image48x48> 
    <image128x128>icons/biggestIcon.png</image128x128>  
</icon>

如果存在用于指定一定尺寸的元素,则文件中的图像必须与指定尺寸完全相同。如果所有尺寸都未提供,则操作系统会将图像缩放为适合图标给定用途的最接近的大小。

注: 指定图标不会自动添加到 AIR 包中。打包应用程序时,图标文件必须包含在其正确的相对位置中。

为获得最佳效果,为每种可用尺寸都提供一个图像。此外,请确保图标在 16 位和 32 位颜色模式下看上去都像一回事。

提供针对应用程序更新的自定义用户界面

AIR 使用默认安装对话框安装和更新应用程序。但是,您可以为更新应用程序提供您自己的用户界面。若要指示让应用程序自身处理更新过程,请将 customUpdateUI 元素设置为 true

<customUpdateUI>true</customUpdateUI>

如果应用程序的已安装版本将 customUpdateUI 元素设置为 true,则当用户双击新版本的 AIR 文件或使用无缝安装功能安装应用程序的更新时,运行时将打开应用程序的已安装版本,而非默认的 AIR 应用程序安装程序。然后,您的应用程序逻辑可以确定如何继续执行更新操作。(AIR 文件中的应用程序 ID 和发行商 ID 必须与已安装应用程序中的相应 ID 匹配才能继续进行升级。)

注: 仅当应用程序已经安装并且用户双击包含更新的 AIR 安装文件或使用无缝安装功能安装应用程序的更新时,customUpdateUI 机制才能发挥作用。无论 customUpdateUI 是否为 true,您都可以通过您自己的应用程序逻辑下载并启动更新,并在必要时显示自定义 UI。

有关详细信息,请参阅更新 AIR 应用程序

允许应用程序的浏览器调用

如果指定以下设置,则可以通过浏览器调用功能(由用户单击 Web 浏览器中某页中的链接)来启动已安装 AIR 应用程序:

<allowBrowserInvocation>true</allowBrowserInvocation>

默认值为 false

如果将该值设置为 true,请务必考虑安全隐患,如浏览器调用所述。

有关详细信息,请参阅从网页安装和运行 AIR 应用程序

声明文件类型关联

利用 fileTypes 元素可声明 AIR 应用程序可以与其关联的文件类型。当安装某个 AIR 应用程序时,任何已声明文件类型都会注册到操作系统,并且如果这些文件类型尚未与其他应用程序关联,则它们将与该 AIR 应用程序关联。若要覆盖某个文件类型和其他应用程序之间的现有关联,请在运行时使用 NativeApplication.setAsDefaultApplication() 方法(最好使用用户权限)。

注: 运行时方法只能管理应用程序描述符中声明的文件类型的关联。
<fileTypes> 
    <fileType> 
        <name>adobe.VideoFile</name> 
        <extension>avf</extension> 
        <description>Adobe Video File</description> 
        <contentType>application/vnd.adobe.video-file</contentType> 
        <icon> 
            <image16x16>icons/AIRApp_16.png</image16x16>       
            <image32x32>icons/AIRApp_32.png</image32x32>       
            <image48x48>icons/AIRApp_48.png</image48x48>      
            <image128x128>icons/AIRApp_128.png</image128x128> 
        </icon> 
    </fileType> 
</fileTypes>

fileTypes 元素为可选元素。如果存在,则它可以包含任何数量的 fileType 元素。

对于包含的每个 fileType 声明,nameextension 元素都是必需的。同一名称可用于多个扩展名。扩展名唯一标识文件类型。(请注意,指定扩展名时前面不加句点。)description 元素是可选元素,并且用户可通过操作系统用户界面看到该元素的内容。contentType 属性也是可选的,但它有助于操作系统在某些情况下找到打开文件的最佳应用程序。该值应为文件内容的 MIME 类型。

可以为文件扩展名指定图标,所使用格式与应用程序 icon 元素相同。图标文件也必须包含在 AIR 安装文件中(它们不会自动打包)。

如果一个文件类型与某个 AIR 应用程序关联,则只要用户打开该类型的某个文件就会调用该应用程序。如果该应用程序已经运行,则 AIR 将针对该运行实例调度 InvokeEvent 对象。否则,AIR 将首先启动该应用程序。在这两种情况下,均可从 NativeApplication 对象调度的 InvokeEvent 对象中检索相应文件路径。可以使用此路径打开相应文件。