使用 AIR 中的 File 对象

Adobe AIR 1.0 和更高版本

File 对象是指向文件系统中文件或目录的指针。

File 类扩展了 FileReference 类。Adobe® Flash® Player 和 AIR 中提供的 FileReference 类表示指向文件的指针。File 类添加了一些属性和方法,出于安全方面的考虑,在 Flash Player 中(在浏览器中运行的 SWF 文件中)未公开这些属性和方法。

关于 File 类

您可以使用 File 类执行以下操作:

  • 获取特殊目录的路径,包括用户目录、用户的文档目录、应用程序的启动目录以及应用程序目录

  • 复制文件和目录

  • 移动文件和目录

  • 删除文件和目录(或将它们移到垃圾桶)

  • 列出目录中包含的文件和目录

  • 创建临时文件和文件夹

当 File 对象指向文件路径后,您可以通过 FileStream 类使用该 File 对象读取和写入文件数据。

File 对象可以指向尚不存在的文件或目录的路径。创建文件或目录时可以使用这种 File 对象。

File 对象的路径

每个 File 对象具有两个属性,各属性可分别定义该对象的路径:

属性

说明

nativePath

指定文件在特定平台上的路径。例如,在 Windows 中,路径可能是“c:\Sample directory\test.txt”,而在 Mac OS 中,路径可能是“/Sample directory/test.txt”。nativePath 属性在 Windows 中使用反斜杠 (\) 字符作为目录分隔符,在 Mac OS 和 Linux 中使用正斜杠 (/) 字符。

url

此属性可以使用 file URL 方案指向文件。例如,在 Windows 中,路径可能是“file:///c:/Sample%20directory/test.txt”,而在 Mac OS 中,路径可能是“file:///Sample%20directory/test.txt”。除 file 之外,运行时还包括其他特殊 URL 方案,在支持的 AIR URL 方案中将予以介绍

File 类包括用于指向 Mac OS、Windows 和 Linux 中的标准目录的静态属性。这些属性包括:

  • File.applicationStorageDirectory — 每个已安装的 AIR 应用程序独有的存储目录。此目录适用于存储动态应用程序资源和用户首选项。考虑在其他位置存储大量数据。

  • File.applicationDirectory — 安装应用程序的目录(还存储任何安装的资源)。在有些操作系统上,应用程序存储在一个软件包文件中而不是物理目录中。在这种情况下,可能无法使用本机路径访问内容。应用程序目录是只读的。

  • File.desktopDirectory— 用户的桌面目录。如果平台不定义桌面目录,则使用文件系统上的另一个位置。

  • File.documentsDirectory— 用户的文档目录。如果平台不定义文档目录,则使用文件系统上的另一个位置。

  • File.userDirectory — 用户目录。如果平台不定义用户目录,则使用文件系统上的另一个位置。

注: 当平台不定义桌面、文档或用户目录的标准位置时,File.documentsDirectoryFile.desktopDirectoryFile.userDirectory 可以引用同一个目录。

这些属性在不同的操作系统上有不同的值。例如,对于用户的桌面目录,Mac 和 Windows 有各自不同的本机路径。然而,File.desktopDirectory 属性在每个平台上指向适当的目录路径。要编写可以跨平台正常工作的应用程序,在需要引用应用程序使用的其他目录和文件时,请以这些属性为基础,然后使用 resolvePath() 方法来完善路径。例如,此代码会指向应用程序存储目录中的 preferences.xml 文件:

var prefsFile:File = air.File.applicationStorageDirectory; 
prefsFile = prefsFile.resolvePath("preferences.xml");

尽管可以使用 File 类来指向特定文件路径,但这种做法会指向无法跨平台工作的应用程序。例如,路径 C:\Documents and Settings\joe\ 仅适用于 Windows。出于以上原因,最好使用 File 类的静态属性,如 File.documentsDirectory

公用目录位置

平台

目录类型

典型的文件系统位置

Linux

应用程序

/opt/filename/share

应用程序存储

/home/userName/.appdata/applicationID/Local Store

桌面

/home/userName/Desktop

文档

/home/userName/Documents

临时

/tmp/FlashTmp.randomString

用户

/home/userName

Mac

应用程序

/Applications/filename.app/Contents/Resources

应用程序存储

/Users/userName/Library/Preferences/applicationID/Local Store

桌面

/Users/userName/Desktop

文档

/Users/userName/Documents

临时

/private/var/folders/JY/randomString/TemporaryItems/FlashTmp

用户

/Users/userName

Windows

应用程序

C:\Program Files\filename

应用程序存储

C:\Documents and settings\userName\ApplicationData\applicationID\Local Store

桌面

C:\Documents and settings\userName\Desktop

文档

C:\Documents and settings\userName\My Documents

临时

C:\Documents and settings\userName\Local Settings\Temp\randomString.tmp

用户

C:\Documents and settings\userName

根据具体的操作系统和计算机配置,这些目录的实际本机路径会有所不同。此表中显示的路径是典型示例。您应该始终使用适当的静态 File 类属性引用这些目录,以便您的应用程序在任何平台上都能正常工作。在一个实际的 AIR 应用程序中,表中显示的 applicationIDfilename 的值取自应用程序描述符。如果您在应用程序描述符中指定发布者 ID,则发布者 ID 在这些路径中会追加到应用程序 ID。userName 的值是安装用户的帐户名称。

将 File 对象指向目录

可以采用多种不同方式设置 File 对象以使其指向某目录。

指向用户的主目录

您可以将 File 对象指向用户的主目录。以下代码将设置 File 对象以使其指向主目录中的 AIR Test 子目录:

var file = air.File.userDirectory.resolvePath("AIR Test");

指向用户的文档目录

您可以将 File 对象指向用户的文档目录。以下代码设置 File 对象以指向文档目录中的 AIR Test 子目录:

var file = air.File.documentsDirectory.resolvePath("AIR Test");

指向桌面目录

您可以使 File 对象指向桌面。以下代码设置 File 对象以使其指向桌面的 AIR Test 子目录:

var file = air.File.desktopDirectory.resolvePath("AIR Test");

指向应用程序存储目录

您可以使 File 对象指向应用程序存储目录。对于每个 AIR 应用程序,有一个唯一的关联路径用于定义应用程序存储目录。此目录对每个应用程序和用户是唯一的。您可以使用此目录存储特定于用户、特定于应用程序的数据(如用户数据或首选参数文件)。例如,以下代码将使 File 对象指向应用程序存储目录中包含的首选参数文件 prefs.xml:

var file = air.File.applicationStorageDirectory; 
file = file.resolvePath("prefs.xml");

应用程序存储目录位置通常基于用户名称和应用程序 ID。此处提供了下列文件系统位置以帮助您调试应用程序。您应该始终使用 File.applicationStorage 属性或 app-storage: URI 方案解析此目录中的文件:

  • 在 Mac OS 中,位于:

    /Users/user name/Library/Preferences/applicationID/Local Store/

    例如:

    /Users/babbage/Library/Preferences/com.example.TestApp/Local Store
  • 在 Windows 中,位于 Documents and Settings 目录下的以下位置:

    C:\Documents and Settings\user name\Application Data\applicationID\Local Store\

    例如:

    C:\Documents and Settings\babbage\Application Data\com.example.TestApp\Local Store
  • 在 Linux 中位于:

    /home/user name/.appdata/applicationID/Local Store/

    例如:

    /home/babbage/.appdata/com.example.TestApp/Local Store
注: 如果应用程序具有发行商 ID,则还可将该 ID 用作应用程序存储目录路径的一部分。

通过 File.applicationStorageDirectory 创建的 File 对象的 URL(和 url 属性)将使用 app-storage URL 方案(请参阅支持的 AIR URL 方案),如下所示:

var dir = air.File.applicationStorageDirectory; 
dir = dir.resolvePath("prefs.xml"); 
air.trace(dir.url); // app-storage:/preferences

指向应用程序目录

您可以使 File 对象指向应用程序的安装目录,即应用程序目录。您可以使用 File.applicationDirectory 属性引用此目录。您可以使用此目录检查应用程序描述符文件或与应用程序一起安装的其他资源。例如,以下代码将使 File 对象指向应用程序目录中名为 images 的目录:

var dir = air.File.applicationDirectory; 
dir = dir.resolvePath("images");

通过 File.applicationDirectory 创建的 File 对象的 URL(和 url 属性)将使用 app URL 方案(请参阅支持的 AIR URL 方案),如下所示:

var dir = air.File.applicationDirectory; 
dir = dir.resolvePath("images"); 
air.trace(dir.url); // app:/images

指向文件系统根目录

File.getRootDirectories() 方法列出所有根卷,如 Windows 计算机中的 C: 和已装好的卷。在 Mac OS 和 Linux 中,此方法始终返回计算机的唯一根目录(“/”目录)。StorageVolumeInfo.getStorageVolumes() 方法提供有已关装的存储卷的更多详细信息(请参阅使用存储卷)。

指向明确的目录

通过设置 File 对象的 nativePath 属性,可以使 File 对象指向某个明确的目录,如以下示例中所示(在 Windows 中):

var file = new air.File(); 
file.nativePath = "C:\\AIR Test";

重要说明:通过这种方式指向明确的路径会导致代码无法跨平台使用。例如,上面的示例仅适用于 Windows。您可以使用 File 类的静态属性(如 File.applicationStorageDirectory)来定位跨平台工作的目录。然后使用 resolvePath() 方法(请参阅下一节)导航到相对路径。

导航到相对路径

您可以使用 resolvePath() 方法获取相对于其他给定路径的路径。例如,以下代码将设置 File 对象以使其指向用户主目录中的“AIR Test”子目录:

var file = air.File.userDirectory; 
file = file.resolvePath("AIR Test");

您还可以使用 File 对象的 url 属性以使该对象指向基于 URL 字符串的目录,如下所示:

var urlStr = "file:///C:/AIR Test/"; 
var file = new air.File() 
file.url = urlStr;

有关详细信息,请参阅修改文件路径

让用户浏览以选择目录

File 类包括 browseForDirectory() 方法,它表示系统对话框,在该对话框中用户可以选择要分配给对象的目录。browseForDirectory() 方法为异步方法。如果用户选择一个目录并单击“打开”按钮,File 对象将调度一个 select 事件;如果用户单击“取消”按钮,它将调度一个 cancel 事件。

例如,以下代码能使用户选择一个目录,并在选择后输出目录路径:

var file = new air.File(); 
file.addEventListener(air.Event.SELECT, dirSelected); 
file.browseForDirectory("Select a directory"); 
function dirSelected(event) { 
    alert(file.nativePath); 
}

指向从中调用应用程序的目录

通过检查调用应用程序时所调度的 InvokeEvent 对象的 currentDirectory 属性,可以获取从中调用应用程序的目录位置。有关详细信息,请参阅捕获命令行参数

将 File 对象指向文件

可采用多种不同方式设置 File 对象所指向的文件。

指向明确的文件路径

重要说明:指向明确的路径会导致代码无法跨平台工作。例如,路径 C:/foo.txt 仅适用于 Windows。您可以使用 File 类的静态属性(如 File.applicationStorageDirectory)来定位跨平台工作的目录。然后使用 resolvePath() 方法(请参阅修改文件路径)导航到相对路径。

您可以使用 File 对象的 url 属性以使该对象指向基于 URL 字符串的文件或目录,如下所示:

var urlStr = "file:///C:/AIR Test/test.txt"; 
var file = new air.File() 
file.url = urlStr;

您还可以将 URL 传递到 File() 构造函数,如下所示:

var urlStr = "file:///C:/AIR Test/test.txt"; 
var file = new air.File(urlStr);

url 属性始终返回 URL 的 URI 编码版本(例如,空格替换为 %20):

file.url = "file:///c:/AIR Test"; 
alert(file.url); // file:///c:/AIR%20Test

您还可以使用 File 对象的 nativePath 属性设置明确的路径。例如,在 Windows 计算机中运行以下代码,可以设置 File 对象以使其指向 C: 驱动器的 AIR Test 子目录中的 test.txt 文件:

var file = new air.File(); 
file.nativePath = "C:/AIR Test/test.txt";

您还可以将此路径传递到 File() 构造函数,如下所示:

var file = new air.File("C:/AIR Test/test.txt");

请使用正斜杠 (/) 字符作为 nativePath 属性的路径分隔符。在 Windows 上,还可以使用反斜杠 (\) 字符,但这会导致应用程序无法跨平台工作。

有关详细信息,请参阅修改文件路径

枚举目录中的文件

您可以使用 File 对象的 getDirectoryListing() 方法获取指向位于某目录根级的文件和子目录的 File 对象数组。有关详细信息,请参阅枚举目录

让用户浏览以选择文件

File 类包括以下方法,它们表示系统对话框,在该对话框中用户可以选择要分配给对象的文件:

  • browseForOpen()

  • browseForSave()

  • browseForOpenMultiple()

这些方法均为异步方法。当用户选择一个文件时(或者,对于 browseForSave() 选择一个目标路径时),browseForOpen()browseForSave() 方法将调度 select 事件。对 browseForOpen()browseForSave() 方法,在进行选择后目标 File 对象将指向所选的文件。当用户选择多个文件时,browseForOpenMultiple() 方法调度一个 selectMultiple 事件。selectMultiple 事件的类型是 FileListEvent,它具有一个 files 属性,该属性是一个 File 对象数组(指向所选的文件)。

例如,以下代码向用户显示“Open”对话框,在该对话框中用户可以选择文件:

var fileToOpen = air.File.documentsDirectory; 
selectTextFile(fileToOpen); 
 
function selectTextFile(root) 
{ 
    var txtFilter = new air.FileFilter("Text", "*.as;*.css;*.html;*.txt;*.xml"); 
    root.browseForOpen("Open", new window.runtime.Array(txtFilter)); 
    root.addEventListener(air.Event.SELECT, fileSelected); 
} 
 
function fileSelected(event) 
{ 
    trace(fileToOpen.nativePath); 
}

当您调用浏览方法时,如果应用程序已打开了其他浏览器对话框,则运行时会引发一个错误异常。

修改文件路径

通过调用 resolvePath() 方法或通过修改对象的 nativePathurl 属性,您还可以修改现有 File 对象的路径,如以下示例中所示(在 Windows 中):

file1 = air.File.documentsDirectory; 
file1 = file1.resolvePath("AIR Test"); 
alert(file1.nativePath); // C:\Documents and Settings\userName\My Documents\AIR Test 
var file2 = air.File.documentsDirectory; 
file2 = file2.resolvePath(".."); 
alert(file2.nativePath); // C:\Documents and Settings\userName 
var file3 = air.File.documentsDirectory; 
file3.nativePath += "/subdirectory"; 
alert(file3.nativePath); // C:\Documents and Settings\userName\My Documents\subdirectory 
var file4 = new air.File(); 
file4.url = "file:///c:/AIR Test/test.txt"; 
alert(file4.nativePath); // C:\AIR Test\test.txt

使用 nativePath 属性时,请使用正斜杠 (/) 字符作为目录分隔符。在 Windows 上,还可以使用反斜杠 (\) 字符,但不应这样做,因为这会导致代码无法跨平台工作。

支持的 AIR URL 方案

在 AIR 中定义 File 对象的 url 属性时,可以使用以下任一 URL 方案:

URL 方案

说明

file

用于指定相对于文件系统根目录的路径。例如:

file:///c:/AIR Test/test.txt

URL 标准规定 file URL 采用 file://<host>/<path> 形式。作为一个特例,<host> 可以是空字符串,它被解释为“解释该 URL 的计算机”。因此,file URL 通常具有三个斜杠 (///)。

app

用于指定相对于所安装应用程序的根目录(该目录包含所安装应用程序的 application.xml 文件)的路径。例如,以下路径指向所安装应用程序的目录的 images 子目录:

app:/images

app-storage

用于指定相对于应用程序存储目录的路径。对于每个安装的应用程序,AIR 定义了一个唯一的应用程序存储目录,此目录对于存储特定于该应用程序的数据很有用。例如,以下路径指向应用程序存储目录的 settings 子目录中的 prefs.xml 文件:

app-storage:/settings/prefs.xml

查找两个文件之间的相对路径

您可以使用 getRelativePath() 方法查找两个文件之间的相对路径:

var file1 = air.File.documentsDirectory 
file1 = file1.resolvePath("AIR Test"); 
var file2 = air.File.documentsDirectory 
file2 = file2.resolvePath("AIR Test/bob/test.txt"); 
 
alert(file1.getRelativePath(file2)); // bob/test.txt

getRelativePath() 方法的第二个参数 useDotDot 允许在结果中返回 .. 语法,以指示父目录:

var file1 = air.File.documentsDirectory; 
file1 = file1.resolvePath("AIR Test"); 
var file2 = air.File.documentsDirectory; 
file2 = file2.resolvePath("AIR Test/bob/test.txt"); 
var file3 = air.File.documentsDirectory; 
file3 = file3.resolvePath("AIR Test/susan/test.txt"); 
 
alert(file2.getRelativePath(file1, true)); // ../.. 
alert(file3.getRelativePath(file2, true)); // ../../bob/test.txt

获取文件名的规范版本

文件名和路径名在 Windows 和 Mac OS 中不区分大小写。在以下示例中,两个 File 对象指向同一个文件:

File.documentsDirectory.resolvePath("test.txt"); 
File.documentsDirectory.resolvePath("TeSt.TxT");

不过,文档和目录名确实包括大小写。例如,以下代码假定在文档目录中有一个名为 AIR Test 的文件夹,如以下示例中所示:

var file = air.File.documentsDirectory; 
file = file.resolvePath("AIR test"); 
trace(file.nativePath); // ... AIR test 
file.canonicalize(); 
alert(file.nativePath); // ... AIR Test

canonicalize() 方法可以转换 nativePath 对象,以使用文件名或目录名的正确大写形式。在区分大小写的文件系统(如 Linux)上,当多个文件的名称只有大小写不同时,canonicalize() 方法将调整路径以匹配最先找到的文件(以文件系统确定的顺序)。

在 Windows 中,您还可以使用 canonicalize() 方法将短文件名(“8.3”名称)转换为长文件名,如以下示例中所示:

var path = new air.File(); 
path.nativePath = "C:\\AIR~1"; 
path.canonicalize(); 
alert(path.nativePath); // C:\AIR Test

使用包和符号链接

多种操作系统支持包文件和符号链接文件:

— 在 Mac OS 中,可以指定目录作为包,并且目录可以作为单个文件而非目录出现在 Mac OS Finder 中。

符号链接 — Mac OS、Linux 和 Windows Vista 支持符号链接。通过符号链接,文件可以指向磁盘上的另一个文件或目录。尽管符号链接与别名类似,不过它们并不相同。别名始终报告为文件(而不是目录),读取或写入别名或快捷方式从不影响它指向的原始文件或目录。另一方面,符号链接的行为则完全与它指向的文件或目录类似。可以将符号链接报告为文件或目录,并且读写符号链接影响的是符号链接所指向的文件或目录,而不影响其本身。此外,在 Windows 中,引用交接点(用于 NTFS 文件系统中)的 File 对象的 isSymbolicLink 属性设置为 true

File 类包括 isPackageisSymbolicLink 属性,用于检查 File 对象是否引用包或符号链接。

以下代码将遍历用户的桌面目录,列出不是 包的子目录:

var desktopNodes = air.File.desktopDirectory.getDirectoryListing(); 
for (i = 0; i < desktopNodes.length; i++)  
{ 
    if (desktopNodes[i].isDirectory && !!desktopNodes[i].isPackage) 
    { 
        air.trace(desktopNodes[i].name); 
    } 
}

以下代码将遍历户的桌面目录,列出不是 符号链接的文件和目录:

var desktopNodes = air.File.desktopDirectory.getDirectoryListing(); 
for (i = 0; i < desktopNodes.length; i++)  
{ 
    if (!desktopNodes[i].isSymbolicLink) 
    { 
        air.trace(desktopNodes[i].name); 
    } 
}

canonicalize() 方法可更改符号链接的路径,以指向该链接所引用的文件或目录。以下代码将遍历用户的桌面目录,报告由是符号链接的文件引用的路径:

var desktopNodes = air.File.desktopDirectory.getDirectoryListing(); 
for (i = 0; i < desktopNodes.length; i++)  
{ 
    if (desktopNodes[i].isSymbolicLink) 
    { 
        var linkNode = desktopNodes[i]; 
        linkNode.canonicalize(); 
        air.trace(desktopNodes[i].name); 
    } 
}

确定卷上的可用空间

File 对象的 spaceAvailable 属性是 File 位置的可用空间(以字节为单位)。例如,以下代码检查应用程序存储目录中的可用空间:

air.trace(air.File.applicationStorageDirectory.spaceAvailable); 

如果 File 对象引用一个目录,则 spaceAvailable 属性将指示可供文件使用的目录空间。如果 File 对象引用一个文件,则 spaceAvailable 属性将指示可供该文件使用的空间。如果 File 位置不存在,则 spaceAvailable 属性将设置为 0。如果 File 对象引用一个符号链接,则 spaceAvailable 属性将设置为符号链接指向的位置的可用空间。

通常,目录或文件的可用空间与包含该目录或文件的卷上的可用空间相同。不过,可用空间与磁盘配额及每个目录的空间限制有关。

将文件或目录添加到卷中通常需要比文件的实际大小或目录中内容的实际大小更多的空间。例如,操作系统可能需要更多空间来存储索引信息。或者,所需的磁盘扇区可能会使用额外的空间。此外,可用空间是动态变化的。因此,您不能期望为文件存储分配报告的全部空间。有关写入文件系统的信息,请参阅读取和写入文件

StorageVolumeInfo.getStorageVolumes() 方法提供有已关装的存储卷的更多详细信息(请参阅使用存储卷)。

使用默认系统应用程序打开文件

在 AIR 2 中,您可以使用操作系统注册的用来打开某文件的应用程序打开该文件。例如,AIR 应用程序可以使用注册的用来打开文档文件的应用程序打开一个文档文件。使用 File 对象的 openWithDefaultApplication() 方法打开该文件。例如,以下代码打开用户桌面上名为 test.doc 的文件,并且打开该文件所用的是与文档文件相对应的默认应用程序:

var file = air.File.deskopDirectory; 
file = file.resolvePath("test.doc"); 
file.openWithDefaultApplication();
注: 在 Linux 中,文件的 MIME 类型(而不是文件扩展名)确定文件的默认应用程序。

以下代码使用户可以导航到一个 mp3 文件,并在用于播放 mp3 文件的默认应用程序中打开它:

var file = air.File.documentsDirectory; 
var mp3Filter = new air.FileFilter("MP3 Files", "*.mp3"); 
file.browseForOpen("Open", [mp3Filter]); 
file.addEventListener(Event.SELECT, fileSelected); 
function fileSelected(event) 
{ 
    file.openWithDefaultApplication(); 
}

无法对位于应用程序目录中的文件使用 openWithDefaultApplication() 方法。

AIR 会阻止您使用 openWithDefaultApplication() 方法打开某些文件。在 Windows 中,AIR 会阻止您打开某些文件类型的文件,例如 EXE 或 BAT。在 Mac OS 和 Linux 中,AIR 阻止您打开将在某些应用程序中启动的文件。(其中包括 Mac OS 中的 Terminal 和 AppletLauncher 以及 Linux 中的 csh、bash 或 ruby。)尝试使用 openWithDefaultApplication() 方法打开其中一个文件将导致异常。有关阻止打开的文件类型的完整列表,请参阅 File.openWithDefaultApplication() 方法的语言参考条目。

注: 对于使用本机安装程序(一种扩展桌面应用程序)安装的 AIR 应用程序不存在这种限制。