bootstrap-fileinput 是前端做檔案上傳時相當順手的一套元件,樣式預設就已經美觀,API 也夠彈性。本文以「專案封面圖片」為例,完整走過一次從頁面渲染、預覽、表單提交到 SpringMVC 端保存的實作過程,並釐清兩個常被誤解的配置項。


只需要樣式表、核心腳本以及中文語言包三個檔案:
<link type="text/css" rel="stylesheet" href="${ctx}/components/fileinput/css/fileinput.css" />
<script type="text/javascript" src="${ctx}/components/fileinput/js/fileinput.js"></script>
<script type="text/javascript" src="${ctx}/components/fileinput/js/fileinput_locale_zh.js"></script>
官方文件與下載位置:https://plugins.krajee.com/file-input。
<input type="file" name="image" class="projectfile" value="${deal.image}"/>
三個屬性各有分工:
type="file" 與自訂 class(這裡是 projectfile)用來標示這是一個檔案輸入框,同時方便後續用 jQuery 選取。name 決定後端接收時的參數鍵名。value 帶入既有圖片路徑,讓編輯頁能直接顯示原圖。projectfileoptions : {
showUpload : false,
showRemove : false,
language : 'zh',
allowedPreviewTypes : [ 'image' ],
allowedFileExtensions : [ 'jpg', 'png', 'gif' ],
maxFileSize : 2000,
},
// 文件上傳框
$('input[class=projectfile]').each(function() {
var imageurl = $(this).attr("value");
if (imageurl) {
var op = $.extend({
initialPreview : [ // 預覽圖片的設置
"<img src='" + imageurl + "' class='file-preview-image'>",
]
}, projectfileoptions);
$(this).fileinput(op);
} else {
$(this).fileinput(projectfileoptions);
}
});
幾個重點:
fileinput() 完成初始化。value 有值,透過 initialPreview 塞入既有的 <img>,即可實現「編輯時回顯」。showUpload 控制是否顯示上傳鈕,language: 'zh' 負責中文化。maxFileSize 的單位是 KB,2000 即 2MB。表單本身的寫法:
<form class="form-horizontal required-validate" action="${ctx}/save?callbackType=confirmTimeoutForward" enctype="multipart/form-data" method="post" onsubmit="return iframeCallback(this, pageAjaxDone)">
<div class="form-group">
<label for="" class="col-md-1 control-label">項目封面</label>
<div class="col-md-10 tl th">
<input type="file" name="image" class="projectfile" value="${deal.image}" />
<p class="help-block">支持jpg、jpeg、png、gif格式,大小不超過2.0M</p>
</div>
</div>
<div class="form-group text-center ">
<div class="col-md-10 col-md-offset-1">
<button type="submit" class="btn btn-primary btn-lg">保存</button>
</div>
</div>
</form>
兩個關鍵設定:
enctype="multipart/form-data" 是必要條件,少了它後端拿不到檔案內容。onsubmit="return iframeCallback(this, pageAjaxDone)" 以 iframe 方式模擬非同步上傳,成功後再交給回呼函式 pageAjaxDone 接手後續流程。回呼函式的職責是解析後端回傳的 JSON:先交給 YUNM.ajaxDone 統一處理錯誤訊息,若狀態碼為成功,就跳出一段提示並導向 forwardUrl。
function pageAjaxDone(json) {
YUNM.debug(json);
YUNM.ajaxDone(json);
if (json[YUNM.keys.statusCode] == YUNM.statusCode.ok) {
var msg = json[YUNM.keys.message];
// 彈出消息提示
YUNM.debug(msg);
if (YUNM.callbackType.confirmTimeoutForward == json.callbackType) {
$.showSuccessTimeout(msg, function() {
window.location = json.forwardUrl;
});
}
}
}
後端沿用專案既有的 SpringMVC 檔案保存流程即可,這裡不再重複贅述。
過去一直有個疑問:明明設了 allowedFileTypes 與 allowedFileExtensions,卻感覺毫無效果。有讀者提醒說,問題可能出在 fileinput() 被呼叫了兩次——一次在 fileinput.js 檔案末尾的自動初始化,一次是自己寫的那段;前者並沒有帶入這些屬性值。解法有兩種:把檔案末尾那幾行呼叫註解掉,或者乾脆全改用 data-* 屬性宣告、不再手動呼叫 fileinput()。
這個提醒很有價值,雖然最終沒有直接命中我的疑問,但這種有來有回的技術交流本身就相當珍貴。
官方定義是:allowedFileTypes 為一個陣列,用來限制允許上傳的檔案「類型」,預設 null 代表不限制。若遇到不合法的類型,會拋出 msgInvalidFileType 所設定的錯誤訊息。可用的類型有:
['image', 'html', 'text', 'video', 'audio', 'flash', 'object']
我原本以為設了這個屬性,系統檔案選擇視窗裡的「所有檔案」下拉選單會自動變成只顯示圖片:

邏輯聽起來沒錯,但 bootstrap-fileinput 並不是這樣運作的——它根本沒有去改動原生選擇視窗的過濾條件。於是我就誤判它「沒生效」。實際上,檢查發生在你選好檔案之後:

也就是說,它是「先讓你選,再驗」的事後檢查機制。
$(this).fileinput({
showUpload : false,
showRemove : false,
language : 'zh',
allowedPreviewTypes: ['image'],
allowedFileTypes: ['image'],
allowedFileExtensions: ['jpg', 'png'],
maxFileSize : 2000,
});
在 fileinput.js 中搜尋 allowedFileTypes,可以看到它先把設定取出來並組成人類可讀的字串:
var node = ctr + i, previewId = previewInitId + "-" + node, isText, file = files[i], caption = self.slug(file.name), fileSize = (file.size || 0) / 1000, checkFile, fileExtExpr = '', previewData = objUrl.createObjectURL(file), fileCount = 0, j, msg, typ, chk, fileTypes = self.allowedFileTypes, strTypes = isEmpty(fileTypes) ? '' : fileTypes.join(', '), fileExt = self.allowedFileExtensions, strExt = isEmpty(fileExt) ? '' : fileExt.join(', ');
接著才是逐項比對的迴圈:
if (!isEmpty(fileTypes) && isArray(fileTypes)) {
for (j = 0; j < fileTypes.length; j += 1) {
typ = fileTypes[j];
checkFile = settings[typ];
chk = (checkFile !== undefined && checkFile(file.type, caption));
fileCount += isEmpty(chk) ? 0 : chk.length;
}
if (fileCount === 0) {
msg = self.msgInvalidFileType.replace('{name}', caption).replace('{types}', strTypes);
self.isError = throwError(msg, file, previewId, i);
return;
}
}
真正的判斷邏輯寫在 defaultFileTypeSettings 裡:
defaultFileTypeSettings = {
image: function (vType, vName) {
return (vType !== undefined) ? vType.match('image.*') : vName.match(/\.(png|jpe?g)$/i);
},
...
從這段程式碼可以讀出三件事:
allowedFileTypes: ['image'] 時,走的是 MIME 比對,vType.match('image.*')。allowedFileExtensions 而不指定 allowedFileTypes,則會落到 vName.match(...) 那一支,也就是改為檢查副檔名。這一點是理解下一節的關鍵。把 allowedFileTypes 拿掉,只留副檔名白名單:
$(this).fileinput({
showUpload : false,
showRemove : false,
language : 'zh',
allowedPreviewTypes: ['image'],
allowedFileExtensions: ['jpg', 'png'],
maxFileSize : 2000,
});
此時若挑一張 gif 圖,就會如預期被攔下並顯示錯誤:

不過要特別留意,原始碼裡 image 類型的預設副檔名是包含 gif 的:
image: function (vType, vName) {
return (vType !== undefined) ? vType.match('image.*') : vName.match(/\.(gif|png|jpe?g)$/i);
},
本文為了示範而把它改成了 \.(png|jpe?g)$,實作時請依實際需求調整,別誤以為原始碼本來就沒有 gif。
以上就是完整的實作與原理梳理,希望對正在使用 bootstrap-fileinput 的人有幫助。