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

File API 源自 Mozilla 向 W3C 提交的規格草案,目標是提供一套標準化的 JavaScript 介面來操作本機檔案。基於安全考量,它只開放有限的存取能力:檔案必須由使用者主動透過 <input type="file"> 選取或拖放提供,程式無法任意掃描目錄。Firefox 3.6 是最早支援的瀏覽器,其後 Chrome 與 Safari 相繼跟進,並成為 HTML5 規格的一部分。
File API 由一組物件與事件構成,作用在 <input type="file"> 選到的檔案上:
size 屬性為大小,slice() 可將長 Blob 切小。name(不含路徑的檔名)、type(MIME 類型)、lastModifiedDate 等屬性。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。