FileReader

藉由 FileReader 物件,Web 應用程式能以非同步(asynchronously)方式讀取儲存在用戶端的檔案(或原始資料暫存)內容,可以使用 FileBlob 物件指定要讀取的資料。

File 物件可以從使用者於 <input> 元素選擇之檔案所回傳的 FileList 物件當中取得,或是來自拖放操作所產生的 DataTransfer 物件之中,也能由 HTMLCanvasElement 物件(元素物件)執行 mozGetAsFile() 方法後回傳。

註:

This feature is available in Web Workers.

建構式

FileReader() (en-US)
建立新的 FileReader 物件。

請參考在網頁應用程式中使用本地檔案的更多細節與範例。

屬性

FileReader.error Read only
DOMException (en-US) 類型的物件記錄了讀取資料時發生的錯誤資訊。
FileReader.readyState Read only
表示目前 FileReader 狀態的數字,其代表的意義為:
EMPTY 0 尚未讀入任何資料。
LOADING 1 正在讀入資料。
DONE 2 完成資料讀取。
FileReader.result (en-US) Read only
讀入的資料內容。只有在讀取完成之後此屬性才有效,而資料的格式則取決於是由哪一個方法進行讀取。

事件處理器

FileReader.onabort (en-US)
abort (en-US) 事件處理器,於讀取被中斷時觸發。
FileReader.onerror (en-US)
error (en-US) 事件處理器,於讀取發生錯誤時觸發。
FileReader.onload (en-US)
load (en-US) 事件處理器,於讀取完成時觸發。
FileReader.onloadstart
loadstart (en-US) 事件處理器,於讀取開始時觸發。
FileReader.onloadend
loadend (en-US) 事件處理器,於每一次讀取結束之後觸發(不論成功或失敗),會於 onloadonerror 事件處理器之後才執行。
FileReader.onprogress
progress (en-US) 事件處理器,於讀取 Blob 內容時觸發。

FileReader 物件繼承自 EventTarget,其所有的事件也都能夠透過 addEventListener (en-US) 方法來註冊事件監聽器。

方法

FileReader.abort() (en-US)
中斷目前的讀取,此方法回傳後屬性 readyState 將會是 DONE
FileReader.readAsArrayBuffer() (en-US)
開始讀取指定的 Blob,讀取完成後屬性 result 將以 ArrayBuffer (en-US) 物件來表示讀入的資料內容。
FileReader.readAsBinaryString() (en-US) This API has not been standardized.
開始讀取指定的 Blob,讀取完成後屬性 result 將以字串型式來表示讀入的原始二進位資料(raw binary data)。
FileReader.readAsDataURL() (en-US)
開始讀取指定的 Blob,讀取完成後屬性 result 將以 data: URL 格式(base64 編碼)的字串來表示讀入的資料內容。
FileReader.readAsText() (en-US)
開始讀取指定的 Blob,讀取完成後屬性 result 將以文字字串型式來表示讀入的資料內容。

規範

規範 狀態 註解
File API
The definition of 'FileReader' in that specification.
Working Draft Initial definition

瀏覽器相容性

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help! (en-US)

功能 Firefox (Gecko) Chrome Edge Internet Explorer Opera Safari
基本支援 3.6 (1.9.2)[1] 7 (Yes) 10[2] 12.02[2] 6.0
在 Web Workers 的支援 46 (46) (Yes) (Yes) No support (Yes) No support
error property uses DOMException (en-US), not DOMError (en-US) 58 (58) (Yes) (Yes) No support (Yes) No support
功能 Firefox Mobile (Gecko) Android Edge IE Mobile Opera Mobile Safari Mobile
基本支援 32 3 (Yes) 10 11.5 6.1
在 Web Workers 的支援 46.0 (46) (Yes) (Yes) No support (Yes) No support
error property uses DOMException (en-US), not DOMError (en-US) 58.0 (58) ? (Yes) No support (Yes) No support

[1] 在 Gecko 2.0 beta 7 (Firefox 4.0 beta 7) 以前,所有的 Blob 參數都屬於 File 參數;之後為了更符合規範,所以更新了這個特徵。在 Gecko 13.0 (Firefox 13.0 / Thunderbird 13.0 / SeaMonkey 2.10) 以前,FileReader.error 屬性回傳了 FileError (en-US) 物件。這個介面之後被移除、而 FileReader.error 目前會回傳 DOMError (en-US) 並定義為 FileAPI draft。

[2] Opera 在 11.1 有限度支援

參見