h5 io文件系统

IO模块管理本地文件系统,用于对文件系统的目录浏览、文件的读取、文件的写入等操作。通过plus.io可获取文件系统管理对象。
PRIVATE_WWW: 应用运行资源目录常量
PRIVATE_DOC: 应用私有文档目录常量
PUBLIC_DOCUMENTS: 程序公用文档目录常量
PUBLIC_DOWNLOADS: 程序公用下载目录常量

一、常量
1、PRIVATE_WWW
应用运行资源目录常量:plus.io.PRIVATE_WWW;
说明:Number类型,本地文件系统常量,Number类型,固定值1。应用运行资源目录,仅本应用可访问。为了确保应用资源的安全性,此目录只可读。
平台支持
Android - ALL (支持): Android平台应用资源是放到apk的assets目录中,安装到设备后无法枚举,为了能够正常枚举访问此目录,需要将应用设置为释放资源模式(在manifest.json中将runmode值设置为liberate),这样程序在第一次运行时将资源释放到sdcard中。 通常在设备上的目录为“/sdcard/Android/data/%PACKAGENAME%/apps/%APPID%/www”,其中%PACKAGENAME%是程序的包名、%APPID%是应用的标识,如“/sdcard/Android/data/io.dcloud.HelloH5/apps/HelloH5/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>  

2、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>  

3、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>  

4、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: 请求本地文件系统对象
resolveLocalFileSystemURL: 通过URL参数获取目录对象或文件对象
convertLocalFileSystemURL: 将本地URL路径转换成平台绝对路径
convertAbsoluteFileSystem: 将平台绝对路径转换成本地URL路径
1、requestFileSystem
请求本地文件系统对象:void plus.io.requestFileSystem( type, succesCB, errorCB )
说明:获取指定的文件系统,可通过type指定获取文件系统的类型。 获取指定的文件系统对象成功通过succesCB回调返回,失败则通过errorCB返回。
参数:
(1)、type: ( Number ) 必选 本地文件系统常量。可取plus.io下的常量,如plus.io.PRIVATE_DOC、plus.io.PUBLIC_DOCUMENTS等。
(2)、succesCB: ( FileSystemSuccessCallback ) 必选 请求文件系统成功的回调。
(3)、errorCB: ( 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进行文件操作  
alert( "Request file system success!" );  
}, function ( e ) {  
alert( "Request file system failed: " + e.message );  
} );  
}  
</script>  
</head>  
<body>  
Request file system  
</body>  
</html>  

2、resolveLocalFileSystemURL
通过URL参数获取目录对象或文件对象void plus.io.resolveLocalFileSystemURL( url, succesCB, errorCB );
说明:快速获取指定的目录或文件操作对象,如通过URL值“_www/test.html”可直接获取文件操作对象。 url值可支持相对路径URL、本地路径URL、网络路径URL(http://localhost:13131/开头)。 获取指定的文件或目录操作对象成功通过succesCB回调返回,如果指定URL路径或文件不存在则失败通过errorCB回调返回。
参数:
(1)、url : ( DOMString ) 必选 要操作文件或目录的URL地址
(2)、succesCB: ( FileResolveSuccessCallback ) 必选 获取操作文件或目录对象成功的回调函数
(3)、errorCB: ( 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.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>  

3、convertLocalFileSystemURL
将本地URL路径转换成平台绝对路径:String plus.io.convertLocalFileSystemURL( url );
说明:绝对路径符合各平台文件路径格式,通常用于Native.JS调用系统原生文件操作API,也可以在前面添加“file://”后在html页面中直接使用。
参数:url: ( String ) 必选 要转换的文件或目录URL地址,URL地址必须是合法的路径,如果地址不合法则返回null。
返回值:String : 转换后在平台路径,在不同平台或者不同设备返回的值可能存在差异,如输入url为“_doc/a.png”: Android平台转换后的路径为“/storage/sdcard0/Android/data/io.dcloud.HBuilder/.HBuilder/apps/HBuilder/doc/a.png”; 在iOS平台转换后的路径为“/var/mobile/Containers/Data/Application/757966CF-345C-4348-B07F-EEF83CF9A369/Library/Pandora/apps/HBuilder/doc/a.png”。
示例:

<!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(){  
var url="_www/index.html";  
var path=plus.io.convertLocalFileSystemURL(url);  
alert(path);  
}  
</script>  
</head>  
<body>  
convertLocalFileSystemURL  
</body>  
</html>  

4、convertAbsoluteFileSystem
将平台绝对路径转换成本地URL路径:String plus.io.convertAbsoluteFileSystem( path );
说明:绝对路径符合各平台文件路径格式,转换后变成RelativeURL类型格式。 功能与convertLocalFileSystemURL方法相反,将绝对路径转换成相对路径。
参数:path: ( String ) 必选 要转换的平台绝对路径,绝对路径必须是合法的路径,如果绝对路径不合法则返回null。
返回值:DOMString : 转换后本地URL路径
示例:

<!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(){  
var url="_www/index.html";  
var path=plus.io.convertLocalFileSystemURL(url);  
var newurl = plus.io.convertAbsoluteFileSystem(path);  
alert(newurl); // 显示值为“_www/index.html”  
}  
</script>  
</head>  
<body>  
convertAbsoluteFileSystem  
</body>  
</html>  

三、对象
DirectoryEntry: 文件系统中的目录对象,用于管理特定的本地目录
DirectoryReader: 读取目录信息对象,用于获取目录中包含的文件及子目录
File: 文件系统中的文件数据对象,用于获取文件的数据
FileEntry: 文件系统中的文件对象,用于管理特定的本地文件
FileReader: 文件系统中的读取文件对象,用于获取文件的内容
FileWriter: 文件系统中的写文件对象,用于写入文件内容
FileSystem: 文件系统对象,用于管理特定本地文件目录
Flags: JSON对象,获取文件操作的参数
Metadata: JSON对象,保存文件或目录的状态信息对象
FileEvent: 文件或目录操作事件对象
URLType: 文件路径类型
RelativeURL: 相对路径URL
LocalURL: 本地路径URL
RemoteURL: 网络路径URL
1、DirectoryEntry
文件系统中的目录对象,用于管理特定的本地目录
1.1、属性
isFile: 操作对象的是否为文件,DirectoryEntry对象固定其值为false
isDirectory: 操作对象是否为目录,DirectoryEntry对象固定其值为true
name: 目录操作对象的名称,不包括路径
fullPath: 目录操作对象的完整路径,文件系统的绝对路径
fileSystem: 文件操作对象所属的文件系统对象,参考FileSystem
1.2、方法
(1)、getMetadata: 获取目录的属性
entry.getMetadata( successCB, errorCB, recursive );
说明:用于获取文件或目录的属性信息。 获取属性信息成功通过succesCB回调返回,失败则通过errorCB返回。
参数:
succesCB: ( MetadataSuccessCallback ) 必选 获取文件或目录属性信息成功的回调。
errorCB: ( 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 );  
} );  

(2)、moveTo: 移动目录
entry.moveTo( parent, newName, succesCB, errorCB );
说明:以下情况移动目录将会导致失败: 将父目录移动到子目录中; 要移动到的目标目录无效; 要移动到的目标路径被文件占用; 要移动到的目标目录已经存在并且不为空。 移动目录成功通过succesCB回调返回,失败则通过errorCB返回。
参数:
parent: ( DirectoryEntry ) 必选 要移动到的目标目录
newName: ( DOMString ) 可选 移动后的目录名称,默认为原始目录名称
succesCB: ( EntrySuccessCallback ) 可选 移动目录成功的回调函数,回调函数中的参数保存新的目录对象。
errorCB: ( 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 );  
} );  
}  

(3)、copyTo: 拷贝目录
entry.copyTo( parent, newName, succesCB, errorCB );
说明:以下情况拷贝目录将会导致失败: 将父目录拷贝到子目录中; 要拷贝到的目标目录无效; 要拷贝到的目标路径被文件占用; 要拷贝到的目标目录已经存在并且不为空。 拷贝目录成功通过succesCB回调返回,失败则通过errorCB返回。
参数:
parent: ( DirectoryEntry ) 必选 要拷贝到的目标目录
newName: ( DOMString ) 可选 拷贝后的目录名称,默认为原始目录名称
succesCB: ( EntrySuccessCallback ) 可选 拷贝目录成功的回调函数
回调函数中的参数保存新的目录对象。
errorCB: ( 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 );  
} );  
}  

(4)、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);  

(5)、toLocalURL: 获取目录路径转换为本地路径URL地址
DOMString entry.toLocalURL();
返回值:DOMString : 格式为本地路径URL
平台支持:Android - 2.2+ (支持)、iOS - 4.3+ (支持)
示例:

// Get the local URL for this directory  
var dirURL = entry.toLocalURL();  

(6)、toRemoteURL: 获取目录路径转换为网络路径URL地址
OMString 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);  

(7)、remove: 删除目录
entry.remove( succesCB, errorCB );
说明:以下情况删除目录将会导致失败: 目录中存在文件; 删除根目录; 删除目录成功通过succesCB回调返回,失败则通过errorCB返回。
参数:
succesCB: ( EntrySuccessCallback ) 可选 删除目录成功的回调函数
回调函数中无参数。
errorCB: ( 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 );  
} );  

(8)、getParent: 获取目录所属的父目录
entry.getParent( succesCB, errorCB );
说明:获取父目录成功通过succesCB回调返回,失败则通过errorCB返回。
参数:
succesCB: ( EntrySuccessCallback ) 可选 获取父目录成功的回调函数
errorCB: ( 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 );  
} );  

(9)、createReader: 创建目录读取对象
DirectoryReader entry.createReader();
说明:创建一个目录读取对象,用户读取目下的文件及子目录。
返回值:DirectoryReader : 目录读取对象
平台支持:Android - 2.2+ (支持)、iOS - 4.3+ (支持)
示例:

// create a directory reader  
var directoryReader = entry.createReader();  

(10)、getDirectory: 创建或打开子目录
entry.getDirectory( path, flag, succesCB, errorCB );
说明:创建或打开当前目录指定的目录。 创建或打开目录操作成功通过succesCB回调返回,失败则通过errorCB返回。
参数:
path: ( DOMString ) 必选 要操作目录相对于当前目录的地址
flag: ( Flags ) 可选 要操作文件或目录的参数
succesCB: ( EntrySuccessCallback ) 可选 创建或打开目录成功的回调函数
errorCB: ( 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 );  
} );  

(11)、getFile: 创建或打开文件
entry.getFile( path, flag, succesCB, errorCB );
说明:创建或打开当前目录下指定的文件。 创建或打开文件操作对象成功通过succesCB回调返回,失败则通过errorCB返回。
参数:
path: ( DOMString ) 必选 要操作文件相对于当前目录的地址
flag: ( Flags ) 可选 要操作文件或目录的参数
succesCB: ( EntrySuccessCallback ) 可选 创建或打开文件成功的回调函数
errorCB: ( 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>  

(12)、removeRecursively: 递归删除目录
entry.removeRecursively( succesCB, errorCB );
说明:删除目录将会删除其下的所有文件及子目录 不能删除根目录,如果操作删除根目录将会删除目录下的文件及子目录,不会删除根目录自身。 删除目录成功通过succesCB回调返回,失败则通过errorCB返回。
参数:
succesCB: ( EntrySuccessCallback ) 可选 删除目录成功的回调函数
回调函数中无参数。
errorCB: ( 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 );  
} );  

2、DirectoryReader
读取目录信息对象,用于获取目录中包含的文件及子目录
2.1方法
readEntries: 获取当前目录中的所有文件和子目录
directoryReader.readEntries( succesCB, errorCB );
说明:获取当前目录下的所有文件和子目录。 获取操作成功通过succesCB回调返回,失败则通过errorCB返回。
参数:
succesCB: ( EntrySuccessCallback ) 可选 获取成功的回调函数
errorCB: ( 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>  

3、File
文件系统中的文件数据对象,用于获取文件的数据
3.1属性
size: 文件数据对象的数据大小,单位为字节
type: 文件数据对象MIME类型
name: 文件数据对象的名称,不包括路径
lastModifiedDate: 文件对象的最后修改时间
3.2方法
(1)、slice: 获取文件指定的数据内容
file.slice( start, end );
说明:获取文件指定的数据内容,其中end必须大于start。
参数:
start: ( Number ) 可选 获取文件数据的起始位置
end: ( Number ) 可选 获取文件数据的结束位置
返回值:File : 指定数据内容的文件对象
示例:

var slice1 = file.slice(100, 400);  
var slice2 = slice1.slice(20, 35);  
var slice3 = file.slice(120, 135);  
// slice2 and slice3 are equivalent.  

(2)、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();  

4、FileEntry
文件系统中的文件对象,用于管理特定的本地文件
4.1属性:
isFile: 文件操作对象的是否为文件,FileEntry对象固定其值为true
isDirectory: 文件操作对象是否为目录,FileEntry对象固定其值为false
name: 文件操作对象的名称,不包括路径
fullPath: 文件操作对象的完整路径,文件系统的绝对路径
fileSystem: 文件操作对象所属的文件系统对象,参考FileSystem
4.2方法:
(1)、getMetadata: 获取文件的属性信息
entry.getMetadata( successCB, errorCB );
说明:用于获取文件的属性信息。 获取属性信息成功通过succesCB回调返回,失败则通过errorCB返回。

参数:
succesCB: ( MetadataSuccessCallback ) 必选 获取文件属性信息成功的回调函数
errorCB: ( 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 );  
} );  

(2)、moveTo: 移动文件
entry.moveTo( parent, newName, succesCB, errorCB );
说明:以下情况移动目录将会导致失败: 要移动到的目标目录无效; 要移动到的目标路径被其它文件占用; 移动文件成功通过succesCB回调返回,失败则通过errorCB返回。
参数:
parent: ( DirectoryEntry ) 必选 要移动到的目标目录
newName: ( DOMString ) 可选 移动后的文件名称,默认为原始文件名称
succesCB: ( EntrySuccessCallback ) 可选 移动文件成功的回调函数
回调函数中的参数保存新的文件对象。
errorCB: ( 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 );  
} );  
}  

(3)、copyTo: 拷贝文件
entry.copyTo( parent, newName, succesCB, errorCB );
说明:以下情况拷贝文件将会导致失败: 要拷贝到的目标目录无效; 要拷贝到的目标路径被其它文件占用; 拷贝文件成功通过succesCB回调返回,失败则通过errorCB返回。
参数:
parent: ( DirectoryEntry ) 必选 要拷贝到的目标目录
newName: ( DOMString ) 可选 拷贝后的文件名称,默认为原始文件名称
succesCB: ( EntrySuccessCallback ) 可选 拷贝文件成功的回调函数
回调函数中的参数保存新的文件对象。
errorCB: ( 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 );  
} );  
}  

(4)、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);  

(5)、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);  

(6)、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);  

(7)、remove: 删除文件
entry.remove( succesCB, errorCB );
说明:删除文件成功通过succesCB回调返回,失败则通过errorCB返回。
参数:
succesCB: ( EntrySuccessCallback ) 可选 删除文件成功的回调函数
回调函数中无参数。
errorCB: ( 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 );  
} );  

(8)、getParent: 获取文件所属的父目录
entry.getParent( succesCB, errorCB );
说明:获取父目录成功通过succesCB回调返回,失败则通过errorCB返回。
参数:
succesCB: ( EntrySuccessCallback ) 可选 获取父目录成功的回调函数
errorCB: ( 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 );  
} );  

(9)、createWriter: 获取文件关联的写文件操作对象FileWriter
entry.createWriter( succesCB, errorCB );
说明:获取写文件操作对象成功通过succesCB回调返回,失败则通过errorCB返回。
参数:
succesCB: ( FileWriterSuccessCallback ) 可选 获取写文件操作对象成功的回调函数
errorCB: ( 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 );  
} );  

(10)、file: 获取文件数据对象
entry.file( succesCB, errorCB );
说明:获取文件数据对象成功通过succesCB回调返回,失败则通过errorCB返回。
参数:
succesCB: ( FileSuccessCallback ) 可选 获取文件数据对象成功的回调函数
errorCB: ( 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 );  
} );  

5、FileReader
文件系统中的读取文件对象,用于获取文件的内容
说明:FileReader对象是从设备文件系统读取文件,FileReader对象是从设备文件系统读取文件的一种方式,文件以文本或者Base64编码的字符串形式读出来。 用户注册自己的事件监听器来接收loadstart、progress、load、loadend、error和abort事件。
5.1、构造
FileReader: 创建读取文件对象
5.2、常量
EMPTY: 值为0,开始读取文件状态
LOADING: 值为1,正在读取文件状态
DONE: 值为2,读文件操作完成状态
5.3、属性
readyState: 当前读取文件所处的状态,可取上面定义的常量值,EMPTY(0)、LOADING(1)、DONE(2)。
result: 已读取文件的内容
error: 文件操作错误代码
5.4、方法
(1)、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();  

(2)、readAsDataURL: 以URL编码格式读取文件数据内容
reader.readAsDataURL( file, encoding );
说明:读取文件的数据内容,并将数据内容进行URL编码。
参数:
file: ( 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 );  
} );  

(3)、readAsText: 以文本格式读取文件数据内容
reader.readAsText( file, encoding );
说明:读取文件的数据内容。
参数:
file: ( 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 );  
} );  

5.5、事件
onloadstart: 读取文件开始时的回调函数
onprogress: 读取文件过程中的回调函数
onload: 读取文件成功完成的回调函数
onabort: 取消读取文件时的回调函数
onerror: 文件读取操作失败时调用的回调函数
onloadend: 文件读取操作完成时的回调函数
6、FileWriter
文件系统中的写文件对象,用于写入文件内容
说明:FileWriter对象是从设备文件系统写入文件,FileWriter对象是从设备文件系统写入文件的一种方式,用户注册自己的事件监听器来接收writestart、progress、write、writeend、error和abort事件。 一个FileWriter对象是为单个文件的操作而创建。你可以使用该对象多次对相应文件进行写入操作。FileWriter维护该文件的指针位置及长度属性,这样你就可以寻找和写入文件的任何地方。 默认情况下,FileWriter从文件的开头开始写入(将覆盖现有数据)。FileWriter对象的seek方法可设置文件操作指定位置,如fw.seek(fw.length-1)写入操作就会从文件的末尾开始。
6.1、常量
INIT: 值为0,写文件初始化状态
WRITING: 值为1,正在写入文件状态
DONE: 值为2,写文件操作完成状态
6.2、属性
readyState: 当前写入文件所处的状态
length: 文件当前的长度,单位为字节
position: 文件当前操作的指针位置
error: 文件写入操作错误代码
6.3方法
(1)、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();  

(2)、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 );  
} );  

(3)、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 );  
} );  

(4)、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 );  
} );  

6.4事件
onwritestart: 写入文件开始时的回调函数
onprogress: 写入文件过程中的回调函数
onwrite: 写入文件成功完成的回调函数
onabort: 取消写入文件时的回调函数
onerror: 文件写入操作失败时调用的回调函数
onwriteend: 文件写入操作完成时的回调函数
7、FileSystem
文件系统对象,用于管理特定本地文件目录
说明:文件系统对象表示一个应用可访问的根目录。name属性用于标识此根目录的名称,与LocalFileSystem中的文件系统类型一一对应。root属性为文件目录对象,用于实际操作文件系统,参考DirectoryEntry。
7.1、属性
name: 文件系统的名称,值为文件系统类型常量值字符串,如“PRIVATE_WWW”、“PRIVATE_DOCUMENTS”。
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>  

8、Flags
JSON对象,获取文件操作的参数
属性:
create: (Boolean 类型 )是否创建对象标记,指示如果文件或目录不存在时是否进行创建,默认值为false。
exclusive: (Boolean 类型 )反向操作标记,其本身没有任何效果,需与create属性值设置为true时一起使用,如果目标文件或目录已经存在则会导致文件或目录打开失败,默认值为false。
9、Metadata
JSON对象,保存文件或目录的状态信息对象
说明:可通过DirectoryEntry或FileEntry对象的getMetaData方法获取
属性:
modificationTime: (Date 类型 )文件或目录的最后修改时间
size: (Number 类型 )文件的大小,若获取的是目录对象的属性则值为0。

directoryCount: (Number 类型 )包含的子目录数,若自身是文件则其值为0。
fileCount: (Number 类型 )目录的文件数,若自身是文件则其值为0。
10、FileEvent
文件或目录操作事件对象
说明:所有文件或目录操作事件回调函数中都创建该对象的实例。该对象从DOMEvent继承而来,可通过该其target属性获取事件触发的文件或目录操作对象。
属性:
target: (DirectoryEntry 类型 )文件或目录操作对象,在不同的回调中指向的对象不同,可指向的对象包括:FileEntry、DirectoryEntry、FileReader、FileWriter。
11、URLType
文件路径类型
说明:在文件系统中的文件路径需转换成URL格式,已方便runtime快速加载。
12、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”。
13、LocalURL
本地路径URL
说明:可在html页面中直接访问本地资源,以“file:///”开头,后面跟随系统的绝对路径。 如示例:“file:///D:/res/hello.html”。
14、RemoteURL
网络路径URL
说明:可在html页面中以网络资源模式访问本地资源,以“http://”开头,后面跟随相对路径。 如示例:“http://localhost:13131/_www/res/icon.png”,其中“_www”字段可支持类型与相对路径URL一致。
四、回调方法
FileEventCallback: 文件事件回调
FileSystemSuccessCallback: 请求文件系统成功的回调函数
FileResolveSuccessCallback: 通过URL参数获取目录或文件对象成功的回调函数
MetadataSuccessCallback: 获取文件或目录状态信息成功的回调函数
EntrySuccessCallback: 操作文件或目录对象成功的回调函数
EntrysSuccessCallback: 操作文件或目录对象数组成功的回调函数
FileWriterSuccessCallback: 写文件操作成功的回调函数
FileSuccessCallback: 文件操作成功的回调函数
FileErrorCallback: 文件操作失败的回调函数
1、FileEventCallback
文件事件回调

void onEvent( event ) {
// Event code.
}

说明:文件或目录操作回调事件。 通常在FileReader和FileWriter对象的事件函数中触发。
参数:
event: ( FileEvent ) 必选 文件事件对象
返回值:void : 无
2、FileSystemSuccessCallback
请求文件系统成功的回调函数

void onSuccess( fs ) {
// File System operate code.
}

参数:
fs: ( FileSystem ) 必选请求到的文件系统对象
返回值:void : 无
3、FileResolveSuccessCallback
通过URL参数获取目录或文件对象成功的回调函数

void onSuccess( entry ) {
// File or Direcory entry operate code.
}

参数:entry: ( DirectoryEntry ) 必选请求到的目录或文件对象,可指向文件或目录对象(DirectoryEntry|FileEntry)。
返回值:void : 无
4、MetadataSuccessCallback
获取文件或目录状态信息成功的回调函数

void onSuccess( metadata ) {
// Metadata code.
}

参数:metadata: ( Metadata ) 必选 文件或目录的状态信息
返回值:void : 无
5、EntrySuccessCallback
操作文件或目录对象成功的回调函数

void onSuccess( entry ) {
// Entry code.
}

参数:entry: ( DirectoryEntry ) 必选文件或目录对象的引用
可指向文件或目录对象(DirectoryEntry|FileEntry)。
返回值:void : 无
6、EntrysSuccessCallback
操作文件或目录对象数组成功的回调函数

void onSuccess( entrys ) {
// Entrys code.
}

参数:entrys: ( DirectoryEntry ) 必选文件或目录对象数组,可指向文件或目录对象数组(DirectoryEntry[]|FileEntry[])。
返回值:void : 无
7、FileWriterSuccessCallback
写文件操作成功的回调函数

void onSuccess( writer ) {
// FileWriter code.
}

参数:writer: ( FileWriter ) 必选写文件对象的引用
返回值:void : 无
8、FileSuccessCallback
文件操作成功的回调函数

void onSuccess( file ) {
// file code.
}

参数:file: ( File ) 必选文件数据对象的引用
返回值:void : 无
9、FileErrorCallback
文件操作失败的回调函数

void onError( error ) {
// Error code.
}

参数:error: ( DOMException ) 必选文件操作失败的信息
返回值:void : 无

  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值