前言
檔案上傳是每個專案都會遇到的需求,但「上傳中要顯示進度」這件事,在 HTML5 之前往往得靠 Flash 或第三方上傳元件硬做。本文示範完全不依賴 Flash、也不裝任何上傳外掛,只用 Ajax 加 HTML5 的原生能力,做出有進度條、可預覽縮圖、還能拖曳多檔的上傳介面。
目標功能分成兩層:基本功能是帶進度條的單檔上傳;進階功能則是透過拖曳操作一次上傳多個檔案。
HTML5 的 File API 規格定義了一套標準化的本機檔案存取方式,讓我們能取得檔名、類型、大小等資訊,甚至在送出前就在客戶端完成格式與大小的驗證。其中兩個介面最關鍵:
<input type="file">,也可來自拖曳動作。另一位無名英雄是 XMLHttpRequest Level 2(XHR2)。它與舊版大同小異,但多了三項要命的新能力:
progress 事件,其中包含 total(總位元組數)、loaded(已上傳位元組數)、lengthComputable(大小是否可計算)三個資訊。正是這些特性讓 Ajax 與 HTML5 得以完美協作:不必再依賴 Flash Player、外部插件,甚至不必非得用 <form> 包起來,就能依伺服器端回報即時繪製進度條。
表單由「選檔」與「開始上傳」兩個按鈕組成,進度用 Bootstrap 的 progress bar 呈現,右側另闢資訊區顯示檔名、類型、大小與縮圖。
<div id="FormContent"> <form id="FormUpload" enctype="multipart/form-data" method="post"> <span class="btn btn-success fileinput-button"> <i class="glyphicon glyphicon-plus"></i> <span>Add files...</span> <input type="file" name="UploadedFile" id="UploadedFile" /> </span> <button class="btn btn-primary start" type="button" id="Submit_btn"> <i class="glyphicon glyphicon-upload"</i> <span>Start upload</span> </button> <button class="btn btn-warning cancel" type="button" id="Cancel_btn"> <i class="glyphicon glyphicon-ban-circle"></i> <span>close</span> </button> </form> <div class="progress CustomProgress"> <div id="FileProgress" class="progress-bar" role="progressbar" aria-valuenow="" aria-valuemin="" aria-valuemax="" style="width %;"> <span></span> </div> </div> <div class="InfoContainer"> <div id="Imagecontainer"></div> <div id="FileName" class="info"> </div> <div id="FileType" class="info"> </div> <div id="FileSize" class="info"> </div> </div> </div>
接著在檔案輸入元素的 change 事件中掛上 singleFileSelected,無論使用者是首次選擇還是中途換檔都會觸發。方法內取得 FileList 後取 files[0],就能讀到檔名、類型與大小。
function singleFileSelected(evt) { var selectedFile = ($("#UploadedFile"))[].files[];//FileControl.files[]; if (selectedFile) { var FileSize = ; var imageType = /image.*/; if (selectedFile.size > ) { FileSize = Math.round(selectedFile.size * / ) / + " MB"; } else if (selectedFile.size > ) { FileSize = Math.round(selectedFile.size * / ) / + " KB"; } else { FileSize = selectedFile.size + " Bytes"; } $("#FileName").text("Name " + selectedFile.name); $("#FileType").text("type " + selectedFile.type); $("#FileSize").text("Size " + FileSize); } }
FileReader 提供 onload、onerror 等事件,以及 readAsBinaryString()、readAsText()、readAsArrayBuffer()、readAsDataURL() 四種讀取方法,result 屬性則存放讀到的內容。這裡我們用 readAsDataURL() 把圖片轉成 data URL 直接塞進 <img>:
if (selectedFile.type.match(imageType)) { var reader = new FileReader(); reader.onload = function (e) { $("#Imagecontainer").empty(); var dataURL = reader.result; var img = new Image() img.src = dataURL; img.className = "thumb"; $("#Imagecontainer").append(img); }; reader.readAsDataURL(selectedFile); }
做到這裡,畫面上已經能看到檔名、類型、大小與即時縮圖:

重點來了。要拿到進度,必須自己接管 XHR 物件,做法是透過 $.ajax 的 xhr 選項回傳自訂的 XHR,並在它的 upload 上掛監聽:
function UploadFile() { //可用 FormData 建構子直接吃表單,也可手動 append //注意欄位名稱必須與 Action 參數一致 var form = $('#FormUpload')[]; var dataString = new FormData(form); $.ajax({ url '/Uploader/Upload', type 'POST', xhr function () { var myXhr = $.ajaxSettings.xhr(); if (myXhr.upload) { myXhr.upload.addEventListener('progress', progressHandlingFunction, false); } return myXhr; }, success successHandler, error errorHandler, completecompleteHandler, data dataString, //告訴 jQuery 不要加工資料、不要動 content-type cache false, contentType false, processData false }); }
其中 processData: false 與 contentType: false 這兩個設定是無痛的關鍵:前者阻止 jQuery 把 FormData 序列化成字串,後者讓瀏覽器自行帶上正確的 multipart/form-data boundary,少設一個就會 500。
進度計算本身非常單純,先確認 lengthComputable 為真,再用 loaded / total 換算百分比:
function progressHandlingFunction(e) { if (e.lengthComputable) { var percentComplete = Math.round(e.loaded * / e.total); $("#FileProgress").css("width", percentComplete + '%').attr('aria-valuenow', percentComplete); $('#FileProgress span').text(percentComplete + "%"); } else { $('#FileProgress span').text('unable to compute'); } }
在 upload action 中,HttpPostedFileBase 已經把上傳檔案包裝好,FileName(檔名)、ContentType(類型)、InputStream(內容流)全都拿得到,既可用來驗證也可直接落檔。
public JsonResult Upload(HttpPostedFileBase uploadedFile) { if (uploadedFile != null && uploadedFile.ContentLength > ) { byte[] FileByteArray = new byte[uploadedFile.ContentLength]; uploadedFile.InputStream.Read(FileByteArray, , uploadedFile.ContentLength); Attachment newAttchment = new Attachment(); newAttchment.FileName = uploadedFile.FileName; newAttchment.FileType = uploadedFile.ContentType; newAttchment.FileContent = FileByteArray; OperationResult operationResult = attachmentManager.SaveAttachment(newAttchment); if (operationResult.Success) { string HTMLString = CaptureHelper.RenderViewToString ("_AttachmentItem", newAttchment, this.ControllerContext); return Json(new { statusCode = , status = operationResult.Message, NewRow = HTMLString }, JsonRequestBehavior.AllowGet); } else { return Json(new { statusCode = , status = operationResult.Message, file = uploadedFile.FileName }, JsonRequestBehavior.AllowGet); } } return Json(new { statusCode = , status = "Bad Request! Upload Failed", file = string.Empty }, JsonRequestBehavior.AllowGet); }
先為 file input 加上 multiple 屬性,再畫一個放投區:
<div id="drop_zone">Drop images Here</div>
拖曳的處理與單檔版本很像,差別在於要跑迴圈把選到的檔案全部列出來,同時得呼叫 stopPropagation() 與 preventDefault() 阻止瀏覽器把檔案直接開啟:
function MultiplefileSelected(evt) { evt.stopPropagation(); evt.preventDefault(); $('#drop_zone').removeClass('hover'); selectedFiles = evt.target.files || evt.dataTransfer.files; if (selectedFiles) { $('#Files').empty(); for (var i = ; i < selectedFiles.length; i++) { DataURLFileReader.read(selectedFiles[i], function (err, fileInfo) { if (err != null) { var RowInfo = '<div id="File_' + i + '" class="info"><div class="InfoContainer">' + '<div class="Error">' + err + '</div>' + '<div data-name="FileName" class="info">' + fileInfo.name + '</div>' + '<div data-type="FileType" class="info">' + fileInfo.type + '</div>' + '<div data-size="FileSize" class="info">' + fileInfo.size() + '</div></div><hr/></div>'; $('#Files').append(RowInfo); } else { var image = '<img src="' + fileInfo.fileContent + '" class="thumb" title="' + fileInfo.name + '" />'; var RowInfo = '<div id="File_' + i + '" class="info"><div class="InfoContainer">' + '<div data_img="Imagecontainer">' + image + '</div>' + '<div data-name="FileName" class="info">' + fileInfo.name + '</div>' + '<div data-type="FileType" class="info">' + fileInfo.type + '</div>' + '<div data-size="FileSize" class="info">' + fileInfo.size() + '</div></div><hr/></div>'; $('#Files').append(RowInfo); } }); } } }
這裡把選檔與拖檔的結果統一存進全域變數 selectedFiles,再逐一傳給自製的 DataURLFileReader.read()。這個小工具包著 FileReader,把 onload/onerror 改寫成 callback 形式,最後彙整成一個 FileInfo 物件:
var DataURLFileReader = { read function (file, callback) { var reader = new FileReader(); var fileInfo = { name file.name, type file.type, fileContent null, size function () { var FileSize = ; if (file.size > ) { FileSize = Math.round(file.size * / ) / + " MB"; } else if (file.size > ) { FileSize = Math.round(file.size * / ) / + " KB"; } else { FileSize = file.size + " bytes"; } return FileSize; } }; if (!file.type.match('image.*')) { callback("file type not allowed", fileInfo); return; } reader.onload = function () { fileInfo.fileContent = reader.result; callback(null, fileInfo); }; reader.onerror = function () { callback(reader.error, fileInfo); }; reader.readAsDataURL(file); } };
再為 drop zone 註冊四個拖曳事件,其中 dragover 必須 preventDefault(),否則 drop 永遠不會觸發:
var dropZone = document.getElementById('drop_zone'); dropZone.addEventListener('dragover', handleDragOver, false); dropZone.addEventListener('drop', MultiplefileSelected, false); dropZone.addEventListener('dragenter', dragenterHandler, false); dropZone.addEventListener('dragleave', dragleaveHandler, false);
function handleDragOver(evt) { evt.preventDefault(); evt.dataTransfer.effectAllowed = 'copy'; evt.dataTransfer.dropEffect = 'copy'; }
多檔送出時,建議手動組 FormData 並逐一 append,這樣能順便過濾掉不符合規格的檔案:
function UploadMultipleFiles() { //手動建立 FormData,避免送出非圖片檔 var dataString = new FormData(); for (var i = ; i < selectedFiles.length; i++) { if (!selectedFiles[i].type.match('image.*')) { continue; } } // AJAX Request code here }
伺服器端只要把參數改成陣列即可,但務必確認 HttpPostedFileBase[] 的名稱與 append() 用的 key 完全一致,MVC 的模型綁定才會把它對應成檔案陣列:
public JsonResult UplodMultiple(HttpPostedFileBase[] uploadedFiles) dataString.append("uploadedFiles", selectedFiles[i]);
預設的請求大小上限會直接把你擋在門外。若使用 IIS7 以上版本,在 Web.config 補上:
<system.webServer> <security> <requestFiltering> <requestLimits maxAllowedContentLength="" /> </requestFiltering> </security> </system.webServer> <httpRuntime targetFramework="." maxRequestLength=""/>
兩個數字都要放大,其中 maxAllowedContentLength 的單位是位元組、maxRequestLength 的單位是 KB,別搞混。設定完成後,理論上可上傳到 2GB 等級的檔案。
最後提醒:所有在客戶端做的格式與大小驗證都只是使用者體驗的加分項,真正的把關一定要在伺服器端重做一次,包含副檔名白名單、Magic Number 檢查與儲存路徑的跳脫防護。