【Bootstrap】bootstrap-fileinput上傳文件插件

【bootstrap-fileinput】

　　官方文檔：http://plugins.krajee.com/file-input

　　這是個據傳最好用的bootstrap相關聯的文件上傳控件，支持拖曳上傳，多線程上傳，上傳文件預覽等等功能。

　　首先仍是說一下要引入的一些文件：

<link href="{% static 'bootstrap-fileinput/css/fileinput.min.css' %}" rel="stylesheet" /> <script src="{% static 'bootstrap-fileinput/js/fileinput.min.js' %}"></script> <script src="{% static 'bootstrap-fileinput/js/locales/zh.js' %}"></script>

 

 

　　一樣也須要jquery和bootstrap的支持。

　　■　　基本使用

　　HTML：

<!-- 就是一個簡單的文件表單字段 --> <label class="control-label" for="testfile">上傳文件</label> <input type="file" id="testfile" name="test" multiple />

 

　　JS：

$('#testfile').fileinput({
    language: 'zh', uploadUrl: location.pathname + 'upload/', showCaption: true, showUpload: true, showRemove: true, showClose: true, layoutTemplates:{ actionDelete: '' }, browseClass: 'btn btn-primary' });

 

　　經過這樣的初始化獲得的上傳組件大概是這樣子的：

咱們姑且把顯示一個個文件的虛線區域稱爲文件區，每一個文件標識稱爲文件縮略圖

　　而後來解釋一下各個參數的含義：

　　language指出國際化顯示的語言環境，須要locales下面響應的js文件的支持；uploadUrl指出了點擊上傳以後會將上傳文件的這個post請求發向哪一個url。（uploadUrl這個參數其實還牽扯到了fileinput支持的兩種不一樣的上傳方式——form上傳和ajax上傳，在配置了uploadUrl時默認就是選擇了ajax上傳方式。fileinput對於ajax方式的上傳支持更好，而拖曳上傳等功能也只有在ajax上傳方式中才奏效。關於具體的兩種上傳方式的區別後面再說，如今先默認全部操做都是基於ajax方式上傳來作的。）

　　showCaption　　默認true，設置爲false時將不顯示下面那個相似於input[type=text]那樣的顯示框（然而這個顯示框並不能直接編輯，它只是顯示了文件名等信息）

　　showUpload　　默認true，設置爲false是不顯示右下角那個上傳按鈕

　　showRemove　　默認爲true，設置爲false時不顯示右下角移除按鈕

　　showClose　　默認爲true，設置爲false時不顯示右上角的小叉（這個叉的做用就是移除當前全部文件區中的文件）

　　以上這些都是一些非文件區內的顯示調整

　　layoutTemplates和文件縮略圖的樣式相關，暫且先不談

　　browseClass指出了右下角選擇按鈕的樣式。通常儘可能不要用btn-sm和btn-lg，會和左邊的輸入框不協調。

　　●  更多初始化參數

　　showPreview　　默認true，設置爲false時默認不顯示整個文件區，天然就沒法拖曳文件進行上傳了。

　　showCancel　　默認true，只在ajax上傳模式中可用，在上傳過程當中右下角有一個取消按鈕，能夠取消上傳

　　showUploadedThumbs　　默認爲true，這個屬性是基於這樣一個使用方法的：選擇若干個文件後點擊右下角上傳按鈕批量上傳，待所有完成後再選擇一批文件，此時以前上傳成功的文件是否要保存。就是這個屬性控制的。注意，點擊文件縮略圖下面的上傳按鈕不會致使以前的成功上傳的文件消失，即便這裏設置了true

　　showBrowse　　fileinput支持部分文件格式（如各類圖片格式，txt，pdf等）的預覽，點擊縮略圖的右上角按鈕便可，這個就是控制是否顯示這個按鈕的。

　　autoReplace,maxFileCount　　這兩個屬性配合一塊兒使用，便可以設置一個文件區存放的最多文件的數量，當要處理的文件個數超過這個數量時自動只選取最後的那幾個進行展現和處理。

　　captionClass/previewClass/mainClass/frameClass　　這四個class參數能夠爲各自部分增長一些class屬性、mainClass針對元素.file-caption-main，frameClass針對每一個縮略圖的框架。

　　initialPreview　　經過這個參數，咱們能夠爲文件區設置一些默認的縮略圖。一般能夠用於一些附帶的默認要上傳的文件。參數的值寫html代碼便可，不過爲了和其餘部分統一，咱們要用file-preview-image,file-preview-text等fileinput預設的class。代碼實例能夠參考官方文檔【http://plugins.krajee.com/file-input/plugin-options#initialPreview】。事實上，initialPreview這一塊內容是很豐富的，也有不少不少相關的參數可使用。這個主要是用於當須要直接從後端讀取一些文件數據展現給前端，而且容許前端進行新增或刪除操做時使用。這種場景其實已經超越了普通的文件上傳表單的意義了。就不詳細敘述。等到要用的時候再研究吧

　　

　　●  layoutTemplates

　　這個參數內容也比較多，因此單獨拿出來講一下。這個參數的值應該是一個object，而object中的各個鍵值對指出了一個整個fileinput組件的各類樣式。上面的基本應用示例中的actionDelete其實就是指縮略圖上的刪除按鈕。如像我同樣設置成了''（空值），則文件縮略圖上就不會顯示刪除按鈕了。從觀念上來講，咱們能夠把各個鍵值對的值當作是一個模板性質的東西，改變相應的模板天然就能夠渲染出相應的內容了。

　　既然有模板，那麼確定就有模板變量和有必定語法的模板語言。fileinput裏面有一種叫作tag的機制，即在模板中會出現相似{variable}的變量，能夠被具體內容替換。而模板之間是能夠嵌套的。好比layoutTemplates.footer中有{actions}這個變量：

    footer: '<div class="file-thumbnail-footer">\n' +
        '    <div class="file-caption-name" style="width:{width}">{caption}</div>\n' +
        '    {progress} {actions}\n' +
        '</div>',

，其內容是actions模板，而這個模板中又含有{upload}，{download}等變量：

    actions: '<div class="file-actions">\n' +
        '    <div class="file-footer-buttons">\n' +
        '        {upload} {download} {delete} {zoom} {other}' +
        '    </div>\n' +
        '    {drag}\n' +
        '    <div class="file-upload-indicator" title="{indicatorTitle}">{indicator}</div>\n' +
        '    <div class="clearfix"></div>\n' +
        '</div>',

有了模板機制，可讓咱們自由地選擇再哪一個層面的組件上進行模板的修改，而後模板系統會自動將這種改變傳遞給全部長輩模板，很是方便。由於咱們不設置layoutTemplates參數也能渲染出一個界面來，說明這些模板中的全部變量（遞歸到最底層）都是有默認值的，這些默認值能夠在這裏看到：【http://plugins.krajee.com/file-input/plugin-options#layoutTemplates】。同時在修改模板時也要注意，除非有十足的把握，不然應該儘可能不動這個模板中本來就有的那些變量。若是在改後的模板中少寫了某個變量，就意味着這個變量指代的內容將不會被體現出來。

　　上面示例中給出的actionDelete相對仍是比較低層級的模板，下面咱們從高到低梳理一下各個層級的模板，部分模板沒有變量，代表其是一個相對獨立的模板：

　　main1　　帶有caption的渲染模板

　　main2　　不帶caption的渲染模板

　　preview　　文件區的渲染模板

　　fileIcon　　caption中在文件名前面那個圖標，默認glypyhicon-file

　　caption　　caption的渲染模板

　　modal　　modal的渲染模板（這個模態對話框在預覽文件內容時出現）

　　progress　　進度條的渲染模板，包括總進度條和每個縮略圖中進度條

　　size　　含有{sizeText}變量，文件縮略圖中文件大小部分信息的渲染模板

　　footer　　含有{actions}變量等。

　　actions　　含有{upload}、{download}、{delete}等變量，這三個變量分別表明了actionUpload,actionDownload和actionDelete三個模板的內容。

　　以actionDelete爲例：

　　　　actionDelete裏面還有removeClass，removeIcon，removeTitle等變量。這三個變量比較特殊，是在fileActionSettings裏面進行設置的。

　　

　　內容還有不少不少。。。我不想寫了。總之就是看文檔看文檔

　　還有一個previewTemplates，是文件預覽界面跳出來的模態框的樣式設置， 很少說了。。

 

　　●   好的，繼續來看其餘的初始化參數

　　previewSettings　　這個參數能夠爲不一樣類型的文件設置預覽時不一樣的CSS，同這個系列的也還有不少

　　allowedFileTypes　　一個數組，指出哪些類型的文件纔是被接受上傳的，儘可能不要同時設置allowedFileTypes和allowedFileExtensions兩個參數

　　allowedFileExtensions　　一個數組，指出帶有哪些後綴名的文件纔是被接受上傳的，設置msgInvalidFileExtension能夠個性化出現此錯誤時的錯誤信息

　　previewFileIcon　　當文件沒法被預覽時出如今縮略圖中的圖標，默認是<i class="glyphicon glyphicon-file"></i>

       previewFileIconSettings　　能夠將不一樣的後綴的文件有不一樣的縮略圖圖標

　　uploadExtraData　　剛纔說過，若是使用ajax上傳的話，能夠設置這個屬性來上傳一些其餘的數據。這個是一個object。

　　minFileSize/maxFileSize　　指出上傳支持的最小/最大的文件大小，同時能夠設置msgFileTooSmall和msgFileTooLarge個性化報錯信息

　　minFileCount/maxFileCount　　指出上傳最少/多幾個文件，若設置成0則表示沒有限制。默認是0

　　msgPlaceholder　　默認是Select {files} ，表明了caption中的placeholder。若是是中文環境最好改一下，由於Select這個是沒辦法本身消除的。

　　msgFileRequired　　當要求文件可是沒上傳時的報錯信息

　　關於msg的還有不少參數好比太多太少，太大過小，沒找到文件，文件不可讀等等，不一一列舉。

　　dropZoneEnabled　　是否有拖曳文件上傳區，和showPreview的區別在於，上傳以後用戶仍是能看到文件縮略圖，只是單純不能拖曳上傳了。

　　

　　●  fileActionSettings

　　最上面的那些show都是在縮略圖外面的，如今來講說縮略圖裏面的一些東西要怎麼控制顯示隱藏：

　　showUpload，showDownload，showRemove，showZoom等就不說了

　　showDrag　　顯示拖動按鈕（只適用於initialPreview的部分）

　　uploadIcon/uploadTitle/uploadClass　　上傳按鈕相關的屬性

　　download/remove/drag/zoom也有上面這三個

　　

　　篇幅有些過長了。。關於fileinput的方法、事件以及兩種上傳方法的比較另開一片寫

 ■　　fileinput相關方法

　　經過$('#testfile').調用下列方法：

　　fileinput('disable/enable')　　禁用/啓用文件上傳

　　fileinput('reset/clear')　　清空待上傳/全部文件（待上傳就是說不包括已經上傳的和initialPreview部分的縮略圖）

　　fileinput('destroy')　　將文件上傳部分變回默認樣式的上傳表單字段

　　fileinput('refresh',{somenewconfig:value})　　這個方法能夠動態增長或改變初始化參數，好比fileinput('refresh',{showCaption:false})這樣子

　    fileinput('upload')　　經過方法觸發上傳，這隻適用於ajax上傳方法。這個按鈕至關於上傳前caption右邊那個上傳按鈕的事件

　　fileinput('lock/unlock')　　這個比較有意思，會鎖定/解鎖fileinput組件（鎖定指將各類刪除/上傳/預覽/瀏覽等按鈕disable掉，而且放出一個取消按鈕，點擊取消可手動解鎖）

　　fileinput('getFileStack')　　首先要了解什麼是file stack。這個是待上傳文件的一個棧，能夠經過fileinput('addToStack/updateStack/clearStack')等方法進行改變。只是這些方法操做的對象是文件對象，不知道怎麼在javascript中表示。。可是getFileStack這個方法是能夠的，它就是返回了一個列表，其中是待上傳的文件的棧。相似的getFilesCount能夠返回當前待上傳的文件的個數

　　fileinput('getFrames')　　返回全部縮略圖的jquery對象的列表。比較有意思的是，針對不一樣的狀態（好比上傳成功和失敗），縮略圖會有file-preview-success和file-preview-error這種class，咱們能夠基於這個class的存在狀況來進行一些判斷的

　　

■　　fileinput相關事件

　　經過$('#testfile').on('事件名',functionxx)來綁定事件和相關的響應函數，事件包括：

　　change　　當文件選擇中新增了文件（注意只有新增能夠）觸發

　　fileselect　　當用戶打開選擇文件的對話框觸發，不管其最終是否真的選中若干個文件仍是點擊了取消，這個事件都會被觸發。

　　filebatchselected　　當用戶選擇了多於一個文件時觸發的事件，綁定的函數上除了event還能夠有files參數，傳入的值是被選擇的文件對象的列表

　　fileclear/filecleared　　當用戶點擊叉號或者移除按鈕清空文件區時fileclear被觸發，當全部縮略圖被順利刪除以後filecleared被觸發

　　fileloaded　　當一個文件被順利加載到文件區，準備被上傳時觸發。響應函數有4個附加參數，依次是file（文件對象）,previewId（縮略圖的id），index（該文件在這批上傳文件中的index），reader（文件讀取流實例）

　　filepreremove　　當點擊縮略圖上的刪除按鈕，一個文件縮略圖被刪除時觸發，兩個附加參數是id和index

　　fileuploaded　　在ajax上傳的時候，每一個縮略圖表明的文件被成功上傳以後觸發的事件，有三個附加參數，data，previewId和index。data略複雜一些，是一個object，包含了字段：

　　　　form　　表單數據

　　　　files　　文件對象的列表

　　　　filenames　　文件名的列表

　　　　filescount　　上傳的文件個數

　　　　extra　　uploadExtraData中上傳上去的數據

　　　　response　　ajax返回

　　　　reader　　文件讀取流對象

　　相似的還有一個filebatchuploadsuccess，是在批量上傳文件成功後觸發的事件。以上是正常或者成功時觸發的事件，下面介紹一些失敗的事件

　　fileuploaderror　　當客戶端驗證文件出錯或上傳出錯時觸發，附加參數data，是個object。含有字段：

　　　　id　　出錯文件縮略圖的id

　　　　index

　　　　file　　出錯文件的文件對象

　　　　reader

　　　　files　　文件對象數組

 

■　　兩種不一樣的上傳方式

　　內容確實比較多。。其實這塊內容應該放在上面講，已經很後面了。正如以前所說，存在兩種不一樣的上傳文件方式，即form上傳和ajax上傳。

　　對於ajax上傳方式來講，是否上傳成功是須要後臺返回特定格式的數據來斷定的。好比至少後臺返回的數據應該是一個JSON串而且帶有error字段，當error字段爲空時默認上傳成功。