io
File模块管理本地文件系统,用于对文件系统的目录浏览、文件的读取、文件的写入等操作。通过plus.io可获取文件系统管理对象。
常量:
- PRIVATE_WWW: 应用运行资源目录常量
- PRIVATE_DOC: 应用私有文档目录常量
- PUBLIC_DOCUMENTS: 程序公用文档目录常量
- PUBLIC_DOWNLOADS: 程序公用下载目录常量
方法:
- requestFileSystem: 请求本地文件系统对象
- resolveLocalFileSystemURL: 通过URL参数获取目录对象或文件对象
- convertLocalFileSystemURL: 将本地URL路径转换成平台绝对路径
- convertAbsoluteFileSystem: 将平台绝对路径转换成本地URL路径
对象:
- DirectoryEntry: 文件系统中的目录对象,用于管理特定的本地目录
- DirectoryReader: 读取目录信息对象,用于获取目录中包含的文件及子目录
- File: 文件系统中的文件数据对象,用于获取文件的数据
- FileEntry: 文件系统中的文件对象,用于管理特定的本地文件
- FileReader: 文件系统中的读取文件对象,用于获取文件的内容
- FileWriter: 文件系统中的写文件对象,用于写入文件内容
- FileSystem: 文件系统对象,用于管理特定本地文件目录
- Flags: JSON对象,获取文件操作的参数
- Metadata: JSON对象,保存文件或目录的状态信息对象
- FileEvent: 文件或目录操作事件对象
- URLType: 文件路径类型
- RelativeURL: 相对路径URL
- LocalURL: 本地路径URL
- RemoteURL: 网络路径URL
回调方法:
- FileEventCallback: 文件事件回调
- FileSystemSuccessCallback: 请求文件系统成功的回调函数
- FileResolveSuccessCallback: 通过URL参数获取目录或文件对象成功的回调函数
- MetadataSuccessCallback: 获取文件或目录状态信息成功的回调函数
- EntrySuccessCallback: 操作文件或目录对象成功的回调函数
- EntrysSuccessCallback: 操作文件或目录对象数组成功的回调函数
- FileWriterSuccessCallback: 写文件操作成功的回调函数
- FileSuccessCallback: 文件操作成功的回调函数
- FileErrorCallback: 文件操作失败的回调函数
权限:
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。应用私有文档目录,仅本应用可访问。
平台支持
PUBLIC_DOCUMENTS
程序公用文档目录常量
plus.io.PUBLIC_DOCUMENTS;
说明:
Number 类型
本地文件系统常量,Number类型,固定值3。程序公用文档目录,所有应用可访问。
平台支持
PUBLIC_DOWNLOADS
程序公用下载目录常量
plus.io.PUBLIC_DOWNLOADS;
说明:
Number 类型
本地文件系统常量,Number类型,固定值4。程序公用下载目录,所有应用可访问。
平台支持
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
)
必选 请求文件系统成功的回调
- errorCB:
(
FileErrorCallback
)
可选 请求文件系统失败的回调
返回值:
void : 无平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
<!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。 获取指定的文件或目录操作对象成功通过succesCB回调返回,如果指定URL路径或文件不存在则失败通过errorCB回调返回。
参数:
- url :
(
DOMString
)
必选 要操作文件或目录的URL地址
- succesCB:
(
FileResolveSuccessCallback
)
必选 获取操作文件或目录对象成功的回调函数
- errorCB:
(
FileErrorCallback
)
可选 获取操作文件或目录对象失败的回调函数
返回值:
void : 无平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
<!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: 操作对象的是否为文件,DirectoryEntry对象固定其值为false
- isDirectory: 操作对象是否为目录,DirectoryEntry对象固定其值为true
- name: 目录操作对象的名称,不包括路径
- fullPath: 目录操作对象的完整路径,文件系统的绝对路径
- fileSystem: 文件操作对象所属的文件系统对象,参考FileSystem
方法:
- getMetadata: 获取目录的属性
- moveTo: 移动目录
- copyTo: 拷贝目录
- toURL: 获取目录路径转换为URL地址
- toLocalURL: 获取目录路径转换为本地路径URL地址
- toRemoteURL: 获取目录路径转换为网络路径URL地址
- remove: 删除目录
- getParent: 获取目录所属的父目录
- createReader: 创建目录读取对象
- getDirectory: 创建或打开子目录
- getFile: 创建或打开文件
- 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
)
必选 获取文件或目录属性信息成功的回调
- errorCB:
(
FileErrorCallback
)
必选 获取文件或目录属性信息失败的回调
- recursive:
(
Boolean
)
必选 是否递归计算目录信息
true为递归计算获取信息,false不递归计算获取,默认值为false。
返回值:
void : 无平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
// 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
)
必选 要移动到的目标目录
- newName:
(
DOMString
)
可选 移动后的目录名称,默认为原始目录名称
- succesCB:
(
EntrySuccessCallback
)
可选 移动目录成功的回调函数
回调函数中的参数保存新的目录对象。 - errorCB:
(
FileErrorCallback
)
可选 移动目录失败的回调函数
返回值:
void : 无平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
function moveDirecty(entry) { var parent = document.getElementById('parent').value, parentName = parent.substring(parent.lastIndexOf('/')+1), newName = document.getElementById('newName').value, parentEntry = new DirectoryEntry(parentName, parent); // move the directory to a new directory and rename it entry.moveTo( parentEntry, 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
)
必选 要拷贝到的目标目录
- newName:
(
DOMString
)
可选 拷贝后的目录名称,默认为原始目录名称
- succesCB:
(
EntrySuccessCallback
)
可选 拷贝目录成功的回调函数
回调函数中的参数保存新的目录对象。 - errorCB:
(
FileErrorCallback
)
可选 拷贝目录失败的回调函数
返回值:
void : 无平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
function moveDirecty(entry) { var parent = document.getElementById('parent').value, parentName = parent.substring(parent.lastIndexOf('/')+1), newName = document.getElementById('newName').value, parentEntry = new DirectoryEntry(parentName, parent); // copy the directory to a new directory and rename it entry.copyTo( parentEntry, newName, function ( entry ) { plus.console.log("New Path: " + entry.fullPath); }, function ( e ) { alert( e.message ); } ); }
toURL
获取目录路径转换为URL地址
DOMString entry.toURL();
参数:
返回值:
DOMString : 格式为相对路径URL平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
// Get the URL for this directory var dirURL = entry.toURL(); plus.console.log(dirURL);
toLocalURL
获取目录路径转换为本地路径URL地址
DOMString entry.toLocalURL();
参数:
返回值:
DOMString : 格式为本地路径URL平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
// Get the local URL for this directory var dirURL = entry.toLocalURL(); plus.console.log(dirURL);
toRemoteURL
获取目录路径转换为网络路径URL地址
DOMString entry.toRemoteURL();
参数:
返回值:
DOMString : 格式为网络路径URL平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
// Get the remote URL for this directory var dirURL = entry.toRemoteURL(); plus.console.log(dirURL);
remove
删除目录
entry.remove( succesCB, errorCB );
说明:
以下情况删除目录将会导致失败: 目录中存在文件; 删除根目录; 删除目录成功通过succesCB回调返回,失败则通过errorCB返回。
参数:
- succesCB:
(
EntrySuccessCallback
)
可选 删除目录成功的回调函数
回调函数中无参数。 - errorCB:
(
FileErrorCallback
)
可选 删除目录失败的回调函数
返回值:
void : 无平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
// 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
)
可选 获取父目录成功的回调函数
- errorCB:
(
FileErrorCallback
)
可选 获取父目录失败的回调函数
返回值:
void : 无平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
// 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 : 目录读取对象平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
// create a directory reader var directoryReader = entry.createReader();
getDirectory
创建或打开子目录
entry.getDirectory( path, flag, succesCB, errorCB );
说明:
创建或打开当前目录指定的目录。 创建或打开目录操作成功通过succesCB回调返回,失败则通过errorCB返回。
参数:
- path:
(
DOMString
)
必选 要操作目录相对于当前目录的地址
- flag:
(
Flags
)
可选 要操作文件或目录的参数
- succesCB:
(
EntrySuccessCallback
)
可选 创建或打开目录成功的回调函数
- errorCB:
(
FileErrorCallback
)
可选 创建或打开目录失败的回调函数
返回值:
void : 无平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
// 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
)
可选 要操作文件或目录的参数
- succesCB:
(
EntrySuccessCallback
)
可选 创建或打开文件成功的回调函数
- errorCB:
(
FileErrorCallback
)
可选 创建或打开文件失败的回调函数
返回值:
void : 无平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
<!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
)
可选 删除目录成功的回调函数
回调函数中无参数。 - errorCB:
(
FileErrorCallback
)
可选 删除目录失败的回调函数
返回值:
void : 无平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
// 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: 获取当前目录中的所有文件和子目录
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>
File
文件系统中的文件数据对象,用于获取文件的数据
属性:
- size: 文件数据对象的数据大小,单位为字节
- type: 文件数据对象MIME类型
- name: 文件数据对象的名称,不包括路径
- lastModifiedDate: 文件对象的最后修改时间
方法:
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
- isDirectory: 文件操作对象是否为目录,FileEntry对象固定其值为false
- name: 文件操作对象的名称,不包括路径
- fullPath: 文件操作对象的完整路径,文件系统的绝对路径
- fileSystem: 文件操作对象所属的文件系统对象,参考FileSystem
方法:
- getMetadata: 获取文件的属性信息
- moveTo: 移动文件
- copyTo: 拷贝文件
- toURL: 获取文件路径转换为URL地址
- toLocalURL: 获取文件路径转换为本地路径URL地址
- toRemoteURL: 获取文件路径转换为网络路径URL地址
- remove: 删除文件
- getParent: 获取文件所属的父目录
- createWriter: 获取文件关联的写文件操作对象FileWriter
- file: 获取文件数据对象
isFile
文件操作对象的是否为文件,FileEntry对象固定其值为true
说明:
Boolean 类型 只读属性
isDirectory
文件操作对象是否为目录,FileEntry对象固定其值为false
说明:
Boolean 类型 只读属性
name
文件操作对象的名称,不包括路径
说明:
DOMString 类型 只读属性
fullPath
文件操作对象的完整路径,文件系统的绝对路径
说明:
DOMString 类型 只读属性
fileSystem
文件操作对象所属的文件系统对象,参考FileSystem
说明:
FileSystem 类型 只读属性
getMetadata
获取文件的属性信息
entry.getMetadata( successCB, errorCB );
说明:
用于获取文件的属性信息。 获取属性信息成功通过succesCB回调返回,失败则通过errorCB返回。
参数:
- succesCB:
(
MetadataSuccessCallback
)
必选 获取文件属性信息成功的回调函数
- errorCB:
(
FileErrorCallback
)
必选 获取文件属性信息失败的回调函数
返回值:
void : 无平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
// 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
)
必选 要移动到的目标目录
- newName:
(
DOMString
)
可选 移动后的文件名称,默认为原始文件名称
- succesCB:
(
EntrySuccessCallback
)
可选 移动文件成功的回调函数
回调函数中的参数保存新的文件对象。 - errorCB:
(
FileErrorCallback
)
可选 移动文件失败的回调函数
返回值:
void : 无平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
function moveDirecty(entry) { var parent = document.getElementById('parent').value, parentName = parent.substring(parent.lastIndexOf('/')+1), parentEntry = new DirectoryEntry(parentName, parent); // move the file to a new directory and rename it entry.moveTo( parentEntry, "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
)
必选 要拷贝到的目标目录
- newName:
(
DOMString
)
可选 拷贝后的文件名称,默认为原始文件名称
- succesCB:
(
EntrySuccessCallback
)
可选 拷贝文件成功的回调函数
回调函数中的参数保存新的文件对象。 - errorCB:
(
FileErrorCallback
)
可选 拷贝文件失败的回调函数
返回值:
void : 无平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
function copyFile(entry) { var parent = document.getElementById('parent').value, parentName = parent.substring(parent.lastIndexOf('/')+1), parentEntry = new DirectoryEntry(parentName, parent); // copy the file to a new directory and rename it entry.copyTo( parentEntry, "file.copy", function () { plus.console.log("New Path: " + entry.fullPath); }, function ( e ) { alert( e.message ); } ); }
toURL
获取文件路径转换为URL地址
DOMString entry.toURL();
参数:
返回值:
DOMString : 格式为相对路径URL平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
// Get the URL for this file var fileURL = entry.toURL(); plus.console.log(fileURL);
toLocalURL
获取文件路径转换为本地路径URL地址
DOMString entry.toLocalURL();
参数:
返回值:
DOMString : 格式为本地路径URL平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
// Get the local URL for this file var fileURL = entry.toLocalURL(); plus.console.log(dirURL);
toRemoteURL
获取文件路径转换为网络路径URL地址
DOMString entry.toRemoteURL();
参数:
返回值:
DOMString : 格式为网络路径URL平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
// Get the remote URL for this file var fileURL = entry.toRemoteURL(); plus.console.log(dirURL);
remove
删除文件
entry.remove( succesCB, errorCB );
说明:
删除文件成功通过succesCB回调返回,失败则通过errorCB返回。
参数:
- succesCB:
(
EntrySuccessCallback
)
可选 删除文件成功的回调函数
回调函数中无参数。 - errorCB:
(
FileErrorCallback
)
可选 删除文件失败的回调函数
返回值:
void : 无平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
// 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
)
可选 获取父目录成功的回调函数
- errorCB:
(
FileErrorCallback
)
可选 获取父目录失败的回调函数
返回值:
void : 无平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
// 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
)
可选 获取写文件操作对象成功的回调函数
- errorCB:
(
FileErrorCallback
)
可选 获取写文件操作对象失败的回调函数
返回值:
void : 无平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
// 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
)
可选 获取文件数据对象成功的回调函数
- errorCB:
(
FileErrorCallback
)
可选 获取文件数据对象失败的回调函数
返回值:
void : 无平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持)
- WP7.5+ (支持)
示例:
// 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: 创建读取文件对象
常量:
属性:
- readyState: 当前读取文件所处的状态
- result: 已读取文件的内容
- error: 文件操作错误代码
方法:
- abort: 终止文件读取操作
- readAsDataURL: 以URL编码格式读取文件数据内容
- readAsText: 以文本格式读取文件数据内容
事件:
- onloadstart: 读取文件开始时的回调函数
- onprogress: 读取文件过程中的回调函数
- onload: 读取文件成功完成的回调函数
- onabort: 取消读取文件时的回调函数
- onerror: 文件读取操作失败时调用的回调函数
- onloadend: 文件读取操作完成时的回调函数
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
读取文件开始时的回调函数
说明:
onprogress
读取文件过程中的回调函数
说明:
用于获取文件读取进度。
onload
读取文件成功完成的回调函数
说明:
onabort
取消读取文件时的回调函数
说明:
onerror
文件读取操作失败时调用的回调函数
说明:
onloadend
文件读取操作完成时的回调函数
说明:
不管成功或失败都会触发。
FileWriter
文件系统中的写文件对象,用于写入文件内容
说明:
FileWriter对象是从设备文件系统写入文件FileWriter对象是从设备文件系统写入文件的一种方式,用户注册自己的事件监听器来接收writestart、progress、write、writeend、error和abort事件。 一个FileWriter对象是为单个文件的操作而创建。你可以使用该对象多次对相应文件进行写入操作。FileWriter维护该文件的指针位置及长度属性,这样你就可以寻找和写入文件的任何地方。 默认情况下,FileWriter从文件的开头开始写入(将覆盖现有数据)。FileWriter对象的seek方法可设置文件操作指定位置,如fw.seek(fw.length-1)写入操作就会从文件的末尾开始。
常量:
属性:
- readyState: 当前写入文件所处的状态
- length: 文件当前的长度,单位为字节
- position: 文件当前操作的指针位置
- error: 文件写入操作错误代码
方法:
事件:
- onwritestart: 写入文件开始时的回调函数
- onprogress: 写入文件过程中的回调函数
- onwrite: 写入文件成功完成的回调函数
- onabort: 取消写入文件时的回调函数
- onerror: 文件写入操作失败时调用的回调函数
- 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 );
说明:
从文件当前定位的位置开始,按照指定长度截断文件。
参数:
返回值:
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
写入文件开始时的回调函数
说明:
onprogress
写入文件过程中的回调函数
说明:
用于获取文件读取进度。
onwrite
写入文件成功完成的回调函数
说明:
onabort
取消写入文件时的回调函数
说明:
onerror
文件写入操作失败时调用的回调函数
说明:
onwriteend
文件写入操作完成时的回调函数
说明:
不管成功或失败都会触发。
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对象,获取文件操作的参数
属性:
- 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
类型
)文件或目录操作对象
在不同的回调中指向的对象不同,可指向的对象包括: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
)
必选 文件事件对象
返回值:
void : 无FileSystemSuccessCallback
请求文件系统成功的回调函数
void onSuccess( fs ) { // File System operate code. }
参数:
- fs:
(
FileSystem
)
必选 请求到的文件系统对象
返回值:
void : 无FileResolveSuccessCallback
通过URL参数获取目录或文件对象成功的回调函数
void onSuccess( entry ) { // File or Direcory entry operate code. }
参数:
- entry:
(
DirectoryEntry
)
必选 请求到的目录或文件对象
可指向文件或目录对象(DirectoryEntry|FileEntry)。
返回值:
void : 无MetadataSuccessCallback
获取文件或目录状态信息成功的回调函数
void onSuccess( metadata ) { // Metadata code. }
参数:
- metadata:
(
Metadata
)
必选 文件或目录的状态信息
返回值:
void : 无EntrySuccessCallback
操作文件或目录对象成功的回调函数
void onSuccess( entry ) { // Entry code. }
参数:
- entry:
(
DirectoryEntry
)
必选 文件或目录对象的引用
可指向文件或目录对象(DirectoryEntry|FileEntry)。
返回值:
void : 无EntrysSuccessCallback
操作文件或目录对象数组成功的回调函数
void onSuccess( entrys ) { // Entrys code. }
参数:
- entrys:
(
DirectoryEntry
)
必选 文件或目录对象数组
可指向文件或目录对象数组(DirectoryEntry[]|FileEntry[])。
返回值:
void : 无FileWriterSuccessCallback
写文件操作成功的回调函数
void onSuccess( writer ) { // FileWriter code. }
参数:
- writer:
(
FileWriter
)
必选 写文件对象的引用
返回值:
void : 无FileSuccessCallback
文件操作成功的回调函数
void onSuccess( file ) { // file code. }
参数:
- file:
(
File
)
必选 文件数据对象的引用
返回值:
void : 无FileErrorCallback
文件操作失败的回调函数
void onError( error ) { // Error code. }
参数:
- error:
(
DOMException
)
必选 文件操作失败的信息