DIV CSS 佈局教程網

Bootstrap Fileinput 元件實戰:圖片預覽、AJAX 上傳與 SpringMVC 後端保存全流程
編輯:關於JavaScript     

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);
    }
});

幾個重點:

  • 先用 jQuery 撈出所有 file input,再逐一呼叫 fileinput() 完成初始化。
  • 若 value 有值,透過 initialPreview 塞入既有的 <img>,即可實現「編輯時回顯」。
  • showUpload 控制是否顯示上傳鈕,language: 'zh' 負責中文化。
  • maxFileSize 的單位是 KB,2000 即 2MB。

五、含檔案的表單以 AJAX 送出

表單本身的寫法:

<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>

兩個關鍵設定:

  1. enctype="multipart/form-data" 是必要條件,少了它後端拿不到檔案內容。
  2. 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 端保存圖片

後端沿用專案既有的 SpringMVC 檔案保存流程即可,這裡不再重複贅述。

七、關於「屬性沒作用」的誤會

過去一直有個疑問:明明設了 allowedFileTypes 與 allowedFileExtensions,卻感覺毫無效果。有讀者提醒說,問題可能出在 fileinput() 被呼叫了兩次——一次在 fileinput.js 檔案末尾的自動初始化,一次是自己寫的那段;前者並沒有帶入這些屬性值。解法有兩種:把檔案末尾那幾行呼叫註解掉,或者乾脆全改用 data-* 屬性宣告、不再手動呼叫 fileinput()。

這個提醒很有價值,雖然最終沒有直接命中我的疑問,但這種有來有回的技術交流本身就相當珍貴。

八、真正搞懂 allowedFileTypes

官方定義是:allowedFileTypes 為一個陣列,用來限制允許上傳的檔案「類型」,預設 null 代表不限制。若遇到不合法的類型,會拋出 msgInvalidFileType 所設定的錯誤訊息。可用的類型有:

['image', 'html', 'text', 'video', 'audio', 'flash', 'object']

我原本以為設了這個屬性,系統檔案選擇視窗裡的「所有檔案」下拉選單會自動變成只顯示圖片:

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

也就是說,它是「先讓你選,再驗」的事後檢查機制。

allowedFileTypes 的運作原理

$(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.*')。
  • 上傳 .txt 檔之所以被擋下,就是因為它的 type 不是 image 開頭。
  • 如果只指定 allowedFileExtensions 而不指定 allowedFileTypes,則會落到 vName.match(...) 那一支,也就是改為檢查副檔名。這一點是理解下一節的關鍵。

allowedFileExtensions 何時生效

把 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 的人有幫助。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved