# [io]()
IO模块管理本地文件系统，用于对文件系统的目录浏览、文件的读取、文件的写入等操作。通过plus.io可获取文件系统管理对象。
### 常量：
- [PRIVATE_WWW](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.PRIVATE_WWW): 应用运行资源目录常量
- [PRIVATE_DOC](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.PRIVATE_DOC): 应用私有文档目录常量
- [PUBLIC_DOCUMENTS](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.PUBLIC_DOCUMENTS): 程序公用文档目录常量
- [PUBLIC_DOWNLOADS](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.PUBLIC_DOWNLOADS): 程序公用下载目录常量
### 方法：
- [requestFileSystem](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.requestFileSystem): 请求本地文件系统对象
- [resolveLocalFileSystemURL](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.resolveLocalFileSystemURL): 通过URL参数获取目录对象或文件对象
- [convertLocalFileSystemURL](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.convertLocalFileSystemURL): 将本地URL路径转换成平台绝对路径
- [convertAbsoluteFileSystem](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.convertAbsoluteFileSystem): 将平台绝对路径转换成本地URL路径
### 对象：
- [DirectoryEntry](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry): 文件系统中的目录对象，用于管理特定的本地目录
- [DirectoryReader](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryReader): 读取目录信息对象，用于获取目录中包含的文件及子目录
- [File](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.File): 文件系统中的文件数据对象，用于获取文件的数据
- [FileEntry](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEntry): 文件系统中的文件对象，用于管理特定的本地文件
- [FileReader](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileReader): 文件系统中的读取文件对象，用于获取文件的内容
- [FileWriter](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileWriter): 文件系统中的写文件对象，用于写入文件内容
- [FileSystem](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileSystem): 文件系统对象，用于管理特定本地文件目录
- [Flags](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.Flags): JSON对象，获取文件操作的参数
- [Metadata](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.Metadata): JSON对象，保存文件或目录的状态信息对象
- [FileEvent](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEvent): 文件或目录操作事件对象
- [URLType](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.URLType): 文件路径类型
- [RelativeURL](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.RelativeURL): 相对路径URL
- [LocalURL](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.LocalURL): 本地路径URL
- [RemoteURL](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.RemoteURL): 网络路径URL
### 回调方法：
- [FileEventCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEventCallback): 文件事件回调
- [FileSystemSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileSystemSuccessCallback): 请求文件系统成功的回调函数
- [FileResolveSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileResolveSuccessCallback): 通过URL参数获取目录或文件对象成功的回调函数
- [MetadataSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.MetadataSuccessCallback): 获取文件或目录状态信息成功的回调函数
- [EntrySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.EntrySuccessCallback): 操作文件或目录对象成功的回调函数
- [EntrysSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.EntrysSuccessCallback): 操作文件或目录对象数组成功的回调函数
- [FileWriterSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileWriterSuccessCallback): 写文件操作成功的回调函数
- [FileSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileSuccessCallback): 文件操作成功的回调函数
- [FileErrorCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileErrorCallback): 文件操作失败的回调函数
### 权限：
permissions
~~~
"File": {
"description": "访问本地文件系统"
}
~~~
# [PRIVATE_WWW]()
应用运行资源目录常量
~~~
plus.io.PRIVATE_WWW;
~~~
### 说明：
Number 类型
本地文件系统常量，Number类型，固定值1。应用运行资源目录，仅本应用可访问。 为了确保应用资源的安全性，此目录只可读。
### 平台支持
- Android - ALL (支持): Android平台应用资源是放到apk的assets目录中，安装到设备后无法枚举，为了能够正常枚举访问此目录，需要将应用设置为释放资源模式（在manifest.json中将runmode值设置为liberate），这样程序在第一次运行时将资源释放到sdcard中。 通常在设备上的目录为“/sdcard/Android/data/%PACKAGENAME%/.%APPID%/apps/%APPID%/www”，其中%PACKAGENAME%是程序的包名、%APPID%是应用的标识，如“/sdcard/Android/data/io.dcloud.HBuilder/.HBuilder/apps/HBuilder/www”。
- iOS - ALL (支持): iOS平台应用资源是放到应用的沙盒目录中，安装到设备后放到应用沙盒目录的“/DCloud_Pandora.app/Pandora/apps/%APPID%/www”，如“/DCloud_Pandora.app/Pandora/apps/HBuilder/www”。 如将应用设置为释放资源模式（在manifest.json中将runmode值设置为liberate），程序在第一次运行时将资源释放到应用沙盒目录下的Library中“/Library/Pandora/apps/%APPID%/www”，如“/Library/Pandora/apps/HBuilder/www”。
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>File Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
plus.io.requestFileSystem( plus.io.PRIVATE_WWW, function( fs ) {
// 可通过fs操作PRIVATE_WWW文件系统
// ......
}, function ( e ) {
alert( "Request file system failed: " + e.message );
} );
}
</script>
</head>
<body>
Local file system
</body>
</html>
~~~
# [PRIVATE_DOC]()
应用私有文档目录常量
~~~
plus.io.PRIVATE_DOC;
~~~
### 说明：
Number 类型
本地文件系统常量，Number类型，固定值2。应用私有文档目录，仅本应用可读写。
### 平台支持
- Android - ALL (支持): 通常在设备上的目录为“/sdcard/Android/data/%PACKAGENAME%/.%APPID%/apps/%APPID%/doc”，其中%PACKAGENAME%是程序的包名、%APPID%是应用的标识，如“/sdcard/Android/data/io.dcloud.HBuilder/.HBuilder/apps/HBuilder/doc”。
- iOS - ALL (支持): 通常在设备应用沙盒目录下“/Library/Pandora/apps/%APPID%/doc”，其中%APPID%是应用的标识，，如“/Library/Pandora/apps/HBuilder/doc”。
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>File Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
plus.io.requestFileSystem( plus.io.PRIVATE_DOC, function( fs ) {
// 可通过fs操作PRIVATE_DOC文件系统
// ......
}, function ( e ) {
alert( "Request file system failed: " + e.message );
} );
}
</script>
</head>
<body>
Local file system
</body>
</html>
~~~
# [PUBLIC_DOCUMENTS]()
程序公用文档目录常量
~~~
plus.io.PUBLIC_DOCUMENTS;
~~~
### 说明：
Number 类型
本地文件系统常量，Number类型，固定值3。程序公用文档目录，所有应用可读写。
### 平台支持
- Android - ALL (支持): 通常在设备上的目录为“/sdcard/Android/data/%PACKAGENAME%/.%APPID%/documents”，其中%PACKAGENAME%是程序的包名、%APPID%是应用的标识，如“/sdcard/Android/data/io.dcloud.HBuilder/.HBuilder/documents”。
- iOS - ALL (支持): 通常在设备应用沙盒目录下“/Library/Pandora/documents”。
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>File Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
plus.io.requestFileSystem( plus.io.PUBLIC_DOCUMENTS, function( fs ) {
// 可通过fs操作PUBLIC_DOCUMENTS文件系统
// ......
}, function ( e ) {
alert( "Request file system failed: " + e.message );
} );
}
</script>
</head>
<body>
Local file system
</body>
</html>
~~~
# [PUBLIC_DOWNLOADS]()
程序公用下载目录常量
~~~
plus.io.PUBLIC_DOWNLOADS;
~~~
### 说明：
Number 类型
本地文件系统常量，Number类型，固定值4。程序公用下载目录，所有应用可读写。
### 平台支持
- Android - ALL (支持): 通常在设备上的目录为“/sdcard/Android/data/%PACKAGENAME%/.%APPID%/downloads”，其中%PACKAGENAME%是程序的包名、%APPID%是应用的标识，如“/sdcard/Android/data/io.dcloud.HBuilder/.HBuilder/downloads”。
- iOS - ALL (支持): 通常在设备应用沙盒目录下“/Library/Pandora/downloads”。
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>File Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
plus.io.requestFileSystem( plus.io.PUBLIC_DOWNLOADS, function( fs ) {
// 可通过fs操作PUBLIC_DOWNLOADS文件系统
// ......
}, function ( e ) {
alert( "Request file system failed: " + e.message );
} );
}
</script>
</head>
<body>
Local file system
</body>
</html>
~~~
# [requestFileSystem]()
请求本地文件系统对象
~~~
void plus.io.requestFileSystem( type, succesCB, errorCB );
~~~
### 说明：
获取指定的文件系统，可通过type指定获取文件系统的类型。 获取指定的文件系统对象成功通过succesCB回调返回，失败则通过errorCB返回。
### 参数：
- type: *( Number ) 必选 *本地文件系统常量
可取plus.io下的常量，如plus.io.PRIVATE_DOC、plus.io.PUBLIC_DOCUMENTS等。
- succesCB: *( [FileSystemSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileSystemSuccessCallback) ) 必选 *请求文件系统成功的回调
- errorCB: *( [FileErrorCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileErrorCallback) ) 可选 *请求文件系统失败的回调
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>File Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
plus.io.requestFileSystem( plus.io.PRIVATE_WWW, function( fs ) {
// 可通过fs进行文件操作
alert( "Request file system success!" );
}, function ( e ) {
alert( "Request file system failed: " + e.message );
} );
}
</script>
</head>
<body>
Request file system
</body>
</html>
~~~
# [resolveLocalFileSystemURL]()
通过URL参数获取目录对象或文件对象
~~~
void plus.io.resolveLocalFileSystemURL( url, succesCB, errorCB );
~~~
### 说明：
快速获取指定的目录或文件操作对象，如通过URL值“_www/test.html”可直接获取文件操作对象。 url值可支持相对路径URL、本地路径URL、网络路径URL(http://localhost:13131/开头)。 获取指定的文件或目录操作对象成功通过succesCB回调返回，如果指定URL路径或文件不存在则失败通过errorCB回调返回。
### 参数：
- url : *( DOMString ) 必选 *要操作文件或目录的URL地址
- succesCB: *( [FileResolveSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileResolveSuccessCallback) ) 必选 *获取操作文件或目录对象成功的回调函数
- errorCB: *( [FileErrorCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileErrorCallback) ) 可选 *获取操作文件或目录对象失败的回调函数
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>File Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
plus.io.resolveLocalFileSystemURL( "_www/test.html", function( entry ) {
// 可通过entry对象操作test.html文件
entry.file( function(file){
var fileReader = new plus.io.FileReader();
alert("getFile:" + JSON.stringify(file));
fileReader.readAsText(file, 'utf-8');
fileReader.onloadend = function(evt) {
alert("11" + evt);
alert("evt.target" + evt.target);
alert(evt.target.result);
}
alert(file.size + '--' + file.name);
} );
}, function ( e ) {
alert( "Resolve file URL failed: " + e.message );
} );
}
</script>
</head>
<body>
Request file system
</body>
</html>
~~~
# [convertLocalFileSystemURL]()
将本地URL路径转换成平台绝对路径
~~~
String plus.io.convertLocalFileSystemURL( url );
~~~
### 说明：
绝对路径符合各平台文件路径格式，通常用于系统原生文件操作API。
### 参数：
- url: *( String ) 必选 *要转换的文件或目录URL地址
URL地址必须是合法的路径，如果地址不合法则返回null。
### 返回值：
String : 转换后的平台路径
# [convertAbsoluteFileSystem]()
将平台绝对路径转换成本地URL路径
~~~
String plus.io.convertAbsoluteFileSystem( path );
~~~
### 说明：
绝对路径符合各平台文件路径格式，转换后变成RelativeURL类型格式。
### 参数：
- path: *( String ) 必选 *要转换的平台绝对路径
绝对路径必须是合法的路径，如果绝对路径不合法则返回null。
### 返回值：
DOMString : 转换后本地URL路径
# [DirectoryEntry]()
文件系统中的目录对象，用于管理特定的本地目录
### 属性：
- [isFile](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry.isFile): 操作对象的是否为文件，DirectoryEntry对象固定其值为false
- [isDirectory](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry.isDirectory): 操作对象是否为目录，DirectoryEntry对象固定其值为true
- [name](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry.name): 目录操作对象的名称，不包括路径
- [fullPath](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry.fullPath): 目录操作对象的完整路径，文件系统的绝对路径
- [fileSystem](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry.fileSystem): 文件操作对象所属的文件系统对象，参考FileSystem
### 方法：
- [getMetadata](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry.getMetadata): 获取目录的属性
- [moveTo](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry.moveTo): 移动目录
- [copyTo](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry.copyTo): 拷贝目录
- [toURL](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry.toURL): 获取目录路径转换为URL地址
- [toLocalURL](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry.toLocalURL): 获取目录路径转换为本地路径URL地址
- [toRemoteURL](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry.toRemoteURL): 获取目录路径转换为网络路径URL地址
- [remove](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry.remove): 删除目录
- [getParent](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry.getParent): 获取目录所属的父目录
- [createReader](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry.createReader): 创建目录读取对象
- [getDirectory](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry.getDirectory): 创建或打开子目录
- [getFile](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry.getFile): 创建或打开文件
- [removeRecursively](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry.removeRecursively): 递归删除目录
# [isFile]()
操作对象的是否为文件，DirectoryEntry对象固定其值为false
### 说明：
Boolean 类型 只读属性
# [isDirectory]()
操作对象是否为目录，DirectoryEntry对象固定其值为true
### 说明：
Boolean 类型 只读属性
# [name]()
目录操作对象的名称，不包括路径
### 说明：
DOMString 类型 只读属性
# [fullPath]()
目录操作对象的完整路径，文件系统的绝对路径
### 说明：
DOMString 类型 只读属性
# [fileSystem]()
文件操作对象所属的文件系统对象，参考FileSystem
### 说明：
FileSystem 类型 只读属性
# [getMetadata]()
获取目录的属性
~~~
entry.getMetadata( successCB, errorCB, recursive );
~~~
### 说明：
用于获取文件或目录的属性信息。 获取属性信息成功通过succesCB回调返回，失败则通过errorCB返回。
### 参数：
- succesCB: *( [MetadataSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.MetadataSuccessCallback) ) 必选 *获取文件或目录属性信息成功的回调
- errorCB: *( [FileErrorCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileErrorCallback) ) 必选 *获取文件或目录属性信息失败的回调
- recursive: *( Boolean ) 必选 *是否递归计算目录信息
true为递归计算获取信息，false不递归计算获取，默认值为false。
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
// Request the metadata object for this entry
entry.getMetadata( function ( metadata ) {
plus.console.log("Last Modified: " + metadata.modificationTime);
}, function () {
alert( e.message );
} );
~~~
# [moveTo]()
移动目录
~~~
entry.moveTo( parent, newName, succesCB, errorCB );
~~~
### 说明：
以下情况移动目录将会导致失败： 将父目录移动到子目录中； 要移动到的目标目录无效； 要移动到的目标路径被文件占用； 要移动到的目标目录已经存在并且不为空。 移动目录成功通过succesCB回调返回，失败则通过errorCB返回。
### 参数：
- parent: *( [DirectoryEntry](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry) ) 必选 *要移动到的目标目录
- newName: *( DOMString ) 可选 *移动后的目录名称，默认为原始目录名称
- succesCB: *( [EntrySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.EntrySuccessCallback) ) 可选 *移动目录成功的回调函数
回调函数中的参数保存新的目录对象。
- errorCB: *( [FileErrorCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileErrorCallback) ) 可选 *移动目录失败的回调函数
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
function moveDirecty(srcEntry,dstEntry) {
var newName = document.getElementById('newName').value,
// move the directory to a new directory and rename it
srcEntry.moveTo( dstEntry, newName, function( entry ) {
plus.console.log("New Path: " + entry.fullPath);
}, function ( e ) {
alert( e.message );
} );
}
~~~
# [copyTo]()
拷贝目录
~~~
entry.copyTo( parent, newName, succesCB, errorCB );
~~~
### 说明：
以下情况拷贝目录将会导致失败： 将父目录拷贝到子目录中； 要拷贝到的目标目录无效； 要拷贝到的目标路径被文件占用； 要拷贝到的目标目录已经存在并且不为空。 拷贝目录成功通过succesCB回调返回，失败则通过errorCB返回。
### 参数：
- parent: *( [DirectoryEntry](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry) ) 必选 *要拷贝到的目标目录
- newName: *( DOMString ) 可选 *拷贝后的目录名称，默认为原始目录名称
- succesCB: *( [EntrySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.EntrySuccessCallback) ) 可选 *拷贝目录成功的回调函数
回调函数中的参数保存新的目录对象。
- errorCB: *( [FileErrorCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileErrorCallback) ) 可选 *拷贝目录失败的回调函数
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
function copyDirecty(srcEntry,dstEntry){
var newName = document.getElementById('newName').value,
// copy the directory to a new directory and rename it
srcEntry.copyTo( dstEntry, newName, function( entry ){
plus.console.log("New Path: " + entry.fullPath);
}, function( e ){
alert( e.message );
} );
}
~~~
# [toURL]()
获取目录路径转换为URL地址
~~~
DOMString entry.toURL();
~~~
### 参数：
### 返回值：
DOMString : 格式为相对路径URL
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
// Get the URL for this directory
var dirURL = entry.toURL();
plus.console.log(dirURL);
~~~
# [toLocalURL]()
获取目录路径转换为本地路径URL地址
~~~
DOMString entry.toLocalURL();
~~~
### 参数：
### 返回值：
DOMString : 格式为本地路径URL
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
// Get the local URL for this directory
var dirURL = entry.toLocalURL();
plus.console.log(dirURL);
~~~
# [toRemoteURL]()
获取目录路径转换为网络路径URL地址
~~~
DOMString entry.toRemoteURL();
~~~
### 参数：
### 返回值：
DOMString : URL地址格式为以“http://localhost:13131/”开头的网络路径。
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
// Get the remote URL for this directory
var dirURL = entry.toRemoteURL();
plus.console.log(dirURL);
~~~
# [remove]()
删除目录
~~~
entry.remove( succesCB, errorCB );
~~~
### 说明：
以下情况删除目录将会导致失败： 目录中存在文件； 删除根目录； 删除目录成功通过succesCB回调返回，失败则通过errorCB返回。
### 参数：
- succesCB: *( [EntrySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.EntrySuccessCallback) ) 可选 *删除目录成功的回调函数
回调函数中无参数。
- errorCB: *( [FileErrorCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileErrorCallback) ) 可选 *删除目录失败的回调函数
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
// remove this directory
entry.remove( function ( entry ) {
plus.console.log( "Remove succeeded" );
}, function ( e ) {
alert( e.message );
} );
~~~
# [getParent]()
获取目录所属的父目录
~~~
entry.getParent( succesCB, errorCB );
~~~
### 说明：
获取父目录成功通过succesCB回调返回，失败则通过errorCB返回。
### 参数：
- succesCB: *( [EntrySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.EntrySuccessCallback) ) 可选 *获取父目录成功的回调函数
- errorCB: *( [FileErrorCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileErrorCallback) ) 可选 *获取父目录失败的回调函数
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
// Get the parent DirectoryEntry
entry.getParent( function ( entry ) {
plus.console.log( "Parent Name: " + entry.name );
}, function ( e ) {
alert( e.message );
} );
~~~
# [createReader]()
创建目录读取对象
~~~
DirectoryReader entry.createReader();
~~~
### 说明：
创建一个目录读取对象，用户读取目下的文件及子目录。
### 参数：
### 返回值：
[DirectoryReader](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryReader) : 目录读取对象
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
// create a directory reader
var directoryReader = entry.createReader();
~~~
# [getDirectory]()
创建或打开子目录
~~~
entry.getDirectory( path, flag, succesCB, errorCB );
~~~
### 说明：
创建或打开当前目录指定的目录。 创建或打开目录操作成功通过succesCB回调返回，失败则通过errorCB返回。
### 参数：
- path: *( DOMString ) 必选 *要操作目录相对于当前目录的地址
- flag: *( [Flags](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.Flags) ) 可选 *要操作文件或目录的参数
- succesCB: *( [EntrySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.EntrySuccessCallback) ) 可选 *创建或打开目录成功的回调函数
- errorCB: *( [FileErrorCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileErrorCallback) ) 可选 *创建或打开目录失败的回调函数
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
// Retrieve an existing directory, or create it if it does not already exist
entry.getDirectory( "newDir", {create:true,exclusive:false}, function( dir ){
console.log("Directory Entry Name: " + dir.name);
}, function () {
alert( e.message );
} );
~~~
# [getFile]()
创建或打开文件
~~~
entry.getFile( path, flag, succesCB, errorCB );
~~~
### 说明：
创建或打开当前目录下指定的文件。 创建或打开文件操作对象成功通过succesCB回调返回，失败则通过errorCB返回。
### 参数：
- path: *( DOMString ) 必选 *要操作文件相对于当前目录的地址
- flag: *( [Flags](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.Flags) ) 可选 *要操作文件或目录的参数
- succesCB: *( [EntrySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.EntrySuccessCallback) ) 可选 *创建或打开文件成功的回调函数
- errorCB: *( [FileErrorCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileErrorCallback) ) 可选 *创建或打开文件失败的回调函数
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>File Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
plus.io.requestFileSystem( plus.io.PRIVATE_WWW, function(fs){
// fs.root是根目录操作对象DirectoryEntry
fs.root.getFile('config.xml',{create:true}, function(fileEntry){
fileEntry.file( function(file){
var fileReader = new plus.io.FileReader();
alert("getFile:" + JSON.stringify(file));
fileReader.readAsText(file, 'utf-8');
fileReader.onloadend = function(evt) {
alert("11" + evt);
alert("evt.target" + evt.target);
alert(evt.target.result);
}
alert(file.size + '--' + file.name);
} );
});
} );
}
</script>
</head>
<body>
Request file system
</body>
</html>
~~~
# [removeRecursively]()
递归删除目录
~~~
entry.removeRecursively( succesCB, errorCB );
~~~
### 说明：
删除目录将会删除其下的所有文件及子目录 不能删除根目录，如果操作删除根目录将会删除目录下的文件及子目录，不会删除根目录自身。 删除目录成功通过succesCB回调返回，失败则通过errorCB返回。
### 参数：
- succesCB: *( [EntrySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.EntrySuccessCallback) ) 可选 *删除目录成功的回调函数
回调函数中无参数。
- errorCB: *( [FileErrorCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileErrorCallback) ) 可选 *删除目录失败的回调函数
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
// remove the directory and all it's contents
entry.removeRecursively( function ( entry ) {
plus.console.log( "Remove Recursively Succeeded" );
}, function ( e ) {
alert( e.message );
} );
~~~
# [DirectoryReader]()
读取目录信息对象，用于获取目录中包含的文件及子目录
### 方法：
- [readEntries](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryReader.readEntries): 获取当前目录中的所有文件和子目录
# [readEntries]()
获取当前目录中的所有文件和子目录
~~~
directoryReader.readEntries( succesCB, errorCB );
~~~
### 说明：
获取当前目录下的所有文件和子目录。 获取操作成功通过succesCB回调返回，失败则通过errorCB返回。
### 参数：
- succesCB: *( [EntrySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.EntrySuccessCallback) ) 可选 *获取成功的回调函数
- errorCB: *( [FileErrorCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileErrorCallback) ) 可选 *获取失败的回调函数
### 返回值：
void : 无
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>File Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
plus.io.requestFileSystem( plus.io.PRIVATE_WWW, function(fs){
// fs.root是根目录操作对象DirectoryEntry
// 创建读取目录信息对象
var directoryReader = fs.root.createReader();
directoryReader.readEntries( function( entries ){
var i;
for( i=0; i < entries.length; i++ ) {
alert( entries[i].name );
}
}, function ( e ) {
alert( "Read entries failed: " + e.message );
} );
} );
}
</script>
</head>
<body>
Request file system
</body>
</html>
~~~
# [File]()
文件系统中的文件数据对象，用于获取文件的数据
### 属性：
- [size](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.File.size): 文件数据对象的数据大小，单位为字节
- [type](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.File.type): 文件数据对象MIME类型
- [name](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.File.name): 文件数据对象的名称，不包括路径
- [lastModifiedDate](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.File.lastModifiedDate): 文件对象的最后修改时间
### 方法：
- [slice](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.File.slice): 获取文件指定的数据内容
- [close](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.File.close): 关闭文件数据对象
# [size]()
文件数据对象的数据大小，单位为字节
### 说明：
Number 类型 只读属性
# [type]()
文件数据对象MIME类型
### 说明：
DOMString 类型 只读属性
# [name]()
文件数据对象的名称，不包括路径
### 说明：
DOMString 类型 只读属性
# [lastModifiedDate]()
文件对象的最后修改时间
### 说明：
Date 类型 只读属性
# [slice]()
获取文件指定的数据内容
~~~
file.slice( start, end );
~~~
### 说明：
获取文件指定的数据内容，其中end必须大于start。
### 参数：
- start: *( Number ) 可选 *获取文件数据的其实位置
- end: *( Number ) 可选 *获取文件数据的结束位置
### 返回值：
[File](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.File) : 指定数据内容的文件对象
### 示例：
~~~
var slice1 = file.slice(100, 400);
var slice2 = slice1.slice(20, 35);
var slice3 = file.slice(120, 135);
// slice2 and slice3 are equivalent.
~~~
# [close]()
关闭文件数据对象
~~~
file.close();
~~~
### 说明：
当文件数据对象不再使用时，可通过此方法关闭，释放系统资源。
### 参数：
### 返回值：
void : 无
### 示例：
~~~
var slice1 = file.slice(100, 400);
var slice2 = slice1.slice(20, 35);
var slice3 = file.slice(120, 135);
// slice2 and slice3 are equivalent.
// ......
slice3.close();
~~~
# [FileEntry]()
文件系统中的文件对象，用于管理特定的本地文件
### 属性：
- [isFile](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEntry.isFile): 文件操作对象的是否为文件，FileEntry对象固定其值为true
- [isDirectory](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEntry.isDirectory): 文件操作对象是否为目录，FileEntry对象固定其值为false
- [name](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEntry.name): 文件操作对象的名称，不包括路径
- [fullPath](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEntry.fullPath): 文件操作对象的完整路径，文件系统的绝对路径
- [fileSystem](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEntry.fileSystem): 文件操作对象所属的文件系统对象，参考FileSystem
### 方法：
- [getMetadata](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEntry.getMetadata): 获取文件的属性信息
- [moveTo](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEntry.moveTo): 移动文件
- [copyTo](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEntry.copyTo): 拷贝文件
- [toURL](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEntry.toURL): 获取文件路径转换为URL地址
- [toLocalURL](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEntry.toLocalURL): 获取文件路径转换为本地路径URL地址
- [toRemoteURL](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEntry.toRemoteURL): 获取文件路径转换为网络路径URL地址
- [remove](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEntry.remove): 删除文件
- [getParent](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEntry.getParent): 获取文件所属的父目录
- [createWriter](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEntry.createWriter): 获取文件关联的写文件操作对象FileWriter
- [file](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEntry.file): 获取文件数据对象
# [isFile]()
文件操作对象的是否为文件，FileEntry对象固定其值为true
### 说明：
Boolean 类型 只读属性
# [isDirectory]()
文件操作对象是否为目录，FileEntry对象固定其值为false
### 说明：
Boolean 类型 只读属性
# [name]()
文件操作对象的名称，不包括路径
### 说明：
DOMString 类型 只读属性
# [fullPath]()
文件操作对象的完整路径，文件系统的绝对路径
### 说明：
DOMString 类型 只读属性
# [fileSystem]()
文件操作对象所属的文件系统对象，参考FileSystem
### 说明：
[FileSystem](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileSystem) 类型 只读属性
# [getMetadata]()
获取文件的属性信息
~~~
entry.getMetadata( successCB, errorCB );
~~~
### 说明：
用于获取文件的属性信息。 获取属性信息成功通过succesCB回调返回，失败则通过errorCB返回。
### 参数：
- succesCB: *( [MetadataSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.MetadataSuccessCallback) ) 必选 *获取文件属性信息成功的回调函数
- errorCB: *( [FileErrorCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileErrorCallback) ) 必选 *获取文件属性信息失败的回调函数
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
// Request the metadata object for this entry
entry.getMetadata( function ( metadata ) {
plus.console.log("Last Modified: " + metadata.modificationTime);
}, function () {
alert( e.message );
} );
~~~
# [moveTo]()
移动文件
~~~
entry.moveTo( parent, newName, succesCB, errorCB );
~~~
### 说明：
以下情况移动目录将会导致失败： 要移动到的目标目录无效； 要移动到的目标路径被其它文件占用； 移动文件成功通过succesCB回调返回，失败则通过errorCB返回。
### 参数：
- parent: *( [DirectoryEntry](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry) ) 必选 *要移动到的目标目录
- newName: *( DOMString ) 可选 *移动后的文件名称，默认为原始文件名称
- succesCB: *( [EntrySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.EntrySuccessCallback) ) 可选 *移动文件成功的回调函数
回调函数中的参数保存新的文件对象。
- errorCB: *( [FileErrorCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileErrorCallback) ) 可选 *移动文件失败的回调函数
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
function moveFile(fileEntry,dstEntry){
// move the file to a new directory and rename it
fileEntry.moveTo( dstEntry, "newfile.txt", function( entry ){
plus.console.log("New Path: " + entry.fullPath);
}, function( e ){
alert( e.message );
} );
}
~~~
# [copyTo]()
拷贝文件
~~~
entry.copyTo( parent, newName, succesCB, errorCB );
~~~
### 说明：
以下情况拷贝文件将会导致失败： 要拷贝到的目标目录无效； 要拷贝到的目标路径被其它文件占用； 拷贝文件成功通过succesCB回调返回，失败则通过errorCB返回。
### 参数：
- parent: *( [DirectoryEntry](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry) ) 必选 *要拷贝到的目标目录
- newName: *( DOMString ) 可选 *拷贝后的文件名称，默认为原始文件名称
- succesCB: *( [EntrySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.EntrySuccessCallback) ) 可选 *拷贝文件成功的回调函数
回调函数中的参数保存新的文件对象。
- errorCB: *( [FileErrorCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileErrorCallback) ) 可选 *拷贝文件失败的回调函数
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
function copyFile(fileEntry,dstEntry) {
// copy the file to a new directory and rename it
fileEntry.copyTo( dstEntry, "file.copy", function( entry ){
plus.console.log("New Path: " + entry.fullPath);
}, function( e ){
alert( e.message );
} );
}
~~~
# [toURL]()
获取文件路径转换为URL地址
~~~
DOMString entry.toURL();
~~~
### 参数：
### 返回值：
DOMString : 格式为相对路径URL
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
// Get the URL for this file
var fileURL = entry.toURL();
plus.console.log(fileURL);
~~~
# [toLocalURL]()
获取文件路径转换为本地路径URL地址
~~~
DOMString entry.toLocalURL();
~~~
### 参数：
### 返回值：
DOMString : 格式为本地路径URL
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
// Get the local URL for this file
var fileURL = entry.toLocalURL();
plus.console.log(dirURL);
~~~
# [toRemoteURL]()
获取文件路径转换为网络路径URL地址
~~~
DOMString entry.toRemoteURL();
~~~
### 说明：
URL地址格式为以“http://localhost:13131/”开头的网络路径。
### 参数：
无
### 返回值：
DOMString : 网络格式路径URL
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
// Get the remote URL for this file
var fileURL = entry.toRemoteURL();
plus.console.log(dirURL);
~~~
# [remove]()
删除文件
~~~
entry.remove( succesCB, errorCB );
~~~
### 说明：
删除文件成功通过succesCB回调返回，失败则通过errorCB返回。
### 参数：
- succesCB: *( [EntrySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.EntrySuccessCallback) ) 可选 *删除文件成功的回调函数
回调函数中无参数。
- errorCB: *( [FileErrorCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileErrorCallback) ) 可选 *删除文件失败的回调函数
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
// remove this file
entry.remove( function ( entry ) {
plus.console.log( "Remove succeeded" );
}, function ( e ) {
alert( e.message );
} );
~~~
# [getParent]()
获取文件所属的父目录
~~~
entry.getParent( succesCB, errorCB );
~~~
### 说明：
获取父目录成功通过succesCB回调返回，失败则通过errorCB返回。
### 参数：
- succesCB: *( [EntrySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.EntrySuccessCallback) ) 可选 *获取父目录成功的回调函数
- errorCB: *( [FileErrorCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileErrorCallback) ) 可选 *获取父目录失败的回调函数
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
// Get the parent DirectoryEntry
entry.getParent( function ( entry ) {
plus.console.log( "Parent Name: " + entry.name );
}, function ( e ) {
alert( e.message );
} );
~~~
# [createWriter]()
获取文件关联的写文件操作对象FileWriter
~~~
entry.createWriter( succesCB, errorCB );
~~~
### 说明：
获取写文件操作对象成功通过succesCB回调返回，失败则通过errorCB返回。
### 参数：
- succesCB: *( [FileWriterSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileWriterSuccessCallback) ) 可选 *获取写文件操作对象成功的回调函数
- errorCB: *( [FileErrorCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileErrorCallback) ) 可选 *获取写文件操作对象失败的回调函数
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
// create a FileWriter to write to the file
entry.createWriter( function ( writer ) {
// Write data to file.
writer.write( "Data " );
}, function ( e ) {
alert( e.message );
} );
~~~
# [file]()
获取文件数据对象
~~~
entry.file( succesCB, errorCB );
~~~
### 说明：
获取文件数据对象成功通过succesCB回调返回，失败则通过errorCB返回。
### 参数：
- succesCB: *( [FileSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileSuccessCallback) ) 可选 *获取文件数据对象成功的回调函数
- errorCB: *( [FileErrorCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileErrorCallback) ) 可选 *获取文件数据对象失败的回调函数
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
### 示例：
~~~
// Get the parent DirectoryEntry
entry.file( function ( file ) {
plus.console.log("File size: " + file.size);
}, function ( e ) {
alert( e.message );
} );
~~~
# [FileReader]()
文件系统中的读取文件对象，用于获取文件的内容
### 说明：
FileReader对象是从设备文件系统读取文件FileReader对象是从设备文件系统读取文件的一种方式，文件以文本或者Base64编码的字符串形式读出来。 用户注册自己的事件监听器来接收loadstart、progress、load、loadend、error和abort事件。
### 构造：
- [FileReader](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileReader.FileReader): 创建读取文件对象
### 常量：
- [EMPTY](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileReader.EMPTY): 值为0，开始读取文件状态
- [LOADING](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileReader.LOADING): 值为1，正在读取文件状态
- [DONE](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileReader.DONE): 值为2，读文件操作完成状态
### 属性：
- [readyState](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileReader.readyState): 当前读取文件所处的状态
- [result](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileReader.result): 已读取文件的内容
- [error](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileReader.error): 文件操作错误代码
### 方法：
- [abort](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileReader.abort): 终止文件读取操作
- [readAsDataURL](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileReader.readAsDataURL): 以URL编码格式读取文件数据内容
- [readAsText](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileReader.readAsText): 以文本格式读取文件数据内容
### 事件：
- [onloadstart](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileReader.onloadstart): 读取文件开始时的回调函数
- [onprogress](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileReader.onprogress): 读取文件过程中的回调函数
- [onload](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileReader.onload): 读取文件成功完成的回调函数
- [onabort](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileReader.onabort): 取消读取文件时的回调函数
- [onerror](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileReader.onerror): 文件读取操作失败时调用的回调函数
- [onloadend](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileReader.onloadend): 文件读取操作完成时的回调函数
# [FileReader]()
创建读取文件对象
### 说明：
创建读取文件对象
### 参数：
无
### 返回值：
[FileReader](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileReader) :
# [EMPTY]()
值为0，开始读取文件状态
### 说明：
Number 类型
# [LOADING]()
值为1，正在读取文件状态
### 说明：
Number 类型
# [DONE]()
值为2，读文件操作完成状态
### 说明：
Number 类型
# [readyState]()
当前读取文件所处的状态
### 说明：
Number 类型 只读属性
可取上面定义的常量值，EMPTY（0）、LOADING（1）、DONE（2）。
# [result]()
已读取文件的内容
### 说明：
DOMString 类型 只读属性
# [error]()
文件操作错误代码
### 说明：
Number 类型 只读属性
# [abort]()
终止文件读取操作
~~~
reader.abort();
~~~
### 说明：
读取文件操作开始后，可通过此方法取消读取文件。 调用此方法后将触发文件读取对象的onabort事件。
### 参数：
### 返回值：
void : 无
### 示例：
~~~
// Read data from file
var reader = null;
entry.file( function ( file ) {
reader = new plus.io.FileReader();
reader.onloadend = function ( e ) {
plus.console.log( "Read success" );
// Get data
plus.console.log( e.target.result );
};
reader.readAsText( file );
}, function ( e ) {
alert( e.message );
} );
// ......
// Abort read data from file
reader.abort();
~~~
# [readAsDataURL]()
以URL编码格式读取文件数据内容
~~~
reader.readAsDataURL( file, encoding );
~~~
### 说明：
读取文件的数据内容，并将数据内容进行URL编码。
### 参数：
- file: *( [File](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.File) ) 必选 *要读取的文件数据对象
- encoding : *( DOMString ) 可选 *读取文件数据内容的字符编码格式
目前仅支持UTF-8编码格式。
### 返回值：
void : 无
### 示例：
~~~
// Read data from file
var reader = null;
entry.file( function ( file ) {
reader = new plus.io.FileReader();
reader.onloadend = function ( e ) {
plus.console.log( "Read success" );
// Get data
plus.console.log( e.target.result );
};
reader.readAsDataURL( file );
}, function ( e ) {
alert( e.message );
} );
~~~
# [readAsText]()
以文本格式读取文件数据内容
~~~
reader.readAsText( file, encoding );
~~~
### 说明：
读取文件的数据内容。
### 参数：
- file: *( [File](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.File) ) 必选 *要读取的文件数据对象
- encoding : *( DOMString ) 可选 *读取文件数据内容的字符编码格式
目前仅支持UTF-8编码格式。
### 返回值：
void : 无
### 示例：
~~~
// Read data from file
var reader = null;
entry.file( function ( file ) {
reader = new plus.io.FileReader();
reader.onloadend = function ( e ) {
plus.console.log( "Read success" );
// Get data
plus.console.log( e.target.result );
};
reader.readAsText( file );
}, function ( e ) {
alert( e.message );
} );
~~~
# [onloadstart]()
读取文件开始时的回调函数
### 说明：
[FileEventCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEventCallback) 类型
# [onprogress]()
读取文件过程中的回调函数
### 说明：
[FileEventCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEventCallback) 类型
用于获取文件读取进度。
# [onload]()
读取文件成功完成的回调函数
### 说明：
[FileEventCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEventCallback) 类型
# [onabort]()
取消读取文件时的回调函数
### 说明：
[FileEventCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEventCallback) 类型
# [onerror]()
文件读取操作失败时调用的回调函数
### 说明：
[FileEventCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEventCallback) 类型
# [onloadend]()
文件读取操作完成时的回调函数
### 说明：
[FileEventCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEventCallback) 类型
不管成功或失败都会触发。
# [FileWriter]()
文件系统中的写文件对象，用于写入文件内容
### 说明：
FileWriter对象是从设备文件系统写入文件FileWriter对象是从设备文件系统写入文件的一种方式，用户注册自己的事件监听器来接收writestart、progress、write、writeend、error和abort事件。 一个FileWriter对象是为单个文件的操作而创建。你可以使用该对象多次对相应文件进行写入操作。FileWriter维护该文件的指针位置及长度属性，这样你就可以寻找和写入文件的任何地方。 默认情况下，FileWriter从文件的开头开始写入（将覆盖现有数据）。FileWriter对象的seek方法可设置文件操作指定位置，如fw.seek(fw.length-1)写入操作就会从文件的末尾开始。
### 常量：
- [INIT](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileWriter.INIT): 值为0，写文件初始化状态
- [WRITING](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileWriter.WRITING): 值为1，正在写入文件状态
- [DONE](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileWriter.DONE): 值为2，写文件操作完成状态
### 属性：
- [readyState](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileWriter.readyState): 当前写入文件所处的状态
- [length](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileWriter.length): 文件当前的长度，单位为字节
- [position](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileWriter.position): 文件当前操作的指针位置
- [error](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileWriter.error): 文件写入操作错误代码
### 方法：
- [abort](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileWriter.abort): 终止文件写入操作
- [seek](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileWriter.seek): 定位文件操作位置
- [truncate](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileWriter.truncate): 按照指定长度截断文件
- [write](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileWriter.write): 向文件中写入数据
### 事件：
- [onwritestart](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileWriter.onwritestart): 写入文件开始时的回调函数
- [onprogress](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileWriter.onprogress): 写入文件过程中的回调函数
- [onwrite](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileWriter.onwrite): 写入文件成功完成的回调函数
- [onabort](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileWriter.onabort): 取消写入文件时的回调函数
- [onerror](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileWriter.onerror): 文件写入操作失败时调用的回调函数
- [onwriteend](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileWriter.onwriteend): 文件写入操作完成时的回调函数
# [INIT]()
值为0，写文件初始化状态
### 说明：
Number 类型
# [WRITING]()
值为1，正在写入文件状态
### 说明：
Number 类型
# [DONE]()
值为2，写文件操作完成状态
### 说明：
Number 类型
# [readyState]()
当前写入文件所处的状态
### 说明：
Number 类型 只读属性
可取上面定义的常量值，INIT(0)、WRITING（1）、DONE（2）。
# [length]()
文件当前的长度，单位为字节
### 说明：
Number 类型 只读属性
# [position]()
文件当前操作的指针位置
### 说明：
Number 类型 只读属性
# [error]()
文件写入操作错误代码
### 说明：
Number 类型 只读属性
# [abort]()
终止文件写入操作
~~~
writer.abort();
~~~
### 说明：
写入文件数据操作开始后，可通过此方法取消写入文件数据操作。 调用此方法后将触发文件写入对象的onabort事件。
### 参数：
### 返回值：
void : 无
### 示例：
~~~
// Write data to file
var w = null;
entry.createWriter( function ( writer ) {
w = writer;
// fast forwards file pointer to end of file
writer.seek( writer.length-1 );
}, function ( e ) {
alert( e.message );
} );
// ......
// Abort write data to file
w.abort();
~~~
# [seek]()
定位文件操作位置
~~~
writer.seek( position );
~~~
### 说明：
定位文件的操作位置，有效值为0到文件的总长度减1。 0表示文件的起始位置。
### 参数：
- position: *( Number ) 必选 *要定位到的位置
### 返回值：
void : 无
### 示例：
~~~
// Write data to file
var w = null;
entry.createWriter( function ( writer ) {
w = writer;
// fast forwards file pointer to end of file
writer.seek( writer.length-1 );
}, function ( e ) {
alert( e.message );
} );
~~~
# [truncate]()
按照指定长度截断文件
~~~
writer.truncate( length );
~~~
### 说明：
从文件当前定位的位置开始，按照指定长度截断文件。
### 参数：
- length : *( Number ) 必选 *截断后的文件长度
### 返回值：
void : 无
### 示例：
~~~
// Truncate file
entry.createWriter( function ( writer ) {
// Truncate file data length to 100
writer.truncate( 100 );
}, function ( e ) {
alert( e.message );
} );
~~~
# [write]()
向文件中写入数据
~~~
writer.write( data );
~~~
### 说明：
从文件当前定位的位置开始，写入数据到文件中。 如果文件中已经存在数据，新写入的数据将覆盖已有数据。
### 参数：
- data : *( DOMString ) 必选 *要写入的数据内容
### 返回值：
void : 无
### 示例：
~~~
// Write data to file
entry.createWriter( function ( writer ) {
writer.onwrite = function ( e ) {
plus.console.log( "Write data success!" );
};
// Write data to the end of file.
writer.seek( writer.length );
writer.write( "New data!" );
}, function ( e ) {
alert( e.message );
} );
~~~
# [onwritestart]()
写入文件开始时的回调函数
### 说明：
[FileEventCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEventCallback) 类型
# [onprogress]()
写入文件过程中的回调函数
### 说明：
[FileEventCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEventCallback) 类型
用于获取文件读取进度。
# [onwrite]()
写入文件成功完成的回调函数
### 说明：
[FileEventCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEventCallback) 类型
# [onabort]()
取消写入文件时的回调函数
### 说明：
[FileEventCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEventCallback) 类型
# [onerror]()
文件写入操作失败时调用的回调函数
### 说明：
[FileEventCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEventCallback) 类型
# [onwriteend]()
文件写入操作完成时的回调函数
### 说明：
[FileEventCallback](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEventCallback) 类型
不管成功或失败都会触发。
# [FileSystem]()
文件系统对象，用于管理特定本地文件目录
### 说明：
文件系统对象表示一个应用可访问的根目录。name属性用于标识此根目录的名称，与LocalFileSystem中的文件系统类型一一对应。root属性为文件目录对象，用于实际操作文件系统，参考DirectoryEntry。
### 属性：
- [name](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileSystem.name): 文件系统的名称
- [root](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileSystem.root): 文件系统的根目录
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>File Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
plus.io.requestFileSystem( plus.io.PRIVATE_WWW, function( fs ) {
// 可通过fs进行文件操作
alert( "File system name: " + fs.name );
// 通过fs.root获取DirectoryEntry对象进行操作
// fs.root
}, function ( e ) {
alert( "Request file system failed: " + e.message );
} );
}
</script>
</head>
<body>
Request file system
</body>
</html>
~~~
# [name]()
文件系统的名称
### 说明：
DOMString 类型 只读属性
值为文件系统类型常量值字符串，如“PRIVATE_WWW”、“PRIVATE_DOCUMENTS”。
# [root]()
文件系统的根目录
### 说明：
[DirectoryEntry](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry) 类型 只读属性
# [Flags]()
JSON对象，获取文件操作的参数
### 属性：
- create: *(Boolean 类型 )*是否创建对象标记
指示如果文件或目录不存在时是否进行创建，默认值为false。
- exclusive: *(Boolean 类型 )*反向操作标记
其本身没有任何效果，需与create属性值设置为true时一起使用，如果目标文件或目录已经存在则会导致文件或目录打开失败，默认值为false。
# [Metadata]()
JSON对象，保存文件或目录的状态信息对象
### 说明：
可通过DirectoryEntry或FileEntry对象的getMetaData方法获取
### 属性：
- modificationTime: *(Date 类型 )*文件或目录的最后修改时间
- size: *(Number 类型 )*文件的大小
若获取的是目录对象的属性则值为0。
- directoryCount: *(Number 类型 )*包含的子目录数
若自身是文件则其值为0。
- fileCount: *(Number 类型 )*目录的文件数
若自身是文件则其值为0。
# [FileEvent]()
文件或目录操作事件对象
### 说明：
所有文件或目录操作事件回调函数中都创建该对象的实例。 该对象从DOMEvent继承而来，可通过该其target属性获取事件触发的文件或目录操作对象。
### 属性：
- target: *([DirectoryEntry](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry) 类型 )*文件或目录操作对象
在不同的回调中指向的对象不同，可指向的对象包括：FileEntry、DirectoryEntry、FileReader、FileWriter。
# [URLType]()
文件路径类型
### 说明：
在文件系统中的文件路径需转换成URL格式，已方便runtime快速加载。
# [RelativeURL]()
相对路径URL
### 说明：
只能在扩展API中使用，相对于基座提供的特定目录，以“_”开头。
### 常量：
- "_www": *(DOMString 类型 )*应用资源目录
保存应用的所有html、css、js等资源文件，与文件系统中根目录PRIVATE_WWW，如“_www/res/icon.png”。
- "_doc": *(DOMString 类型 )*应用私有文档目录
用于保存应用运行期业务逻辑数据，与文件系统中根目录PRIVATE_DOCUMENTS，如“_doc/userdata.xml”。
- "_documents": *(DOMString 类型 )*程序公用文档目录
用于保存程序中各应用间可共享文件的目录，与文件系统中根目录PUBLIC_DOCUMENTS，如“_document/share.doc”。
- "_downloads": *(DOMString 类型 )*程序公用下载目录
用于保存程序下载文件的目录，与文件系统中根目录PUBLIC_DOWNLOADS，如“_download/mydoc.doc”。
# [LocalURL]()
本地路径URL
### 说明：
可在html页面中直接访问本地资源，以“file:///”开头，后面跟随系统的绝对路径。 如示例：“file:///D:/res/hello.html”。
# [RemoteURL]()
网络路径URL
### 说明：
可在html页面中以网络资源模式访问本地资源，以“http://”开头，后面跟随相对路径。 如示例：“http://localhost:13131/_www/res/icon.png”，其中“_www”字段可支持类型与相对路径URL一致。
# [FileEventCallback]()
文件事件回调
~~~
void onEvent( event ) {
// Event code.
}
~~~
### 说明：
文件或目录操作回调事件。 通常在FileReader和FileWriter对象的事件函数中触发。
### 参数：
- event: *( [FileEvent](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileEvent) ) 必选 *文件事件对象
### 返回值：
void : 无
# [FileSystemSuccessCallback]()
请求文件系统成功的回调函数
~~~
void onSuccess( fs ) {
// File System operate code.
}
~~~
### 参数：
- fs: *( [FileSystem](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileSystem) ) 必选 *请求到的文件系统对象
### 返回值：
void : 无
# [FileResolveSuccessCallback]()
通过URL参数获取目录或文件对象成功的回调函数
~~~
void onSuccess( entry ) {
// File or Direcory entry operate code.
}
~~~
### 参数：
- entry: *( [DirectoryEntry](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry) ) 必选 *请求到的目录或文件对象
可指向文件或目录对象（DirectoryEntry|FileEntry）。
### 返回值：
void : 无
# [MetadataSuccessCallback]()
获取文件或目录状态信息成功的回调函数
~~~
void onSuccess( metadata ) {
// Metadata code.
}
~~~
### 参数：
- metadata: *( [Metadata](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.Metadata) ) 必选 *文件或目录的状态信息
### 返回值：
void : 无
# [EntrySuccessCallback]()
操作文件或目录对象成功的回调函数
~~~
void onSuccess( entry ) {
// Entry code.
}
~~~
### 参数：
- entry: *( [DirectoryEntry](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry) ) 必选 *文件或目录对象的引用
可指向文件或目录对象（DirectoryEntry|FileEntry）。
### 返回值：
void : 无
# [EntrysSuccessCallback]()
操作文件或目录对象数组成功的回调函数
~~~
void onSuccess( entrys ) {
// Entrys code.
}
~~~
### 参数：
- entrys: *( [DirectoryEntry](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.DirectoryEntry) ) 必选 *文件或目录对象数组
可指向文件或目录对象数组（DirectoryEntry[]|FileEntry[]）。
### 返回值：
void : 无
# [FileWriterSuccessCallback]()
写文件操作成功的回调函数
~~~
void onSuccess( writer ) {
// FileWriter code.
}
~~~
### 参数：
- writer: *( [FileWriter](http://www.dcloud.io/docs/api/zh_cn/io.shtml#plus.io.FileWriter) ) 必选 *写文件对象的引用
### 返回值：
void : 无
# [FileSuccessCallback]()
文件操作成功的回调函数
~~~
void onSuccess( file ) {
// file code.
}
~~~
### 参数：
- file: *( File ) 必选 *文件数据对象的引用
### 返回值：
void : 无
# [FileErrorCallback]()
文件操作失败的回调函数
~~~
void onError( error ) {
// Error code.
}
~~~
### 参数：
- error: *( DOMException ) 必选 *文件操作失败的信息
### 返回值：
void : 无
- API参考
- Accelerometer
- Audio
- Camera
- Contacts
- Device
- Downloader
- Events
- Gallery
- Geolocation
- IO
- Key
- Messaging
- NativeUI
- Navigator
- Orientation
- Proximity
- SplashScreen
- Storage
- UI
- Uploader
- InterfaceOrientation
- Runtime
- WebView
- XMLHttpRequest
- Zip
- Plugins
- Barcode
- Maps
- Payment
- Push
- Share
- Speech
- Statistic
- Native.js
- Android
- iOS