DIV CSS 佈局教程網

深入 File API:用純 JavaScript 完成本機檔案讀取、預覽與拖放上傳
編輯:關於JavaScript     

過去在瀏覽器中存取本機檔案一直是件麻煩事。基於安全考量,JavaScript 長期無法讀取本機內容,工程師只能依賴各瀏覽器各自的私有技術:IE 要靠 ActiveX 控制項,Firefox 得寫擴充功能,跨瀏覽器支援的成本極高。File API 的出現改變了這個局面。

一、File API 是什麼

File API 源自 Mozilla 向 W3C 提交的規格草案,目標是提供一套標準化的 JavaScript 介面來操作本機檔案。基於安全考量,它只開放有限的存取能力:檔案必須由使用者主動透過 <input type="file"> 選取或拖放提供,程式無法任意掃描目錄。Firefox 3.6 是最早支援的瀏覽器,其後 Chrome 與 Safari 相繼跟進,並成為 HTML5 規格的一部分。

二、物件模型

File API 由一組物件與事件構成,作用在 <input type="file"> 選到的檔案上:

  • FileList:檔案清單,通常從表單的 file 欄位取得,是 File 物件的集合。
  • Blob:代表一組原始二進位串流,size 屬性為大小,slice() 可將長 Blob 切小。
  • File:繼承自 Blob,額外提供 name(不含路徑的檔名)、type(MIME 類型)、lastModifiedDate 等屬性。
  • FileReader:負責實際讀取,關聯 File 或 Blob 物件,提供三種讀取方法與六種事件。

讀取方法

readAsBinaryString():讀為二進位字串,每個 byte 對應 [0..255] 的整數,參數為 File 物件。

readAsText():讀為文字,可接受第二個參數指定編碼。

readAsDataURL():讀為 data: 開頭的 URL(定義於 RFC 2397),常用於預覽圖片。

事件

onloadstart:開始讀取時觸發。
progress:讀取中週期性觸發,事件參數含已讀取量。
abort:讀取被中止。
error:讀取出錯。
load:成功讀完。
loadend:讀取結束,不論成功或失敗。

三、基本範例:讀取並上傳

以下範例包含 index.html 與 upload.jsp 兩個檔案。使用者選檔後,以 File API 讀取內容,再用 XMLHttpRequest 以 Ajax 方式送到後端。

HTML 部分:

<body>
<h1>File API Demo</h1>
<p>
<!-- 上傳用表單 -->
<form name="demoForm" id="demoForm" method="post" enctype="multipart/form-data"
      action="javascript: uploadAndSubmit();">
    <p>Upload File: <input type="file" name="file" /></p>
    <p><input type="submit" value="Submit" /></p>
</form>
<div>
    Progessing (in Bytes): <span id="bytesRead"></span> / <span id="bytesTotal"></span>
</div>
</p>
</body>

<form> 的 action 指向 JavaScript 函式 uploadAndSubmit(),由它完成讀取與上傳。form 之外用兩個 span 顯示已讀取與總共的位元組數。

JavaScript 部分:

function uploadAndSubmit() {
    var form = document.forms["demoForm"];
    if (form["file"].files.length > 0) {
        var file = form["file"].files[0];   // FileList 的第一個元素

        var reader = new FileReader();

        reader.onloadstart = function () {
            console.log("onloadstart");
            document.getElementById("bytesTotal").textContent = file.size;
        };

        reader.onprogress = function (p) {
            console.log("onprogress");
            document.getElementById("bytesRead").textContent = p.loaded;
        };

        reader.onload = function () {
            console.log("load complete");
        };

        reader.onloadend = function () {
            if (reader.error) {
                console.log(reader.error);
            } else {
                document.getElementById("bytesRead").textContent = file.size;
                // 以二進位方式送出
                var xhr = new XMLHttpRequest();
                xhr.open("POST", "upload.jsp?fileName=" + file.name);
                xhr.overrideMimeType("application/octet-stream");
                xhr.sendAsBinary(reader.result);
                xhr.onreadystatechange = function () {
                    if (xhr.readyState == 4 && xhr.status == 200) {
                        console.log("upload complete");
                        console.log("response: " + xhr.responseText);
                    }
                };
            }
        };

        reader.readAsBinaryString(file);
    } else {
        alert("Please choose a file.");
    }
}

程式先確認使用者確實選了檔案,否則提示錯誤;接著在 onloadstart 填入總量、onprogress 更新已讀量,最後在 onloadend 中確認無誤後,以 sendAsBinary 把內容 POST 出去。依規格,onloadend 也可拆成 error 與 load 兩個事件分別處理。

伺服器端 JSP:

<%@ page import="java.io.*" %>
<%
BufferedInputStream fileIn = new BufferedInputStream(request.getInputStream());
String fn = request.getParameter("fileName");
byte[] buf = new byte[1024];
File file = new File("d:/" + fn);
BufferedOutputStream fileOut = new BufferedOutputStream(new FileOutputStream(file));
while (true) {
    int bytesIn = fileIn.read(buf, 0, 1024);
    if (bytesIn == -1) break;
    fileOut.write(buf, 0, bytesIn);
}
fileOut.flush();
fileOut.close();
out.print(file.getAbsolutePath());
%>

後端從 POST 內容中取檔名與二進位資料,寫入 D 槽並回傳完整路徑。

四、加上拖放上傳

逐個點擊「瀏覽」在批次上傳時體驗不佳。HTML5 同時提供了拖放支援,兩者搭配就能做出接近桌面應用的操作。

拖放的三個事件

拖放涉及「拖曳源」與「放置目標」。若元素要能被拖曳,需設 draggable="true" 並監聽 dragstart 設定 DataTransfer。而放置目標必須監聽三個事件:

dragenter:決定是否接收,接收則需取消事件並阻止冒泡。
dragover:回應此事件以顯示放置提示。
drop:在此事件中取出 DataTransfer 的資料進行處理。

目標容器的 HTML:

<div id="container">
    <span>Drag and drop files here to upload.</span>
    <ul id="fileList"></ul>
</div>

事件綁定:

function addDNDListeners() {
    var container = document.getElementById("container");
    var fileList = document.getElementById("fileList");

    container.addEventListener("dragenter", function (event) {
        fileList.innerHTML = '';
        event.stopPropagation();
        event.preventDefault();
    }, false);

    container.addEventListener("dragover", function (event) {
        event.stopPropagation();
        event.preventDefault();
    }, false);

    container.addEventListener("drop", handleDrop, false);
}
window.addEventListener("load", addDNDListeners, false);

處理 drop:

function handleDrop(event) {
    var files = event.dataTransfer.files;
    event.stopPropagation();
    event.preventDefault();

    var fileList = document.getElementById("fileList");
    for (var i = 0; i < files.length; i++) {
        var file = files[i];
        var li = document.createElement('li');
        var progressbar = document.createElement('div');
        var img = document.createElement('img');
        var name = document.createElement('span');

        progressbar.className = "progressBar";
        img.src = files[i].getAsDataURL();
        img.width = 32; img.height = 32;
        name.innerHTML = file.name;

        li.appendChild(img);
        li.appendChild(name);
        li.appendChild(progressbar);
        fileList.appendChild(li);
        uploadFile(file, progressbar);
    }
}

getAsDataURL() 讓我們能直接把圖片內容當成 img 的來源顯示縮圖,不必先上傳。別忘了在 drop 處理器中取消冒泡與預設行為。

上傳並顯示進度:

function uploadFile(file, progressbar) {
    var xhr = new XMLHttpRequest();
    var upload = xhr.upload;
    var p = document.createElement('p');
    p.textContent = "0%";
    progressbar.appendChild(p);
    upload.progressbar = progressbar;

    upload.addEventListener("progress", uploadProgress, false);
    upload.addEventListener("load", uploadSucceed, false);
    upload.addEventListener("error", uploadError, false);

    xhr.open("POST", "upload.jsp?fileName=" + file.name);
    xhr.overrideMimeType("application/octet-stream");
    xhr.sendAsBinary(file.getAsBinary());
}

function uploadProgress(event) {
    if (event.lengthComputable) {
        var percentage = Math.round((event.loaded * 100) / event.total);
        if (percentage < 100) {
            event.target.progressbar.firstChild.style.width = (percentage * 2) + "px";
            event.target.progressbar.firstChild.textContent = percentage + "%";
        }
    }
}

function uploadSucceed(event) {
    event.target.progressbar.firstChild.style.width = "200px";
    event.target.progressbar.firstChild.textContent = "100%";
}

function uploadError(error) {
    alert("error: " + error);
}

五、寫在最後:這段程式碼今天還能用嗎

本文所述的概念——FileReader 的讀取模式、事件模型、拖放的三個事件——至今仍然是標準做法。但範例中幾個 API 已被淘汰:readAsBinaryString() 與 sendAsBinary() 已從規格移除,getAsDataURL()/getAsBinary() 也不再建議使用。現代寫法應改為:

// 讀檔:改用 arrayBuffer 或直接用 URL.createObjectURL
var url = URL.createObjectURL(file);      // 預覽用,記得在不用時 revokeObjectURL
img.src = url;

// 上傳:直接用 FormData,不必自己拼 multipart
var fd = new FormData();
fd.append("file", file);
fetch("upload.jsp", { method: "POST", body: fd });

// 進度:可改用 ReadableStream 的 reader 自行累計

另外,正式環境的上傳請務必在伺服器端驗證副檔名、MIME 與檔案大小,並以隨機名稱重新命名存檔位置,避免路徑穿越與覆寫風險。本範例的 JSP 直接以使用者提供的檔名寫檔,僅供教學示範,不可原樣用於 production。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved