HTML5+规范：IO(管理本地文件系统)

程序员文章站 2022-03-12 20:24:02

IO模块管理本地文件系统，用于对文件系统的目录浏览、文件的读取、文件的写入等操作。通过plus.io可获取文件系统管理对象。 PRIVATE_WWW: 应用运行资源目录常量 P...

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(https://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/ａ.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

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地址格式为以“https://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+ (支持)

示例：

（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 : 无

示例：

文件系统中的文件数据对象，用于获取文件的数据

3.1属性

size: 文件数据对象的数据大小，单位为字节

type: 文件数据对象MIME类型

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

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地址格式为以“https://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 );
} );

onwritestart: 写入文件开始时的回调函数

onprogress: 写入文件过程中的回调函数

onwrite: 写入文件成功完成的回调函数

onabort: 取消写入文件时的回调函数

onerror: 文件写入操作失败时调用的回调函数

onwriteend: 文件写入操作完成时的回调函数

7、FileSystem

文件系统对象，用于管理特定本地文件目录

说明：文件系统对象表示一个应用可访问的根目录。name属性用于标识此根目录的名称，与LocalFileSystem中的文件系统类型一一对应。root属性为文件目录对象，用于实际操作文件系统，参考DirectoryEntry。

7.1、属性

root: 文件系统的根目录

示例：

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页面中以网络资源模式访问本地资源，以“https://”开头，后面跟随相对路径。如示例：“https://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 : 无

上一篇： HTML5--web存储

下一篇：荐 Linux实验：安装和配置Apache服务

HTML5+规范：IO(管理本地文件系统)

HTML5+规范：navigator(管理浏览器运行环境信息)

HTML5+规范：Geolocation(管理设备位置信息)

HTML5+规范：gallery(管理系统相册)

HTML5+规范：Uploader(管理网络上传任务)

HTML5+规范：device(管理设备信息)

HTML5+规范：Downloader(管理网络文件下载任务)