檔案上傳是網站與 Web 應用最基礎的需求之一,卻長期缺乏一個「什麼都對」的方案,讓開發者在瀏覽器相容性上耗掉大量時間。
WebUploader 由百度 FEX 團隊開發,以 HTML5 為主、Flash 為輔。它在現代瀏覽器中充分發揮 HTML5 的能力,同時保留 Flash 執行環境以照顧主流 IE,相容 IE6+、iOS 6+、Android 4+。搭配大檔案分片與併發上傳,傳輸效率提升相當明顯。
把大檔切成多塊同時上傳,速度提升顯著。網路出問題時只需重傳失敗的那一片,而非整個檔案;分片也讓進度追蹤更即時。
支援 jpg、jpeg、gif、bmp、png 的預覽與壓縮,減少傳輸量。它會解析 JPEG 中的 meta 資訊,正確處理各種 orientation 標記,壓縮後仍保留原始 meta 資料。
支援多選、型別過濾、拖曳(檔案與資料夾)以及剪貼簿貼上。當剪貼簿裡有圖片時(例如截圖工具擷取後、或網頁上複製圖片),按 Ctrl + V 就能直接加入。
介面一致,兩套執行環境 interchangeable,使用者不必關心內部走的是哪一種。Flash 部分完全沒有做 UI,方便你自由擴充與客製。
檔案多又大時,可在上傳前先算 MD5 進行驗證,一致就直接跳過。若前後端採用相同的分段 MD5 演算法,驗證耗時可壓在 20 毫秒左右。
各功能被拆成獨立的小元件,可以自由搭配;原始碼以 AMD 規範組織,結構清楚,方便進階使用者擴充。
需要三種資源:CSS、JS,以及初始化時指定的 SWF。
<!-- CSS --> <link rel="stylesheet" type="text/css" href="webuploader文件夾/webuploader.css" /> <!-- JS --> <script type="text/javascript" src="webuploader文件夾/webuploader.js"></script> <!-- SWF 於初始化時指定 -->
WebUploader 只提供上傳的底層實作,不含 UI,因此互動層完全自由發揮。
HTML 結構——準備三個部分:存放檔案資訊的容器、選擇檔案的按鈕、開始上傳的按鈕。
<div id="uploader" class="wu-example">
<div id="thelist" class="uploader-list"></div>
<div class="btns">
<div id="picker">選擇檔案</div>
<button id="ctlBtn" class="btn btn-default">開始上傳</button>
</div>
</div>
初始化
var uploader = WebUploader.create({
swf: BASE_URL + '/js/Uploader.swf',
server: 'https://webuploader.duapp.com/server/fileupload.php',
pick: '#picker', // 內部會依執行環境建立 input 或 Flash 元素
resize: false // 不壓縮圖片(預設 JPEG 會先壓縮再上傳)
});
顯示已選檔案——因為 WebUploader 不管 UI,要自己監聽 fileQueued:
uploader.on('fileQueued', function(file){
$list.append('<div id="' + file.id + '" class="item">'
+ '<h4 class="info">' + file.name + '</h4>'
+ '<p class="state">等待上傳...</p></div>');
});
上傳進度——uploadProgress 會帶入檔案物件與目前百分比:
uploader.on('uploadProgress', function(file, percentage){
var $li = $('#' + file.id), $percent = $li.find('.progress .progress-bar');
if (!$percent.length) {
$percent = $('<div class="progress progress-striped active">'
+ '<div class="progress-bar" role="progressbar" style="width: 0%"></div>'
+ '</div>').appendTo($li).find('.progress-bar');
}
$li.find('p.state').text('上傳中');
$percent.css('width', percentage * 100 + '%');
});
成功與失敗——失敗觸發 uploadError,成功觸發 uploadSuccess,不論結果如何,結束後都會觸發 uploadComplete:
uploader.on('uploadSuccess', function(file){
$('#' + file.id).find('p.state').text('已上傳');
});
uploader.on('uploadError', function(file){
$('#' + file.id).find('p.state').text('上傳出錯');
});
uploader.on('uploadComplete', function(file){
$('#' + file.id).find('.progress').fadeOut();
});
HTML:
<div id="uploader-demo"> <div id="fileList" class="uploader-list"></div> <div id="filePicker">選擇圖片</div> </div>
初始化時開啟自動上傳並限制只收圖片:
var uploader = WebUploader.create({
auto: true,
swf: BASE_URL + '/js/Uploader.swf',
server: 'https://webuploader.duapp.com/server/fileupload.php',
pick: '#filePicker',
accept: {
title: 'Images',
extensions: 'gif,jpg,jpeg,bmp,png',
mimeTypes: 'image/*'
}
});
監聽 fileQueued,用 uploader.makeThumb 產生縮圖。要注意這裡取得的是 Data URL,IE6、IE7 無法直接預覽,需要借助 Flash 或後端處理:
uploader.on('fileQueued', function(file){
var $li = $('<div id="' + file.id + '" class="file-item thumbnail">'
+ '<img><div class="info">' + file.name + '</div></div>'),
$img = $li.find('img');
$list.append($li);
uploader.makeThumb(file, function(error, src){
if (error) {
$img.replaceWith('<span>不能預覽</span>');
return;
}
$img.attr('src', src);
}, 100, 100); // 縮圖尺寸 100 x 100
});
接著同樣用四個事件處理狀態提示:
uploader.on('uploadProgress', function(file, percentage){
var $li = $('#' + file.id), $percent = $li.find('.progress span');
if (!$percent.length) {
$percent = $('<p class="progress"><span></span></p>').appendTo($li).find('span');
}
$percent.css('width', percentage * 100 + '%');
});
uploader.on('uploadSuccess', function(file){
$('#' + file.id).addClass('upload-state-done');
});
uploader.on('uploadError', function(file){
var $li = $('#' + file.id), $error = $li.find('div.error');
if (!$error.length) {
$error = $('<div class="error"></div>').appendTo($li);
}
$error.text('上傳失敗');
});
HTML:
<div id="uploader" class="wu-example">
<div class="queueList">
<div id="dndArea" class="placeholder">
<div id="filePicker"></div>
<p>或將照片拖到這裡,單次最多可選 300 張</p>
</div>
</div>
<div class="statusBar" style="display:none;">
<div class="progress"><span class="text">0%</span><span class="percentage"></span></div>
<div class="info"></div>
<div class="btns">
<div id="filePicker2"></div>
<div class="uploadBtn">開始上傳</div>
</div>
</div>
</div>
<link rel="stylesheet" type="text/css" href="/static/js/webuploader/css.css" />
<link rel="stylesheet" type="text/css" href="/static/js/webuploader/image.css" />
<script type="text/javascript" src="/static/js/webuploader/min.js"></script>
<script type="text/javascript" src="/static/js/webuploader/upload-image.js"></script>
JavaScript:
uploader = WebUploader.create({
pick: { id: '#filePicker', label: '點擊選擇圖片' },
dnd: '#uploader .queueList',
paste: document.body,
accept: {
title: 'Images',
extensions: 'gif,jpg,jpeg,bmp,png',
mimeTypes: 'image/*'
},
swf: '/static/js/webuploader/Uploader.swf',
disableGlobalDnd: true,
chunked: true,
server: '/point/image/bulk.html',
fileNumLimit: 300,
fileSizeLimit: 50 * 1024 * 1024, // 總量上限
fileSingleSizeLimit: 5 * 1024 * 1024 // 單檔上限
});
Java 端跟一般 Spring 檔案上傳沒有兩樣:
@RequestMapping("/bulk")
@ResponseBody
public String bulk(HttpServletRequest request, MultipartFile file) {
String path = super.uploadFile(request, "file", true);
return "1";
}
Spring MVC 從 3.2 起支援透過 Servlet 3.0 實作檔案上傳,需要在設定檔中註冊 multipartResolver:
<bean id="multipartResolver"
class="org.springframework.web.multipart.support.StandardServletMultipartResolver"></bean>
WebUploader 真正的強大之處在於「底層只管傳輸、UI 完全交給你」。建議的學習順序是:先跑通最簡單的上傳,再依需求逐一加入分片(chunked)、MD5 秒傳、進度客製與檔案去重。掌握 fileQueued、uploadProgress、uploadSuccess、uploadError、uploadComplete 這五個事件,九成的客製需求都能完成。