先認識 plupload
Plupload 出自 TinyMCE 團隊,為 CMS 與各類上傳情境提供了高度可用的外掛。它拆成核心 API 與 jQuery 上傳佇列元件兩塊,你可以整套拿去用,也可以只取核心自行打造介面。
為什麼會需要它?原本專案用的是 uploadify,一切平靜,直到客戶提出「我要用 iPad 操作系統並上傳圖片」。uploadify 依賴 Flash,在 iOS 與 macOS 上完全不能用。而 plupload 的 HTML5 引擎正好解決了這個問題,上手難度也不高。
<script type="text/javascript" src="js/jquery-1.9.1.min.js"></script> <!-- art dialog --> <script type="text/javascript" src="artdialog/artDialog.source.js?skin=blue"></script> <!-- plupload --> <script type="text/javascript" src="plupload/plupload.full.js"></script>
<!-- 觸發彈出框 -->
<a id="uploadBtn" class="optionbtn inline" href="#">文件上傳</a>
<div id="uploadContent" style="display:none;height:300px;
overflow-x:hidden;overflow-y:auto;">
<div id="choosefile">
<span>單個文件支持小於 100M</span><br/>
<a id="uploadify" href="javascript:void(0);">選擇文件</a>
</div>
<div id="uploadfileQueue" style="border: 1px solid #a7c5e2;
height: 228px; width: 350px;"></div>
</div>
<pre id="console"></pre>
var globalUploader;
function _plupload() {
var uploader = new plupload.Uploader({
runtimes : 'html5,flash,silverlight,html4',
browse_button: 'uploadify', // 瀏覽檔案的 DOM id
container: 'uploadContent', // 包含 browse_button 的容器
url: '/uploadAction!localUpload.action',
flash_swf_url : '/folder/js/plupload/Moxie.swf',
silverlight_xap_url : '/folder/js/plupload/Moxie.xap',
filters : {
max_file_size : '100mb',
mime_types: [ { title : "Image files", extensions : "jpg,gif,png" } ]
},
init: {
PostInit: function () {
$('#uploadfileQueue').html('');
},
// 點擊上傳按鈕後、實際送出前觸發。
// 這裡示範先向後端詢問一個不重複的檔名,再連同其他資訊塞進表單參數
BeforeUpload : function (up, file) {
$.ajax({
url: "/folder/personal/personalAction!getNewFileName.action",
type: "POST",
async: false,
data: { 'upFileName': file.name, 'globalPid': globalPid },
dataType: "json",
success: function (data) {
up.setOption('multipart_params', {
upFileName : data.newFileName,
upFileType : file.name.split(".").pop(),
upFileSize : file.size,
parentId : globalPid
});
},
error: function () {
messageAlert("對不起,檔案[" + file.name + "]上傳準備失敗", '');
}
});
},
// 檔案加入佇列時,動態組出列表項目
FilesAdded: function (up, files) {
var i = 0;
plupload.each(files, function (file) {
$('#uploadfileQueue').append(
'<div id="' + file.id + '" class="uploadify-queue-item">' +
'<div class="cancel"><a href="javascript:_plupload_removeFile(' +
i + ',\'' + file.id + '\')"></a></div>' +
'<span class="fileName">' + file.name + ' (' +
plupload.formatSize(file.size) + ')</span><b></b>' +
'<div class="uploadify-progress">' +
'<div class="uploadify-progress-bar"></div></div>' +
'</div>'
);
i++;
});
},
// 上傳過程中持續回報百分比
UploadProgress: function (up, file) {
document.getElementById(file.id)
.getElementsByTagName('b')[0].innerHTML =
'<span>-' + file.percent + "%</span>";
$('#' + file.id).find('.uploadify-progress-bar')
.css('width', file.percent + '%');
},
Error: function (up, err) {
document.getElementById('console').innerHTML +=
"\n錯誤 #" + err.code + ": " + err.message;
},
FileUploaded: function (up, file, info) {
var data = eval("(" + info.response + ")");
// 這裡可更新畫面上的檔案狀態
},
UploadComplete: function (up, files) {
// 全部檔案上傳完畢
}
}
});
uploader.init();
globalUploader = uploader;
}
// 用 artDialog 包裝成彈窗,並在按鈕中控制佇列的清空
function popUpDialog() {
artDialog({
id: 'file-upload',
title: '文件上傳',
fixed: true,
lock: true,
content: $("#uploadContent")[0],
button: [
{ name: '開始上傳', focus: true, callback: function () {
globalUploader.start();
return false;
}},
{ name: '關閉', callback: function () {
$('#uploadfileQueue').html('');
globalUploader.files.splice(0, globalUploader.files.length);
return true;
}}
],
close: function () {
$('#uploadfileQueue').html('');
globalUploader.files.splice(0, globalUploader.files.length);
}
});
}
$(function () {
$('#uploadBtn').click(function () { popUpDialog(); });
_plupload();
});
後端這裡以 Struts2 的 Action 為例,用 private File file 接收檔案——參數名稱必須與表單欄位一致,否則會收到 null。

<style type="text/css">
#uploadfileQueue {
position: relative; left: 0; top: 0;
border: 1px solid #a7c5e2; margin-bottom: 5px;
height: 228px; width: 350px;
overflow-x: hidden; overflow-y: auto;
}
.uploadify-queue-item {
background-color: #FFF;
-webkit-border-radius: 3px;
-moz-border-radius: 3px;
border-radius: 3px;
font: 11px Verdana, Geneva, sans-serif;
margin: 5px; max-width: 350px; padding: 10px;
}
.uploadify-progress { background-color: #E5E5E5; margin-top: 10px; width: 100%; }
.uploadify-progress-bar { background-color: #0099FF; height: 3px; width: 1px; }
</style>

.uploadify-queue-item .cancel a {
background: url('js/uploadify-cancel.png') 0 0 no-repeat;
float: right; height: 16px; text-indent: -9999px; width: 16px;
}
官方 API 雖然提供了 removeFile(file),但在這個情境下效果不如預期,因此改用陣列的 splice(num, length) 直接從佇列中移除:
function _plupload_removeFile(removeNum, fileId) {
globalUploader.files.splice(removeNum, 1); // 從第 removeNum 個開始刪 1 個
$(fileId).fadeOut();
}

至此,一個具備跨平台能力、進度條與佇列刪除的上傳元件就完成了。相比依賴 Flash 的舊方案,plupload 的 HTML5 引擎讓 iPad、Mac 與行動裝置都能正常使用,這正是換掉舊元件的關鍵理由。