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