PhoneGap API介绍：File

对象：

DirectoryEntry DirectoryReader File FileEntry FileError FileReader FileSystem FileTransfer FileTransferError FileUploadOptions FileUploadResult FileWriter Flags LocalFileSystem Metadata

 DirectoryEntry

该对象代表文件系统中的一个目录，W3C的目录和系统规范对其进行了定义。

属性：

isFile： 总是false。（布尔类型）isFile：总是false。（布尔类型） isDirectory：总是true。(布尔类型) name：DirectoryEntry的名称，不包含前置路径。（DOMString类型） fullPath：从根目录到当前DirectoryEntry的完整绝对路径。（DOMString类型）

备注：以下属性虽然在W3C规范中进行了定义，但PhoneGap并不支持：

filesystem：DirectoryEntry驻留的文件系统。（FileSystem类型）

方法：

DirectoryEntry对象有以下方法可以被调用： getMetadata： 获得目录的元数据。 moveTo：移动一个目录到文件系统中不同的位置。 copyTo：拷贝一个目录到文件系统中不同的位置。 toURI：返回一个可以定位目录的URI。 remove：删除一个目录，被删除的目录必须是空的。 getParent：查找父级目录。 createReader：创建一个可以从目录中读取条目的新DirectoryReader对象。 getDirectory：创建或查找一个目录。 getFile：创建或查找一个文件。 removeRecursively：删除一个目录以及它的所有内容。

支持的平台：

Android BlackBerry WebWorks (OS 5.0或更高版本) iOS

getMetadata：

查找目录的元数据。

参数：

successCallback：获取元数据successCallback：获取元数据成功后回调此函数，参数为一个Metadata 对象。（函数类型） errorCallback：试图检索元数据发生错误的时候回调此函数，参数为一个FileError对象。（函数类型）

简单的范例：

moveTo：

移动一个目录到文件系统中不同的位置。在尝试进行以下操作时会发生错误: 移动目录到其自身，或者移动到其任意深度的任意子目录中； 同级移动（将一个目录移动到它的父目录中）时没有提供和当前名称不同的名称； 移动目录到一个文件所占用的路径； 移动目录到一个非空目录所占用的路径。 另外，尝试移动一个目录到另一个已经存在的空目录上时，系统会尝试删除并替换已存在的目录。

参数：

parent：将目录对象移动到的父级目录。(DirectoryEntry类型) newName：目录的新名字。如果没有指定，默认为当前名字。（DOMString类型） successCallback：移动成功后调用的回调函数，参数为移动后的新目录的DirectoryEntry对象。（函数类型） errorCallback：试图移动目录发生错误时调用的回调函数，参数为一个FileError对象。（函数类型）

简单的范例：

copyTo：

拷贝一个目录到文件系统中不同的位置。在尝试进行以下操作时会发生错误: 拷贝一个目录到其任意深度的子目录中； 同级拷贝（将一个目录拷贝到它的父目录中）时没有提供和当前名称不同的名称； 目录总是递归操作 — 也就是说，会拷贝目录中的所有内容。

参数：

parent：将目录对象拷贝到的父级目录。(DirectoryEntry类型) newName：目录的新名称。如果没有指定，默认为当前名字。（DOMString类型） successCallback：拷贝成功后调用的回调函数，参数为拷贝后的新目录的DirectoryEntry对象。（函数类型） errorCallback：试图拷贝目录发生错误时调用的回调函数，其参数为一个FileError对象。（函数类型）

简单的范例：

toURI：

返回一个用于定位该文件的URI。

简单的范例：

remove：

删除一个目录。在尝试进行以下操作时会发生错误: 删除一个非空目录； 删除文件系统的根目录。

参数：

successCallback：目录删除成功后调用的回调函数，无参数。（函数类型） errorCallback：试图删除目录发生错误时调用的回调函数，其参数为一个FileError对象。（函数类型）

简单的范例：

getParent：

查找包含当前目录的父级DirectoryEntry。

参数：

successCallback： 查找成功后调用此回调函数，参数为当前目录的父级DirectoryEntry对象。（函数类型） errorCallback：试图获得当前目录的父级DirectoryEntry对象发生错误时调用的回调函数，其参数为一个FileError对象。（函数类型）

简单的范例：

createReader：

建立一个新的DirectoryReader对象用来读取目录的所有条目。

简单的范例：

getDirectory：

创建新的目录或查询一个存在的目录，在尝试进行以下操作时会发生错误: 创建一个直属父级目录尚不存在的目录。

参数：

path：查找或创建的目录路径，可以是一个绝对路径或者是对应当前DirectoryEntry的相对路径。（DOMString类型） options：用于指定如果查找的目录不存在时是否创建该目录的选项。（Flags类型） successCallback：获取成功后调用的回调函数，参数为查找到或创建的DirectoryEntry对象。（函数类型） errorCallback：创建或查找目录发生错误时调用的回调函数，其参数为一个FileError对象。（函数类型）

简单的范例：

getFile：

创建新的文件或查询一个存在的文件，在尝试进行以下操作时会发生错误: 创建一个直属父级目录尚不存在的文件。

参数：

path：查找或创建的文件路径，可以是一个绝对路径或者是对应当前DirectoryEntry的相对路径。（DOMString类型） options：用于指定如果查找的文件不存在时是否创建该文件的选项。（Flags类型） successCallback：获取成功后调用的回调函数，参数为查找到或创建的FileEntry对象。（函数类型） errorCallback：创建或查找文件发生错误时调用的回调函数，其参数为一个FileError对象。（函数类型）

简单的范例：

removeRecursively：

删除一个目录及其所有内容。在删除过程中发生错误时（例如：试图删除一个包含不可删除文件的目录），该目录中的部分内容可能已经被删除。在尝试进行以下操作时会发生错误： 删除filesystem的根目录。

参数：

successCallback：当DirectoryEntry删除成功后调用的回调函数，无参数。（函数类型） errorCallback：当试图删除DirectoryEntry发生错误时调用的回调函数，其参数为一个FileError对象。（函数类型）

简单的范例：

DirectoryReader

包含目录中所有的文件和子目录的列表对象，W3C的目录和系统规范对其进行了定义。

方法：

readEntries：读取目录中的所有条目。

支持的平台：

Android BlackBerry WebWorks (OS 5.0或更高版本) iOS

readEntries：

读取当前目录中的所有条目。

参数：

successCallback：读取成功后调用的回调函数，参数为一个包含FileEntry和DirectoryEntry的对象数组。（函数类型） errorCallback：检索目录列表发生错误时调用的回调函数，其参数为一个FileError对象。（函数类型）

简单的范例：

File

该对象包含单个文件的属性。

属性：

name：文件的名称。（DOMString类型） fullPath：文件的完整路径，包含文件名称。（DOMString类型） type：文件的mime类型。（DOMString类型） lastModifiedDate：文件最后被修改的时间。(日期类型) size：以字节为单位的文件大小。（长整型）

详述：

File对象包含单个文件的属性，你可以通过调用FileEntry对象的file方法获得一个File对象实例。

支持的平台：

Android BlackBerry WebWorks (OS 5.0或更高版本) iOS

FileSystem

这个对象表示一个文件系统。

属性：

name：文件系统的名称。（DOMString类型） root：文件系统的根目录。（DirectoryEntry类型）

详述：

FileSystem对象代表当前文件系统的信息。文件系统的名称在公开的文件系统列表中是唯一的。它的root属性包含一个代表当前文件系统的根目录的DirectoryEntry对象。

支持的平台：

Android BlackBerry WebWorks (OS 5.0或更高版本) iOS

File System简单的范例：

完整的范例：

FileEntry

该对象代表文件系统中的一个文件，W3C目录和系统规范对其进行了定义。

属性：

isFile：返回值总是true。（布尔类型） isDirectory：返回值总是false。（布尔类型） name：FileEntry的名称，不包含前置路径。（DOMString类型） fullPath：从根目录到当前FileEntry的完整绝对路径。（DOMString类型）

备注：以下属性虽然在W3C规范中进行了定义，但PhoneGap并不支持：

filesystem：FileEntry驻留的文件系统名称。（FileSystem类型）

方法：

getMetadata： 获得文件的元数据。 moveTo：移动一个文件到文件系统中不同的位置。 copyTo：拷贝一个文件到文件系统中不同的位置。 toURI：返回一个可以定位文件的URI。 remove：删除一个文件。 getParent：查找父级目录。 createWriter：创建一个可以写入文件的FileWriter对象。 file：创建一个包含文件属性的File对象。

支持的平台：

Android BlackBerry WebWorks (OS 5.0或更高版本) iOS

getMetadata：

查找文件的元数据。

参数：

successCallback：获取元数据成功后调用的回调函数，参数为一个Metadata 对象。（函数类型） errorCallback：试图检索元数据发生错误后调用的回调函数，参数为一个FileError对象。（函数类型）

简单的范例：

moveTo：

移动一个文件到文件系统中不同的位置。在尝试进行以下操作时会发生错误: 同级移动（将一个文件移动到它的父目录中）时没有提供和当前名称不同的名称； 移动文件到一个目录所占用的路径； 此外，尝试移动一个文件到另一个已经存在的空文件上时，系统会尝试删除并替换已存在的文件。

参数：

parent：将文件对象移动到的父级目录。(DirectoryEntry类型) newName：文件的新名称。如果没有指定，默认为当前名字。（DOMString类型） successCallback：移动成功后调用的回调函数，参数为移动后新文件的FileEntry对象。（函数类型） errorCallback：试图移动文件发生错误时调用的回调函数，参数为一个FileError对象。（函数类型）

简单的范例：

copyTo：

拷贝一个文件到文件系统中新的位置。在尝试进行以下操作时会发生错误: 同级拷贝（将一个文件拷贝到它的父目录中）时没有提供和当前名称不同的名称；

参数：

parent：将文件对象拷贝到的父级目录。(DirectoryEntry类型) newName：文件的新名字。如果没有指定，默认为当前名字。（DOMString类型） successCallback：拷贝成功后调用的回调函数，参数为拷贝后新文件的FileEntry对象。（函数类型） errorCallback：试图拷贝文件发生错误时调用的回调函数，其参数为一个FileError对象。（函数类型）

简单的范例：

toURI：

返回一个用于定位该文件的URI。

简单的范例：

remove：

删除一个文件。

参数：

successCallback：文件删除成功后调用的回调函数，无参数。（函数类型） errorCallback：试图删除文件发生错误时调用的回调函数，其参数为一个FileError对象。（函数类型）

简单的范例：

getParent：

查找包含当前文件的父级DirectoryEntry。

参数：

successCallback：查找成功后调用的回调函数，参数为当前文件的父级DirectoryEntry对象。（函数类型） errorCallback：试图获得当前文件的父级DirectoryEntry对象发生错误时调用的回调函数，其参数为一个FileError对象。（函数类型）

简单的范例：

createWriter：

创建一个FileEntry所代表的文件相关的FileWriter对象。

参数：

successCallback：创建成功后调用的回调函数，参数为FileWriter对象。（函数类型） errorCallback：试图创建FileWriter发生错误时调用的回调函数，其参数为一个FileError对象。（函数类型）

简单的范例：

file

返回表示这个FileEntry所代表文件的当前状态的File对象。

参数：

successCallback：获取成功后调用的回调函数，其参数为一个File对象。（函数类型） errorCallback：创建File对象发生错误时调用的回调函数（例如：底层的文件已不再存在），其参数为一个FileError对象。（函数类型）

简单的范例：

FileReader

FileReader是一个允许用户读取文件的对象。

属性：

readyState: 当前读取器所处的状态，取值为以下三者之一：EMPTY、LOADING和DONE。 result：已读取文件的内容。（DOMString类型） error：包含错误信息的对象。（FileError类型） onloadstart：读取启动时调用的回调函数。（函数类型） onprogress：读取过程中调用的回调函数，用于汇报读取进度（progress.loaded和progress.total）。（函数类型） 不支持 onload：读取安全完成后调用的回调函数。（函数类型） onabort：读取被中止后调用的回调函数，例如通过调用abort()方法。（函数类型） onerror：读取失败后调用的回调函数。（函数类型） onloadend：请求完成后调用的回调函数（无论请求是成功还是失败）。（函数类型）

方法：

abort： 中止读取文件。 readAsDataURL：读取文件，结果以Base64编码的data URL形式返回。(data URL的格式由IETF在RFC2397中定义) readAsText：读取文件，结果以文本字符串返回。

详述：

FileReader对象是从设备文件系统读取文件FileReader对象是从设备文件系统读取文件的一种方式，文件以文本或者Base64编码的字符串形式读出来。用户注册自己的事件监听器来接收loadstart、progress、load、loadend、error和abort事件。

支持的平台：

Android BlackBerry WebWorks (OS 5.0或更高版本) iOS

ReadAsDataURL：

参数：

file：读取的文件对象

简单的范例：

ReadAsText：

参数：

file：读取的文件对象。 encoding：用来编码文件内容的编码格式，默认值为UTF8。

简单的范例：

Abort 简单的范例：

完整的范例：

iOS 的特异情况：

不支持encoding参数，总是用UTF8编码格式。

FileWriter

FileWriter是一个允许用户写文件的对象。

属性：

readyState：当前写入器所处的状态，取值为以下三者之一：INIT、WRITING和DONE。 fileName：要进行写入的文件的名称。（DOMString类型） length：要进行写入的文件的当前长度。（长整型） position：文件指针的当前位置。（长整型） error：包含错误信息的对象。（FileError类型） onwritestart：写入操作启动时调用的回调函数。（函数类型） onprogress：写入过程中调用的回调函数，用于汇报写入进度（progress.loaded和progress.total）。（函数类型）— 不支持 onwrite：当写入成功完成后调用的回调函数。（函数类型） onabort：写入被中止后调用的回调函数，例如通过调用abort()方法。（函数类型） onerror：写入失败后调用的回调函数。(函数类型) onwriteend：请求完成后调用的回调函数（无论请求是成功还是失败）。（函数类型）

方法：

abort：中止写入文件。 seek：移动文件指针到指定的字节位置。 truncate：按照指定长度截断文件。 write：向文件中写入数据。

详述：

FileWriter对象是从设备文件系统写入文件FileWriter对象是从设备文件系统写入文件的一种方式，用户注册自己的事件监听器来接收writestart、progress、write、writeend、error和abort事件。 一个FileWriter对象是为单个文件的操作而创建。你可以使用该对象多次对相应文件进行写入操作。FileWriter维护该文件的指针位置及长度属性，这样你就可以寻找和写入文件的任何地方。默认情况下，FileWriter从文件的开头开始写入（将覆盖现有数据）。在FileWriter的构造函数中设置可选的append参数值为ture，写入操作就会从文件的末尾开始。

支持的平台：

Android BlackBerry WebWorks (OS 5.0或更高版本) iOS

Seek的简单范例：

Truncate 的简单范例：

Write 的简单范例：

Append 的简单范例：

完整的范例：

FileError

任何File API的方法发生错误时，错误属性都被设置为一个FileError对象。

属性：

code： 一个在下面常量列表中定义好的错误代码。

常量：

FileError.NOT_FOUND_ERR：没有找到相应的文件或目录的错误。(W3C File System API) FileError.SECURITY_ERR：所有没被其他错误类型所涵盖的安全错误，包括：当前文件在Web应用中被访问是不安全的；对文件资源过多的访问等。(W3C File System API) FileError.ABORT_ERR：中止错误。 FileError.NOT_READABLE_ERR：文件或目录无法读取的错误，通常是由于另外一个应用已经获取了当前文件的引用并使用了并发锁。（W3C File System API） FileError.ENCODING_ERR：编码错误。 FileError.NO_MODIFICATION_ALLOWED_ERR：修改拒绝的错误，当试图写入一个底层文件系统状态决定其不能修改的文件或目录时。（W3C File System API） FileError.INVALID_STATE_ERR：无效状态错误。 FileError.SYNTAX_ERR：语法错误，用于File Writer对象。（W3C File System API） FileError.INVALID_MODIFICATION_ERR：非法的修改请求错误，例如同级移动（将一个文件或目录移动到它的父目录中）时没有提供和当前名称不同的名称时。（W3C File System API） FileError.QUOTA_EXCEEDED_ERR：超过配额错误，当操作会导致应用程序超过系统所分配的存储配额时。（W3C File System API） FileError.TYPE_MISMATCH_ERR：类型不匹配错误，当试图查找文件或目录而请求的对象类型错误时。（例如：当用户请求一个FileEntry是一个DirectoryEntry对象）（W3C File System API） FileError.PATH_EXISTS_ERR：路径已存在错误，当试图创建路径已经存在的文件或目录时。（W3C File System API）

说明：

FileError对象是所有File API的错误回调函数的唯一参数。开发者必须根据错误代码属性决定错误类型。

FileTransfer

FileTransfer是一个允许你向服务器上传文件的对象。

属性：

N/A

方法：

upload：上传一个文件到服务器。

详述：

FileTransfer对象提供了一种将文件上传到远程服务器的方法，通过HTTP多部分POST请求，同时支持HTTP和HTTPS协议。可以传递一个由FileUploadOptions对象设定的可选参数给upload方法。上传成功后，系统会调用成功回调函数并传递一个FileUploadResult对象。如果出现错误，系统会调用错误回调函数并传递一个FileTransferError对象。

支持的平台：

Android BlackBerry WebWorks (OS 5.0或更高版本) iOS

简单的范例：

完整的范例：

FileUploadOptions

一个FileUploadOptions对象可以作为参数传递给FileTransfer对象的上传文件方法，以指定上传脚本的其它参数。

属性：

fileKey：表单元素的name值，如果没有设置默认为 “file” 。（DOMString类型） fileName：你希望文件存储到服务器所用的文件名，如果没有设置默认为 “image.jpg”。（DOMString类型） mimeType：正在上传数据所使用的mime类型，如果没有设置默认为“image/jpeg”。（DOMString类型） params：通过HTTP请求发送到服务器的一系列可选键/值对。（对象类型）

说明：

一个FileUploadOptions对象可以作为参数传递给FileTransfer对象的上传文件方法，以指定上传脚本的其他参数。

FileUploadResult

FileTransfer的upload方法调用成功后，通过回调函数将一个FileUploadResult对象返回给用户。

属性：

bytesSent：上传文件时向服务器所发送的字节数。（长整型） responseCode：服务器端返回的HTTP响应代码。（长整型） response：服务器端返回的HTTP响应。（DOMString类型）

说明：

FileTransfer方法调用成功后，通过回调函数将一个FileUploadResult对象返回给用户。

iOS的特异情况：

iOS的成功回调函数返回的FileUploadResult对象中不包含responseCode和bytesSent的值。

FileTransferError

当文件传输过程中发生错误时，通过错误回调函数返回一个FileTransferError对象。

属性：

code：一个在下面常量列表中定义的错误代码。（整数类型）

常量：

FileTransferError.FILE_NOT_FOUND_ERR：文件未找到错误。 FileTransferError.INVALID_URL_ERR：无效的URL错误。 FileTransferError.CONNECTION_ERR：连接错误。

说明：

当文件传输过程中发生错误时，通过错误回调函数返回一个FileTransferError对象。

Flags

该对象用于为DirectoryEntry对象的getFile和getDirectory方法提供参数，这两个方法分别用于查找或创建文件和目录。

属性：

create: 用于指示如果文件或目录不存在时是否进行创建。（布尔类型） exclusive：就其本身而言没有任何效果。和create一起使用时，当要创建的目标路径已经存在，它会导致文件或目录创建失败。（布尔类型）

支持的平台：

Android BlackBerry WebWorks (OS 5.0或更高版本) iOS

简单的范例：

LocalFileSystem

该对象提供一个方法来获得根文件系统。

方法：

requestFileSystem：请求一个filesystem对象。（函数类型） resolveLocalFileSystemURI：通过本地URI参数检索DirectoryEntry或FileEntry。（函数类型）

常量：

LocalFileSystem.PERSISTENT：用于不经过应用程序或者用户许可就无法通过用户代理移除的存储类型。 LocalFileSystem.TEMPORARY：用于不需要保证持久化的存储类型。

详述：

LocalFileSystem对象的方法定义在window对象内。

支持的平台：

Android BlackBerry WebWorks (OS 5.0或更高版本) iOS

Request File System简单的范例：

完整的范例：

Metadata

这个接口提供一个文件或目录的状态信息。

属性：

modificationTime：文件或目录最后的修改时间。（日期类型）

详述：

Metadata对象代表一个文件或目录的状态信息，你可以通过调用DirectoryEntry或FileEntery的getMetadata方法来获得Metadata对象的实例。

支持的平台：

Android BlackBerry WebWorks (OS 5.0或更高版本) iOS

简单的范例：