IO · Html5+參考

# [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 : 無