API Reference

Plugins

Native.js


io

IO模块管理本地文件系统,用于对文件系统的目录浏览、文件的读取、文件的写入等操作。通过plus.io可获取文件系统管理对象。

常量:

方法:

对象:

回调方法:

模块:

5+功能模块(permissions)


{
// ...
"permissions":{
	// ...
	"File": {
		"description": "文件系统"
	}
}
}
			

PRIVATE_WWW

应用运行资源目录常量


plus.io.PRIVATE_WWW;
				

说明:

Number 类型

本地文件系统常量,Number类型,固定值1。应用运行资源目录,仅本应用可访问。 为了确保应用资源的安全性,此目录只可读。

平台支持

示例:


<!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。应用私有文档目录,仅本应用可读写。

平台支持

示例:


<!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。程序公用文档目录,所有应用可读写。

平台支持

示例:


<!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。程序公用下载目录,所有应用可读写。

平台支持

示例:


<!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返回。

参数:

返回值:

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>
				

resolveLocalFileSystemURL

通过URL参数获取目录对象或文件对象


void plus.io.resolveLocalFileSystemURL( url, succesCB, errorCB );
				

说明:

快速获取指定的目录或文件操作对象,如通过URL值“_www/test.html”可直接获取文件操作对象。 url值可支持相对路径URL、本地路径URL、网络路径URL(http://localhost:13131/开头)。 获取指定的文件或目录操作对象成功通过succesCB回调返回,如果指定URL路径或文件不存在则失败通过errorCB回调返回。

参数:

返回值:

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>
				

convertLocalFileSystemURL

将本地URL路径转换成平台绝对路径


String plus.io.convertLocalFileSystemURL( url );
				

说明:

绝对路径符合各平台文件路径格式,通常用于Native.JS调用系统原生文件操作API,也可以在前面添加“file://”后在html页面中直接使用。

参数:

返回值:

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>
				

convertAbsoluteFileSystem

将平台绝对路径转换成本地URL路径


String plus.io.convertAbsoluteFileSystem( path );
				

说明:

绝对路径符合各平台文件路径格式,转换后变成RelativeURL类型格式。 功能与convertLocalFileSystemURL方法相反,将绝对路径转换成相对路径。

参数:

返回值:

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

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

属性:

方法:

isFile

操作对象的是否为文件,DirectoryEntry对象固定其值为false

说明:

Boolean 类型 只读属性

isDirectory

操作对象是否为目录,DirectoryEntry对象固定其值为true

说明:

Boolean 类型 只读属性

name

目录操作对象的名称,不包括路径

说明:

DOMString 类型 只读属性

fullPath

目录操作对象的完整路径,文件系统的绝对路径

说明:

DOMString 类型 只读属性

fileSystem

文件操作对象所属的文件系统对象,参考FileSystem

说明:

FileSystem 类型 只读属性

getMetadata

获取目录的属性


entry.getMetadata( successCB, errorCB, recursive );
						

说明:

用于获取文件或目录的属性信息。 获取属性信息成功通过succesCB回调返回,失败则通过errorCB返回。

参数:

返回值:

void : 无

平台支持:

示例:


// 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返回。

参数:

返回值:

void : 无

平台支持:

示例:


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返回。

参数:

返回值:

void : 无

平台支持:

示例:


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

平台支持:

示例:


// Get the URL for this directory
var dirURL = entry.toURL();
plus.console.log(dirURL);
						

toLocalURL

获取目录路径转换为本地路径URL地址


DOMString entry.toLocalURL();
						

参数:

返回值:

DOMString : 格式为本地路径URL

平台支持:

示例:


// 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/”开头的网络路径。

平台支持:

示例:


// Get the remote URL for this directory
var dirURL = entry.toRemoteURL();
plus.console.log(dirURL);
						

remove

删除目录


entry.remove( succesCB, errorCB );
						

说明:

以下情况删除目录将会导致失败: 目录中存在文件; 删除根目录; 删除目录成功通过succesCB回调返回,失败则通过errorCB返回。

参数:

返回值:

void : 无

平台支持:

示例:


// remove this directory
entry.remove( function ( entry ) {
	plus.console.log( "Remove succeeded" );
}, function ( e ) {
	alert( e.message );
} );
						

getParent

获取目录所属的父目录


entry.getParent( succesCB, errorCB );
						

说明:

获取父目录成功通过succesCB回调返回,失败则通过errorCB返回。

参数:

返回值:

void : 无

平台支持:

示例:


// 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 : 目录读取对象

平台支持:

示例:


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

getDirectory

创建或打开子目录


entry.getDirectory( path, flag, succesCB, errorCB );
						

说明:

创建或打开当前目录指定的目录。 创建或打开目录操作成功通过succesCB回调返回,失败则通过errorCB返回。

参数:

返回值:

void : 无

平台支持:

示例:


// 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返回。

参数:

返回值:

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
		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返回。

参数:

返回值:

void : 无

平台支持:

示例:


// 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

获取当前目录中的所有文件和子目录


directoryReader.readEntries( succesCB, errorCB );
						

说明:

获取当前目录下的所有文件和子目录。 获取操作成功通过succesCB回调返回,失败则通过errorCB返回。

参数:

返回值:

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

文件数据对象的数据大小,单位为字节

说明:

Number 类型 只读属性

type

文件数据对象MIME类型

说明:

DOMString 类型 只读属性

name

文件数据对象的名称,不包括路径

说明:

DOMString 类型 只读属性

lastModifiedDate

文件对象的最后修改时间

说明:

Date 类型 只读属性

slice

获取文件指定的数据内容


file.slice( start, end );
						

说明:

获取文件指定的数据内容,其中end必须大于start。

参数:

返回值:

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

文件操作对象的是否为文件,FileEntry对象固定其值为true

说明:

Boolean 类型 只读属性

isDirectory

文件操作对象是否为目录,FileEntry对象固定其值为false

说明:

Boolean 类型 只读属性

name

文件操作对象的名称,不包括路径

说明:

DOMString 类型 只读属性

fullPath

文件操作对象的完整路径,文件系统的绝对路径

说明:

DOMString 类型 只读属性

fileSystem

文件操作对象所属的文件系统对象,参考FileSystem

说明:

FileSystem 类型 只读属性

getMetadata

获取文件的属性信息


entry.getMetadata( successCB, errorCB );
						

说明:

用于获取文件的属性信息。 获取属性信息成功通过succesCB回调返回,失败则通过errorCB返回。

参数:

返回值:

void : 无

平台支持:

示例:


// 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返回。

参数:

返回值:

void : 无

平台支持:

示例:


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返回。

参数:

返回值:

void : 无

平台支持:

示例:


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

平台支持:

示例:


// Get the URL for this file
var fileURL = entry.toURL();
plus.console.log(fileURL);
						

toLocalURL

获取文件路径转换为本地路径URL地址


DOMString entry.toLocalURL();
						

参数:

返回值:

DOMString : 格式为本地路径URL

平台支持:

示例:


// 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

平台支持:

示例:


// Get the remote URL for this file
var fileURL = entry.toRemoteURL();
plus.console.log(dirURL);
						

remove

删除文件


entry.remove( succesCB, errorCB );
						

说明:

删除文件成功通过succesCB回调返回,失败则通过errorCB返回。

参数:

返回值:

void : 无

平台支持:

示例:


// remove this file
entry.remove( function ( entry ) {
	plus.console.log( "Remove succeeded" );
}, function ( e ) {
	alert( e.message );
} );
						

getParent

获取文件所属的父目录


entry.getParent( succesCB, errorCB );
						

说明:

获取父目录成功通过succesCB回调返回,失败则通过errorCB返回。

参数:

返回值:

void : 无

平台支持:

示例:


// 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返回。

参数:

返回值:

void : 无

平台支持:

示例:


// 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返回。

参数:

返回值:

void : 无

平台支持:

示例:


// 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

创建读取文件对象

说明:

创建读取文件对象

参数:

返回值:

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编码。

参数:

返回值:

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 );
						

说明:

读取文件的数据内容。

参数:

返回值:

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 类型

onprogress

读取文件过程中的回调函数

说明:

FileEventCallback 类型

用于获取文件读取进度。

onload

读取文件成功完成的回调函数

说明:

FileEventCallback 类型

onabort

取消读取文件时的回调函数

说明:

FileEventCallback 类型

onerror

文件读取操作失败时调用的回调函数

说明:

FileEventCallback 类型

onloadend

文件读取操作完成时的回调函数

说明:

FileEventCallback 类型

不管成功或失败都会触发。

FileWriter

文件系统中的写文件对象,用于写入文件内容

说明:

FileWriter对象是从设备文件系统写入文件FileWriter对象是从设备文件系统写入文件的一种方式,用户注册自己的事件监听器来接收writestart、progress、write、writeend、error和abort事件。 一个FileWriter对象是为单个文件的操作而创建。你可以使用该对象多次对相应文件进行写入操作。FileWriter维护该文件的指针位置及长度属性,这样你就可以寻找和写入文件的任何地方。 默认情况下,FileWriter从文件的开头开始写入(将覆盖现有数据)。FileWriter对象的seek方法可设置文件操作指定位置,如fw.seek(fw.length-1)写入操作就会从文件的末尾开始。

常量:

属性:

方法:

事件:

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表示文件的起始位置。

参数:

返回值:

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 );
						

说明:

从文件当前定位的位置开始,按照指定长度截断文件。

参数:

返回值:

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 );
						

说明:

从文件当前定位的位置开始,写入数据到文件中。 如果文件中已经存在数据,新写入的数据将覆盖已有数据。

参数:

返回值:

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 类型

onprogress

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

说明:

FileEventCallback 类型

用于获取文件读取进度。

onwrite

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

说明:

FileEventCallback 类型

onabort

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

说明:

FileEventCallback 类型

onerror

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

说明:

FileEventCallback 类型

onwriteend

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

说明:

FileEventCallback 类型

不管成功或失败都会触发。

FileSystem

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

说明:

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

属性:

示例:


<!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 类型 只读属性

Flags

JSON对象,获取文件操作的参数

属性:

Metadata

JSON对象,保存文件或目录的状态信息对象

说明:

可通过DirectoryEntry或FileEntry对象的getMetaData方法获取

属性:

FileEvent

文件或目录操作事件对象

说明:

所有文件或目录操作事件回调函数中都创建该对象的实例。 该对象从DOMEvent继承而来,可通过该其target属性获取事件触发的文件或目录操作对象。

属性:

URLType

文件路径类型

说明:

在文件系统中的文件路径需转换成URL格式,已方便runtime快速加载。

RelativeURL

相对路径URL

说明:

只能在扩展API中使用,相对于基座提供的特定目录,以“_”开头。

常量:

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对象的事件函数中触发。

参数:

返回值:

void : 无

FileSystemSuccessCallback

请求文件系统成功的回调函数


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

参数:

返回值:

void : 无

FileResolveSuccessCallback

通过URL参数获取目录或文件对象成功的回调函数


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

参数:

返回值:

void : 无

MetadataSuccessCallback

获取文件或目录状态信息成功的回调函数


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

参数:

返回值:

void : 无

EntrySuccessCallback

操作文件或目录对象成功的回调函数


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

参数:

返回值:

void : 无

EntrysSuccessCallback

操作文件或目录对象数组成功的回调函数


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

参数:

返回值:

void : 无

FileWriterSuccessCallback

写文件操作成功的回调函数


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

参数:

返回值:

void : 无

FileSuccessCallback

文件操作成功的回调函数


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

参数:

返回值:

void : 无

FileErrorCallback

文件操作失败的回调函数


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

参数:

返回值:

void : 无