FormData 是 HTML5 標準中新增的一組封裝對象。過去我們想用 JavaScript 收集表單資料再用 Ajax 送出,得自己一個欄位一個欄位拼字串、自己處理編碼,步驟瑣碎又容易出錯。有了 FormData,這些工作幾乎可以簡化成一行。
傳統做法通常是這樣的:遍歷表單元素、取值、手動做 URL 編碼、再用 "key=value&key2=value2" 的形式串起來。一旦表單裡出現檔片上傳,這套方式就完全行不通,因為二進位內容沒辦法用字串表達。FormData 的價值就在這裡:它天生支援文字欄位與檔案的混雜,能產生正確的 multipart/form-data 請求體。
第一種是直接從現有表單構造,瀏覽器會自動把表單裡所有具名的元素收進來:
var fd = new FormData(document.querySelector('#myForm'));
第二種是完全手動建立,適合表單並不存在於頁面、資料來自其他來源的場景:
var fd = new FormData();
fd.append('username', 'kiro');
fd.append('avatar', document.getElementById('file').files[0]);
FormData 的 API 設計非常直觀,方法名基本能自解釋:
append(key, value) 追加一組資料,同名鍵可以有多個值;set(key, value) 覆寫同名鍵的所有值;get(key) 取第一個值;getAll(key) 取全部值;has(key) 判斷鍵是否存在;delete(key) 刪除整個鍵;entries()、keys()、values() 則用來遍歷,可以直接搭配 for...of 使用。
用 XMLHttpRequest 時,只要把 FormData 物件當成 send 的參數即可:
var xhr = new XMLHttpRequest();
xhr.open('POST', '/upload');
xhr.send(fd);
這裡有一個非常關鍵、也最常被忽略的細節:不要手動設定 Content-Type 標頭。multipart 請求需要在 Content-Type 中附帶一組 boundary 分隔符,而這組 boundary 是瀏覽器在序列化時隨機產生的。你若自己寫死 Content-Type,boundary 對不上,後端就會解析失敗。
如果改用 fetch,寫法更短:
fetch('/upload', { method: 'POST', body: fd });
同樣的原則:不要自己動 Content-Type。
目前主流瀏覽器都已完整支援 FormData,包括 IE 10 以後的版本,行動裝置端更不成問題,可以放心使用。需要注意的是,較老的 IE 不支援 entries() 這類迭代方法,遍歷時可以改用 XHR 的 send 流程,或在建構階段自行記錄鍵名。


總結一句:FormData 把「收集表單資料」這件事從一堆手工作業變成了一個標準物件,尤其在處理檔片上傳時,它幾乎是唯一優雅的解法。