bootstrap-fileinput詳細說明與使用

介紹

bootstrap-fileinput是一款非常優秀的HTML5文件上傳插件，支持文件預覽、多文件上傳等一系列特性。

一款非常優秀的HTML5文件上傳插件，支持bootstrap 3.x 和4.x版本，具有非常多的特性:多文件類型上傳。這個插件能最簡單的幫你完成文件上傳功能，且使用bootstrap樣式。還支持多種文件的預覽，images, text, html, video, audio, flash。另外還支持ajax方式上傳文件，可以看到上傳進度。支持拖拽的方式添加和刪除文件。

插件特性

注意

這個插件的最新版本是v4.4.0（開發中）。 有關詳細信息，請參閱更改日誌。 插件特性主要有兩方面：

文件輸入特性

1、  該插件將一個簡單的HTML文件輸入轉換爲高級文件選擇器的控件。在不支持JQuery或Javascript的瀏覽器中將幫助回退到普通HTML文件輸入。

2、  文件輸入由以下三個部分組成，每個部分都包含用於控制顯示的選項和模板：

• 文件標題部分：顯示所選文件的簡要信息。
• 文件操作按鈕部分：瀏覽，刪除和上傳文件。
• 文件預覽部分：在客戶端上顯示所選文件進行預覽（支持預覽圖像，文本，Flash和視頻文件類型）。其他文件類型將顯示爲默認的縮略圖。

3、  如果設置<input>標籤的class屬性爲file，該插件將自動將它轉換爲type屬性爲file的高級文件輸入選擇器。高級文件輸入選擇器的所有參數都可以通過HTML5的data-*屬性傳遞。

4、  能夠選擇和預覽多個文件。使用HTML5文件閱讀器API來讀取和預覽文件。在選擇多個文件的情況下顯示正在加載到預覽區域的每個文件的進度。

5、  提供預定義的模板和CSS類，可以根據您的需要更改您的文件輸入顯示風格。

6、  能夠配置插件初始化具有初始標題的images/files類型文件預覽 （對於記錄更新場景很有用）。initialPreview、 initialPreviewConfig 和initialCaption 屬性來配置它。

7、  能夠將簡要預覽內容縮放爲詳細預覽。在預覽中查看縮放內容的幻燈片，最大限度地實現無邊界或全屏預覽。

8、  能夠通過拖放操作在初始預覽中對內容進行排序/重排。

9、  能夠完全主題化控件，並控制樣式和佈局。

10、 通過語言/翻譯支持同一頁面上的多語言控件。

11、 顯示/隱藏任何或所有以下內容的選項：

12、自定義顯示整個插件，標題容器，標題文本，預覽容器，預覽圖像和預覽狀態的目標容器元素的位置。

13、 對於文本文件預覽，將文本自動縮隱爲縮略圖寬度，並顯示一個縮略指示器鏈接，以便在懸停時顯示完整的文本。您可以自定義縮略符（默認爲...）。

14、 自定義預覽，進度和所選文件的消息。

15、上傳操作默認爲表單提交。支持用於自定義基於ajax的上傳的route/server上傳動作參數。

16、 觸發JQuery事件進行高級開發。目前可用的事件有filereset、fileclear、filecleared、fileloaded，和fileerror。

17、 支持輸入禁用文件和只讀文件。

18、 動態自動調整文件名長度超過容器寬度的文件標題。

19、 當預覽容器上完全載入圖像後，觸發的新的fileimageuploaded事件。

20、 當預覽圖超過預覽容器的大小時自動調整預覽圖像。

21、 完全模板化和可擴展，允許開發人員以自己想要的方式配置文件輸入。

22、 基於各種文件預覽類型智能化預覽。內置的文件支持類型分類爲image、text、html、video、audio、flash、object和other。

23、allowedPreviewTypes:你可以配置哪些文件類型被允許預覽顯示。默認值爲['image', 'html', 'text', 'video', 'audio', 'flash', 'object']。因此，默認情況下，所有文件類型都將被視爲要預覽的對象。 舉個例子，如果只想展示圖像和視頻的預覽，就將這個參數設置爲['image', 'video']。如果要禁用所有文件類型的內容預覽，並用預覽圖標代替縮略圖，請將其設置爲null、empty或false。

24、allowedPreviewMimeTypes:除了參數allowedPreviewTypes，你還可以控制哪些互聯網媒體類型可以預覽。它的默認值爲null，表示支持所有互聯網媒體類型。請注意： 使用版本2.5.0，你可以通過設置allowedFileTypes和allowedFileExtensions參數來控制允許上傳的文件類型或擴展功能。

25、 layoutTemplates:允許你通過一個屬性來配置所有佈局模板設置。可配置的佈局對象有：main1、main2、preview、caption和 modal。

26、 previewTemplates:所有用於每個預覽類型的預覽模板已被組合成一個屬性，而不是單獨用於圖像，文本等內容的模板。表示格式的鍵爲allowedPreviewTypes，值表示預覽模板。下面是每個預覽文件類型（generic、image、text、html、video、audio、flash, object和other）。generic模板僅用於使用直接的標籤來展示initialPreview內容。

27、previewSettings:允許你爲每個預覽圖像類型配置寬度和高度。該插件對每個類型都具有默認的寬度和高度預定義，這些類型有image、text、 html、video、audio、flash和 object。

28、 fileTypeSettings:允許你使用回調函數配置和識別每個預覽文件類型。該插件有默認的回調函數預定義來識別不同類型，這些類型有image、text、 html、video、audio、flash和 object。

29、使用模板替換標籤已被增強。使用此版本，它將自動檢查每個多次出現的標籤替換的爲模板字符串。

30、操作事件，並輕鬆地在任何中止上傳的事件返回的輸出中添加您自己的自定義驗證消息。

31、支持翻譯和語言環境。

注意

Flash預覽需要安裝Shockwave flash並且客戶端瀏覽器支持它。Flash預覽目前只能與webkit瀏覽器成功運作。支持HTML5 video/audio標籤的所有現代瀏覽器都支持視頻和音頻格式預覽。請注意，瀏覽器的HTML5視頻元素支持的視頻/音頻格式數量有限（例如mp4，webm，ogg，mp3，wav）。視頻文件推薦使用小視頻（通過maxFileSize 屬性進行控制），這樣不會不影響預覽效果。你可以從插件庫的examples目錄下複製幾個文件，來測試一些Flash和視頻文件的示例。

文件上傳特性

伴隨着版本4.0.0，插件現在也包括內置AJAX上傳支持和有選擇地添加或刪除文件。AJAX上傳功能基於HTML5 FormData和XMLHttpRequest Level 2標準。大多數現代瀏覽器都支持此標準，但插件在不支持的瀏覽器中將自動降級爲正常格式提交。

1. 添加AJAX功能，基於HTML5 FormData大多數現代瀏覽器支持）上傳方式。如果不支持，將降級到正常的基於表單的文件提交。
2. 要使用AJAX上傳，必須設置uploadUrl屬性。
3. 增強插件，現在允許添加，附加，刪除文件（基於許多的反饋）。因此，可以附加文件到預覽。
4. 可以通過DRAG & DROP區域來拖放和附加文件。New DRAG & DROP zone available in preview to drag and drop files and append.
5. 逐個或批量刪除、上傳文件。
6. 如果showPreview設置爲false，或者未設置uploadUrl，插件將降級到基於正常的form形式上傳。
7. 可配置指示燈來同步文件等待上傳，文件成功上傳，文件上傳錯誤狀態。
8. 能夠添加額外的表單數據到基於ajax的上傳中。
9. 上傳進度條和單個縮略圖的上傳標識。
10. 能夠取消和中止正在進行的AJAX上傳。
11. 建立初始預覽內容（例如保存的圖像庫）。您可以設置初始預覽操作（預定義支持預先預覽刪除）。也可以設置其他自定義操作按鈕初始化預覽縮略圖。
12. 確保插件仍然尺寸精簡，並最佳地利用HTML5和jquery功能優化上述功能的性能。
13. 一旦ajax上傳完成，就自動從服務器上刷新預覽內容。

安裝

可以使用以下方法之一自動或手動安裝該插件：

Bower包管理器

通過bower包管理器進行安裝，運行下面簡單的指令：

$ bower install bootstrap-fileinput

Composer包管理器

通過Composer包管理器進行安裝，運行指令：

$ php composer.phar require kartik-v/bootstrap-fileinput "dev-master"

或者添加：

"kartik-v/bootstrap-fileinput": "dev-master"

到你的composer.json文件中。

依賴項

1. Bootstrap 3.X。但是，可以使用任何CSS框架模板來定製插件。
2. 最新的JQuery
3. 大多數支持HTML5文件輸入和FileReader API的現代瀏覽器，包括對CSS3和JQuery的支持。
4. 爲了正常使用文件預覽功能，瀏覽器必須支持HTML5 FileReaderAPI，否則插件會自動降級到普通的表單文件輸入。對於Internet Explorer，必須使用IE 10及更高版本。IE9及以下版本將作爲普通文件輸入，並且不支持多個文件選擇和HTML5 FileReader API。
5. 版本4.0支持AJAX上傳。AJAX上傳要求瀏覽器支持HTML5 FormData和XHR2（XMLHttpRequest 2）。大多數現代瀏覽器支持FormData和XHR2。該插件在不支持AJAX上傳的瀏覽器中將自動降級到正常表單提交。

瀏覽器支持

該插件使用HTML5功能來實現各種功能。大多數現代瀏覽器支持這些功能。但是，要知道你的瀏覽器是否支持這些功能，你必須在下面運行這些檢查。以下是檢測瀏覽器是否支持

功能	描述	支持
文件輸入多個	允許用戶使用本機HTML文件輸入選擇多個文件	瀏覽器
HTML5文件API	允許使用插件在預覽窗格上閱讀和預覽文件	瀏覽器
HTML5 XHR2和FormData	允許使用ajax上傳功能來附加/刪除文件並使用進度條進行跟蹤。	瀏覽器
HTML5拖放	能夠將文件拖放到一個Dropzone（僅適用於使用HTML5 XHR2的ajax上傳）	瀏覽器
HTML5畫布	通過JavaScript管理圖像文件。如果你希望在上傳之前調整圖像文件的大小，則必需支持此功能。	瀏覽器

 

 

 

 

 

 

 

 

 

 

 

使用模式

大多數情況下，該插件可以配置爲以下兩種不同的模式之一進行上傳。

重要信息：不要嘗試組合下列模式來接收文件數據，因爲您將收到不一致和/或錯誤的輸出。

1、表單提交：在此模式下，您不能設置uploadUrl屬性。該插件將使用本地文件輸入來存儲文件，並且可以在正常的from提交後讀取文件（您必須在form中包含類型爲file的input標籤）。這對於單個文件上傳或簡單的場景多個文件上傳是有用的。配置非常簡單，你可以從本機表單提交中讀取POSTED的所有數據。但是，請注意，本地文件輸入是隻讀的，不能被外部代碼修改或更新。特別是對於多個文件輸入選擇，無法將單個文件增加到已選擇的文件列表。如果嘗試在已選擇的文件輸入按鈕上再選擇文件，它將覆蓋並清除之前選擇的文件。同樣，在此模式下，無法選擇移去/刪除上傳之前添加的文件。

2、Ajax提交：在此模式下，你必須將uploadUrl屬性設置爲有效的ajax處理服務器action/URL。如果uploadUrl設置了，那麼該插件會自動爲該場景使用ajax上傳。該插件提供了ajax提交的高級功能，這是表單提交提供不了的。如拖放文件，在預覽區域中添加/刪除文件，獲取上傳的進度條等功能只有在此模式下纔可以實現。您的瀏覽器必須支持HTML5 FormData/XHR2才能正常工作，並且處理ajax調用的服務器代碼必須返回有效的JSON響應。

注意 作爲高級場景，插件允許你處理ajax上傳，即使沒有選擇文件，但是使用有效的uploadExtraData也會得到ajax響應。這些事件filebatchpreupload、filebatchuploadsuccess、filebatchuploadcomplete或 filebatchuploaderror將在這種情況下觸發。即使沒有任何的文件數據，它將允許發送額外的數據。

功能/要求	表格提交	Ajax提交
支持單個和多個文件上傳	支持	支持
使用HTML 5 FileAPI預覽文件	支持	支持
通過表單提交直接讀取文件	支持	不支持
每個預覽縮略圖的單個文件刪除圖標	支持 1	支持2
每個預覽縮略圖的個人文件上傳圖標	不支持	支持
需要從服務器返回有效的JSON響應	不支持	支持
需要瀏覽器支持HTML5 FormData / XHR2	不支持	支持
服務器代碼來處理ajax併發送JSON Response	不支持	支持
使用放置區拖放文件	不支持	支持
能夠將文件附加到已選擇的列表	不支持	支持
能夠將文件刪除到已選擇的列表	支持 1	支持
上傳進度欄	不支持	支持
閱讀其他表單數據	直接通過表單提交	通過 uploadExtraData

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

模式比較

• 1 -通過initialPreviewConfig（僅適用於服務器上傳的文件）。
• 2 - 在運行環境中對服務器上傳的文件（通過initialPreviewConfig）和客戶端選擇的文件。

用法

注意

如果你將一個css class='file'屬性賦予input標籤，插件將自動把字段[input type="file"]轉換爲文件輸入控件。但是，如果你想通過javascript單獨初始化插件，那麼請勿將css class='file'屬性附加到'input'上（因爲這將導致重複的初始化，並且JavaScript代碼可能會被跳過不執行）。

步驟1

在網頁頭部加入鏈接。

<link href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css" rel="stylesheet">

<link href="path/to/css/fileinput.min.css" media="all" rel="stylesheet" type="text/css" />

<script src="//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>

<!-- 如果你想在上傳之前修改圖片大小需要加入canvas-to-blob.min.js  它必須在fileinput.min.js之前引入 -->

<script src="path/to/js/plugins/canvas-to-blob.min.js" type="text/javascript"></script>

<!-- 如果你想在最初的預覽中排序/重新排列需要引入sortable.min.js  它必須在fileinput.min.js之前引入 -->

<script src="path/to/js/plugins/sortable.min.js" type="text/javascript"></script>

<!-- 如果你想在HTML文件預覽中淨化HTML內容則要引入purify.min.js is   它必須在fileinput.min.js之前引入 -->

<script src="path/to/js/plugins/purify.min.js" type="text/javascript"></script>

<!-- 主要的 fileinput 插件庫 -->

<script src="path/to/js/fileinput.min.js"></script>

<!-- 如果你想在放大的模態頁面中查看文件詳細信息需要引入bootstrap.js -->

<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/js/bootstrap.min.js" type="text/javascript"></script>

<!-- 可選，如果你需要像font awesome 這樣的主題，就像下面的代碼一樣引入它 -->

<script src="path/to/js/fa.js"></script>

<!-- 可選，如果你需要轉換語言或翻譯，就包含這個庫 -->

<script src="path/to/js/<lang>.js"></script>

你可能注意到了，除了fileinput.min.css和fileinput.min.js外，你必須要加載jquery.min.js和bootstrap.min.css。可選擇加入fa.js主題文件來使用font awesome圖標樣式。

GitHub 地址：https://github.com/kartik-v/bootstrap-fileinput

 

可選的依賴插件

• canvas-to-blob.min.js文件：是blueimp的JavaScript-Canvas-to-Blob插件的源代碼。如果你想在上傳之前修改圖片大小,在fileinput.min.js之前需要先加載它。
• sortable.min.js文件：是rubaxa可排序插件的源代碼。如果你希望在初始預覽中對縮略圖進行排序，則需要先加載它。
• purify.min.js文件：是cure53的DomPurify插件的源代碼。如果你希望淨化預覽的HTML內容，則需要加載它。
• 中文需要引用js/locales/zh.js
• 如下引入文件：

<script src="~/Scripts/bootstrap-fileinput-master/js/fileinput.min.js"></script>

<script src="~/Scripts/bootstrap-fileinput-master/themes/explorer/theme.js"></script>

<script src="~/Scripts/bootstrap-fileinput-master/js/locales/zh.js"></script>

步驟2

在你的頁面中初始化這個插件，像下面的樣例代碼一樣： JavaScript // 使用默認參數初始化插件 $("#input-id").fileinput();

$fileinput.fileinput({

            language: 'zh', //設置語言

            //theme: "explorer",

            uploadUrl: "/api/datareportapi/upload",

            allowedFileExtensions: ['xlsx','txt','zip','rar'],//接收的文件後綴

            uploadClass: "btn btn-sm btn-success",

            removeClass: "btn btn-sm btn-danger",

            cancelClass: "btn btn-sm btn-default",

            browseClass: "btn btn-sm btn-primary", //按鈕樣式 

            enctype: 'multipart/form-data',

            minFileCount: 1,

            //maxFileCount: 5,

            overwriteInitial: false,

            previewFileIcon: '<i class="fa fa-file"></i>',

            uploadExtraData: function (previewId, index) {

                return { batch: _configMap.batch, type: _configMap.type };

            },

            preferIconicPreview: true, // this will force thumbnails to display icons for following file extensions

            previewFileIconSettings: { // configure your icon file extensions

                'xls': '<i class="fa fa-file-excel-o text-success"></i>',

                'xlsx': '<i class="fa fa-file-excel-o text-success"></i>'

            },

            previewFileExtSettings: { // configure the logic for determining icon file extensions

                'xls': function (ext) {

                    return ext.match(/(xls|xlsx)$/i);

                }

            }

        })

// 使用插件參數初始化 $("#input-id").fileinput({'showUpload':false, 'previewFileType':'any'});

`#input-id`是你頁面中`input`標籤（即，`type=file`）的id值，通過插件初始化這個標籤會自動隱藏。

## 步驟 2

或者，你可以直接將插件選項設置爲任何輸入，通過HTML5的`data-*`屬性到你的輸入域。

```html

<input id="input-id" type="file" class="file" data-preview-file-type="text">

最後呈現效果圖如下:

 

Ajax上傳

你需要設置服務器方法通過AJAX來解析並返回正確的響應。你可以按異步或同步模式設置上傳，如下所述。

• 異步上傳
• 同步上傳

異步上傳

這是默認模式，也就是說uploadAsync屬性設置爲true。當上傳多個文件時，異步模式允許觸發並行調用服務器方法接受每個上傳文件。您可以通過設置maxFileCount屬性來控制一次允許上傳的最大文件數。在異步模式下，預覽中每個縮略圖的進度被驗證和更新。

接收數據（在服務器上）

你設置的服務器方法（uploadUrl）從插件接收以下數據:

文件數據:以與form文件輸入非常相似的格式將這些數據發送到服務器。例如，在PHP中，你可以使用代碼$_FILES['input-name']讀取文件數據，input-name是你的input標籤的name屬性。如果你沒有爲input標籤設置name屬性，則它的名稱默認爲file_data。請注意，多個文件上傳需要你爲input標籤設置multiple屬性爲true。這樣在PHP中你會收到文件數據$_FILES['file_data']。（servlet中使用request.getParts()獲取多個文件數據，使用request.getParts("input-name")獲取單個文件）

額外的數據：該插件可以向你的服務器方法發送附加數據。這可以通過將uploadExtraData設置爲鍵值對關聯數組對象來完成。所以如果你設置uploadExtraData={id:'kv-1'}，在PHP中你可以以$_POST['id']的方式讀取這些數據。

注意

在異步模式下，你會經常在處理ajax上傳的服務端接收到單個的文件數據。基本上，這個插件對每個上傳的文件都會觸發並行的ajax調用方法。你需要相應地編寫服務器上傳邏輯，以便您始終讀取和上傳單個文件。同樣，在下面的發送數據部分中，你必須返回一個initialPreview，它反映收到的單個文件的數據。

發送數據（從服務器）

你的服務器方法（uploadUrl）必須返回一個json編碼對象數據。在這種情況下，您可以發送這4個信息。請注意，在異步模式下，您會始終從服務器收到一個文件的記錄 - 因此你也要相應地調整前端JS代碼。

error：string類型，它是整個批量上傳的錯誤消息，並將幫助插件識別文件上傳中的錯誤。例如，來自服務器的響應像{error: 'You are not allowed to upload such a file.'}這樣。注意：插件將自動驗證並顯示ajax異常錯誤。

initialPreview：數組，圖像文件列表或任何指向你上傳文件的HTML標記。你會經常發送此隊列中的一行，因爲你在異步方式會一直收到上傳的單個文件。如果設置了此屬性，插件會在每個文件上傳成功後動態地在預覽內容中替換文件。這個配置類似於initialPreview選項設置。例如：

initialPreview: [

    "<img src='/images/desert.jpg' class='file-preview-image' alt='Desert' title='Desert'>",

],

initialPreviewConfig：數組，用於標識initialPreview條目（即initialPreview的一部分）中每個文件標記的屬性的配置。你會始終發送這個隊列中一行，因爲你始終以異步方式收到上傳的一個文件。如果設置了此屬性，插件會在每個文件上傳成功後自動在預覽內容中替換文件。這個配置類似於initialPreviewConfig選項設置。例如：

initialPreviewConfig ：[ 

    {

        標題:'desert.jpg' ，  

        width:'120px' ，  

        url:'http://localhost/avatar/delete' ，//服務器刪除操作  

        關鍵:100 ，  

        extra:{id:100}  

    }

]

initialPreviewThumbTags：數組，每個初始預覽縮略圖相對應的替換標籤對象數組。通過initialPreview設置的初始預覽縮略圖會讀取此配置爲替換標籤。

//更改縮略圖頁腳模板

//設置初始預覽模板標籤

initialPreviewThumbTags ：[

    {

        '{CUSTOM_TAG_NEW}':'', 

        '{CUSTOM_TAG_INIT}':'<span class = \'custom-css\'>CUSTOM MARKUP</span> '

    }

];

append：boolean類型，如果你已經在INIT中設置了initialPreview是否將內容插入initialPreview。如果未設置，則默認爲true。如果設置false，插件將覆蓋initialPreview內容。

重要

• 你必須從服務器發送有效的JSON響應，否則上傳過程將失敗。即使您沒有遇到任何錯誤，您至少必須從服務器發送一個空的JSON對象{}。
• 要捕獲並顯示驗證錯誤，你的JSON響應數據必須包含該error鍵，其值將是要顯示的錯誤HTML標記。如上所述那樣設置。
• 你還可以使用JSON響應發送附加的密鑰或數據，以便使用諸如fileuploaded此類的事件對高級案例進行處理

同步上傳

在此模式下，uploadAsync屬性設置爲false。它只會觸發一次批量上傳到服務器的方法，並將文件以對象數組的方式從客戶端發送到服務器。儘管在此模式下，你可以通過設置maxFileCount屬性來控制一次允許上傳的最大文件數。然而，在同步模式下，進度只會是對於整體水平的一個標量。預覽中每個縮略圖的進度未被精確計算和更新。但是，該插件爲你提供了識別每個文件上傳錯誤的方法。

接收數據

你設置的uploadUrl服務器方法從插件接收以下數據:

文件數據：以與表單輸入格式非常相似的格式將該數據發送到服務器。例如，在PHP中，您可以將該數據讀取爲$_FILES['input-name']，input-name是你的輸入標籤的name屬性。和之前的異步模式相同，如果你沒有爲輸入標籤設置名稱屬性，則該名稱將默認爲file_data。除了將multiple屬性設置爲true之外，你必須將輸入標籤的name屬性設置爲網頁提示中提到的數組格式。如果你不將輸入名稱設置爲數組格式，那麼你只能在服務器上收到第一個文件。在PHP中，你將收到文件數據$_FILES['input-name']，它將是一組文件對象。

額外的數據：該插件可以向你的服務器方法發送附加數據。這可以通過設置uploadExtraData爲鍵值對關聯數組對象來完成。所以如果你有設置uploadExtraData={id:'kv-1'}，在PHP中你可以像$_POST['id']這樣讀取這些數據。

發送數據

在同步模式下，uploadUrl必須發送json編碼對象數據作爲響應。在這種情況下，你需要發送這5條信息。

error：字符串類型，它是整個批量上傳的錯誤消息，並將幫助插件識別文件上傳中的錯誤。

errorkeys：數組類型，已經出錯的文件的鍵值（接收的文件數據的基於零的索引）。根據這些數據，插件會自動設置縮略圖和每個預覽文件的錯誤。

initialPreview：數組類型，圖像文件列表或任何指向你上傳文件的HTML標記。如果設置了此屬性，插件會在上傳成功後自動在預覽內容中替換文件。這個配置類似於initialPreview選項設置。例如：

initialPreview: [

    '<img src='/images/desert.jpg' class='file-preview-image' alt='Desert' title='Desert'>',

    '<img src='/images/jellyfish.jpg' class='file-preview-image' alt='Jelly Fish' title='Jelly Fish'>',

],

initialPreviewConfig：數組類型，用於標識initialPreview條目中每個文件標記（即作爲initialPreview的一部分進行設置）的屬性的配置。如果設置了此屬性，插件會在上傳成功後自動在預覽內容中替換文件。這個配置類似於initialPreviewConfig選項設置。例如：

initialPreviewConfig: [

    {

        caption: 'desert.jpg', 

        width: '120px', 

        url: 'http://localhost/avatar/delete', // 服務器刪除行爲

        key: 100, 

        extra: {id: 100}

    },

    {

        caption: 'jellyfish.jpg', 

        width: '120px', 

        url: 'http://localhost/avatar/delete', // 服務器刪除行爲

        key: 101, 

        extra: function() { 

            return {id: $('#id').val()};

        },

    }

]

initialPreviewThumbTags：數組類型，對應於每個初始預覽縮略圖中替換標籤的對象數組。通過設置initialPreview的初始預覽縮略圖將讀取此配置以替換標籤。

//更改縮略圖頁腳模板

//設置初始預覽模板標籤

initialPreviewThumbTags:[

    {

        '{CUSTOM_TAG_NEW}': ' ',

        '{CUSTOM_TAG_INIT}': '<span class=\'custom-css\'>CUSTOM MARKUP 1</span>'

    },

    {

        '{CUSTOM_TAG_NEW}': ' ',

        '{CUSTOM_TAG_INIT}': '<span class=\'custom-css\'>CUSTOM MARKUP 2</span>'

    }

];

append：布爾類型，如果你在初始化時設置了initialPreview，是否將新的內容附加到initialPreview中。如果未設置，則默認爲true。如果設置爲false，插件將覆蓋initialPreview內容。

例如，來自服務器的響應將發送{error: 'You have faced errors in 4 files.', errorkeys: [0, 3, 4, 5]}作爲響應。注意：插件將自動驗證並顯示ajax異常錯誤。

重要

你必須從服務器發送有效的JSON響應，否則上傳過程將失敗。即使您沒有遇到任何錯誤，您至少必須從服務器發送一個空的JSON對象。

要捕獲並顯示驗證錯誤，你的JSON響應數據必須包含該error鍵，其值將是要顯示的錯誤HTML標記。另外，您還必須發送errorkeys同步模式來識別面臨錯誤的文件的密鑰。這將如上所述設置。

你還可以使用JSON響應發送附加的密鑰或數據，以便使用如filebatchuploadsuccess事件對高級案例進行處理

方法

這個插件支持如下方法。查看插件各種方法的演示，請點擊這裏。

下面的許多方法支持鏈式調用其他方法，因爲它們將文件輸入元素作爲jQuery對象返回。

disable

禁用文件輸入控件。此方法將文件輸入元素作爲jQuery對象返回，因此可以鏈式調用其他方法。

$('#input-id').fileinput('disable');

// 鏈式調用啓用輸入控件

$('#input-id').fileinput('disable').fileinput('enable');

enable

啓用文件輸入控件。此方法將文件輸入元素作爲jQuery對象返回，因此可以鏈式調用其他方法。

$('#input-id').fileinput('enable');

// 鏈式調用禁用輸入控件

$('#input-id').fileinput('enable').fileinput('disable');

reset

重置文件輸入控件。此方法將文件輸入元素作爲jQuery對象返回，可以鏈式調用其他方法。

$('#input-id').fileinput('reset');

// 鏈式調用

$('#input-id').fileinput('reset').trigger('custom-event');

destroy

銷燬文件輸入控件並恢復到普通的本地文件輸入。此方法將文件輸入元素作爲jQuery對象返回，因此可以鏈式調用其他方法。

$('#input-id').fileinput('destroy');

// 鏈式方法

$('#input-id').fileinput('destroy').fileinput('disable');

refresh

根據提供的參數刷新文件輸入控件。你可以提供一組控件選項作爲參數。此方法將文件輸入元素作爲jQuery對象返回，因此可以鏈式調用其他方法。

// 例1（在運行時禁用）

$('#input-id').attr('disabled', 'disabled');

$('#input-id').fileinput('refresh');

// 例2（在運行時修改插件參數）example 2 (modify plugin options at runtime)

$('#input-id').fileinput('refresh', {browseLabel: 'Select...', removeLabel: 'Delete'});

// 鏈式方法

$('#input-id').fileinput('refresh', {showCaption: false}).fileinput('disable');

clear

清理文件輸入控件。此方法將文件輸入元素作爲jQuery對象返回，因此可以鏈式調用其他方法。

$('#input-id').fileinput('clear');

// 方法鏈

$('#input-id').fileinput('clear').fileinput('disable');

upload

觸發所選文件的ajax上傳。僅適用於uploadUrl已設置的情況。此方法將文件輸入元素作爲jQuery對象返回，因此可以鏈式調用其他方法。

$('#input-id').fileinput('upload');

// 方法鏈

$('#input-id').fileinput('upload').fileinput('disable');

cancel

取消正在進行的ajax文件上傳。此方法將文件輸入元素作爲jQuery對象返回，因此可以鏈式調用其他方法。

$('#input-id').fileinput('cancel');

// 方法鏈

$('#input-id').fileinput('cancel').fileinput('disable');

lock

鎖定文件輸入控件，禁用除取消按鈕（中止正在進行的AJAX請求）之外的所有操作/按鈕。（僅適用於ajax上傳）此方法將文件輸入元素作爲jQuery對象返回，因此可以鏈式調用其他方法。

$('#input-id').fileinput('lock');

// 方法鏈

$('#input-id').fileinput('lock').fileinput('disable');

unlock

通過反轉lock動作的結果解鎖並重新啓動文件輸入控件。此方法將文件輸入元素作爲jQuery對象返回，因此可以鏈式調用其他方法。

$('#input-id').fileinput('unlock');

// 方法鏈

$('#input-id').fileinput('unlock').fileinput('disable');

addToStack

此方法將文件對象推入（追加）到用來上傳的緩存文件堆棧數組。你必須傳入一個文件對象作爲參數。

$('#input-id').fileinput('addToStack', fileObj); // `fileObj`是文件blob對象實例

updateStack

此方法用指定的數組索引更新/重載一個緩存文件堆棧數組中的文件對象，以指定數組索引。你必須傳入數組索引數和文件對象作爲參數。

$('#input-id').fileinput('updateStack', index, fileObj); 

// `index`是你要更新/重載的`fileObj`的緩存文件數組索引。

clearStack

此方法清除整個文件上傳數組堆棧。

$('#input-id').fileinput('clearStack');

getFileStack

這個方法返回已選擇選擇文件對象數組（只有當uploadurl被設置且進行ajax上傳時適用。）這個方法不會返回驗證失敗或者已經上傳的文件。

var files = $('#input-id').fileinput('getFileStack'); // 返回選中的文件隊列

如上所述，請注意，此方法僅對於爲ajax上傳獲取文件對象非常有用。對於正常的基於表單的提交，你可以通過直接讀取輸入值來獲取選定的文件。例如$('#input-id').val()。

getFilesCount

此方法返回所有待上傳的文件和已上傳的文件（基於初始預覽）的計數。計數將包括從客戶端（未上傳）中選擇的文件加上傳到服務器並通過初始預覽顯示的文件。validateInitialCount將用於檢查是否使用初始預覽計數。當設置uploadUrl時，此方法將返回正常表單提交以及ajax上傳的文件數。

var filesCount = $('#input-id').fileinput('getFilesCount'); // 返回文件（已經上傳和等待上傳）計數

zoom

放大縮小傳入幀ID參數的詳細預覽內容。

$('#input-id').fileinput('zoom', 'preview-123882'); // 傳入縮略圖框架的HTML id。

getPreview

返回初始預覽內容，初始預覽配置和初始預覽縮略圖標籤。作爲下列格式的對象（關聯數組）返回結果：

{

    content: ['content1', 'content2'],

    config: [

        { 

            // content1 的初始化預覽配置

        },

        { 

            // content2 的初始化預覽配置

        },

    ],

    tags: [

        { 

            // content1 的初始化預覽標籤

        },

        { 

            // content2 的初始化預覽標籤

        },

    ]

}

使用範例：

console.log($('#input-id').fileinput('getPreview'));

事件

該插件支持各種事件，並允許高級功能，如返回事件結果來驗證和動態操作文件上傳。該部分分爲文件事件，異常事件和事件處理。

• 文件事件
• 異常事件
• 事件處理

文件事件

可用於文件管理和文件操作的事件。

change

只要通過文件瀏覽按鈕在文件輸入控件中選擇單個文件或多個文件，就會觸發此事件。

範例：

    $('#input-id').on('change', function(event) {

        console.log("change");

    });

fileselect

通過文件瀏覽按鈕在文件輸入中選擇文件後觸發此事件。這與change事件稍有不同，即使文件瀏覽對話框被取消，它也會被觸發。

範例：

    $('#input-id').on('fileselect', function(event, numFiles, label) {

        console.log("fileselect");

    });

fileclear

當文件輸入刪除按鈕或預覽窗口關閉圖標被按下以清除文件預覽時觸發此事件。

範例：

    $('#input-id').on('fileclear', function(event) {

        console.log("fileclear");

    });

filecleared

在預覽中的文件被清除後觸發此事件。

範例：

    $('#input-id').on('filecleared', function(event) {

        console.log("filecleared");

    });

fileloaded

在預覽中加載文件後觸發此事件。附加參數有：

• file：文件對象實例
• previewId：預覽文件容器的標識符（id）
• index：預覽列表中加載的文件的基於0的順序索引
• reader：:FileReader實例，如果瀏覽器支持它

範例：

$('#input-id').on('fileloaded', function(event, file, previewId, index, reader) {

    console.log("fileloaded");

});

filereset

當文件輸入被重置爲初始值時觸發此事件。

範例：

    $('#input-id').on('filereset', function(event) {

        console.log("filereset");

    });

fileimageloaded

每個圖像文件在預覽窗口中完全加載時觸發此事件。它只適用於圖像文件預覽且showPreview設置爲true的情況。附加參數有：

• previewId：預覽文件容器的id。

範例：

    $('#input-id').on('fileimageloaded', function(event, previewId) {

        console.log("fileimageloaded");

    });

fileimagesloaded

所有圖像文件在預覽窗口中完全加載時觸發此事件。它只適用於圖像文件預覽且showPreview設置爲true的情況。

範例：

    $('#input-id').on('fileimagesloaded', function(event) {

        console.log("fileimagesloaded");

    });

fileimageresized

當一個預覽的圖像文件由於resizeImage或者maxImageWidth/maxImageHeight設置而發生調整時觸發這個事件。它只適用於圖像文件預覽且showPreview設置爲true的情況。附加參數如下：

• previewId：預覽文件容器的標識符（id）
• index：預覽列表中加載的文件的基於0的順序索引

當預覽中所有圖像文件都發生調整後，上述事件將再次觸發，無任何上述參數（即，previewId和index 值爲 undefined）。

範例：

$('#input-id').on('fileimageresized', function(event, previewId, index) {

    console.log("fileimageresized");

});

fileimagesresized

當所有預覽的圖像文件由於resizeImage或者maxImageWidth/maxImageHeight設置都發生調整時觸發這個事件。它只適用於圖像文件預覽且showPreview設置爲true的情況。

範例：

$('#input-id').on('fileimagesresized', function(event) {

    console.log("fileimagesresized");

});

filebrowse

單擊文件瀏覽按鈕以打開文件選擇對話框時觸發此事件。

範例：

$('#input-id').on('filebrowse', function(event) {

    console.log("File browse triggered.");

});

filebatchselected

在預覽中選擇並顯示一批文件後觸發此事件。附加參數有：

• files：文件對象實例（如果FileReader不可用，則爲空對象）。

範例：

$('#input-id').on('filebatchselected', function(event, files) {

    console.log('File batch selected triggered');

});

fileselectnone

當用戶由於重複選擇場景（即，在已經包含先前選擇的文件的文件輸入）而沒有選擇任何文件時，觸發此事件。此事件更適用於Google Chrome等瀏覽器，當文件選擇對話框被取消時，它清除文件輸入。對於其他瀏覽器，此事件通常僅在復位表單或清除文件輸入（使用刪除按鈕）時纔會觸發。

範例：

$('#input-id').on('fileselectnone', function(event) {

    console.log("Huh! No files were selected.");

});

filelock

當通過點擊上傳按鈕啓動上傳過程時觸發此事件，並且整個小部件被鎖定（禁用），直到上傳被處理。當文件輸入被鎖定時，只有取消按鈕被啓用。附加參數有：

• filestack：已選擇的文件對象數組。
• uploadExtraData：這個插件的uploadExtraData設置（如果沒設置，則返回空對象）。

·           $('#input-id').on('filelock', function(event, filestack, extraData) {

·               var fstack = filestack.filter(function(n){ return n != undefined });

·               console.log('Files selected - ' + fstack.length);

·           });

fileunlock

當上傳過程完成（成功或有錯誤）時觸發此事件。整個小部件被解鎖（啓用）並恢復到初始狀態。附加參數有：

• filestack：已選擇的文件對象數組。
• uploadExtraData：這個插件的uploadExtraData設置（如果沒設置，則返回空對象）。

·         $('#input-id').on('fileunlock', function(event, filestack, extraData) {

·           var fstack = filestack.filter(function(n){ return n != undefined });

·           console.log('Files selected - ' + fstack.length);

·         });

filepredelete

在刪除initialPreview內容集中的每個縮略圖文件之前觸發此事件。附加參數有：

• key：要刪除的已選文件在initialPreviewConfig中傳入的關鍵字。
• jqXHR：用於此事務的jQuery XMLHttpRequest對象（如果可用）。
• data：輸出deleteExtraData對象。

$('#input-id').on('filepredelete', function(event, key) {

    console.log('Key = ' + key);

});

filedeleted

在刪除initialPreview內容集中的每個縮略圖文件之後觸發此事件。附加參數有：

• key：要刪除的已選文件在initialPreviewConfig中傳入的關鍵字。
• jqXHR：用於此事務的jQuery XMLHttpRequest對象（如果可用）。
• data：輸出deleteExtraData對象。

         $('#input-id').on('filedeleted', function(event, key) {

           console.log('Key = ' + key);

         });

filepreajax

此事件在提交ajax請求上傳之前觸發。你可以在ajax提交之前使用此事件操縱uploadExtraData。只有通過每個縮略圖上傳按鈕觸發上傳時，纔可以使用以下附加參數：

• previewId：預覽窗口中每個文件的縮略圖div父節點的id。
• index：預覽列表中加載的文件的基於0的順序索引

        $('#input-id').on('filepreajax', function(event, previewId, index) {

          console.log('File pre ajax triggered');

        });

filepreupload

此事件僅在ajax上傳且上載每個縮略圖文件之前觸發。此事件在filepreajax之後伴隨ajax的beforeSend事件觸發。附加參數有：

• data：這是一個數據對象（關聯數組），它發送以下信息，其關鍵字是：
• form：FormData，通過XHR2傳遞的對象（如果不可用，則爲空對象）。
• files: 數組，文件棧數組（如果不可用，則爲空對象）。
• filenames：數組，堆棧數組中每個文件的客戶端文件名（如果不可用，則爲空對象）。
• filescount: int，所選文件的計數包括已經上傳的文件（基本上返回getFilesCount方法的輸出）。
• extra：該插件的uploadExtraData設置（如果不可用，則爲空對象）。
• response：通過ajax響應發送的數據（如果不可用，則爲空對象）。
• reader：FileReader實例，如果可用。
• jqXHR：用於此事務的jQuery XMLHttpRequest對象（如果可用）。
• previewId：預覽窗口中每個文件的縮略圖div父節點的id。
• index：預覽列表中加載的文件的基於0的順序索引

         $('#input-id').on('filepreupload', function(event, data, previewId, index) {

          var form = data.form, files = data.files, extra = data.extra,

               response = data.response, reader = data.reader;

           console.log('File pre upload triggered');

         });

fileuploaded

此事件僅在ajax上傳且上載每個縮略圖文件之後觸發。此事件只有是AJAX上傳並在以下場景纔會觸發：

• 當單擊每個預覽縮略圖中的上傳圖標並且文件上傳成功時，或者
• 當你將uploadAsync設置爲true並且已觸發批量上傳時。在這種情況下，fileuploaded事件在每個單獨的選定文件成功上傳之後被觸發。

此事件可用的其他參數：

• data：這是一個數據對象（關聯數組），它發送以下信息，其關鍵字是：
• form：FormData，通過XHR2傳遞的對象（如果不可用，則爲空對象）。
• files: 數組，文件棧數組（如果不可用，則爲空對象）。
• filenames：數組，堆棧數組中每個文件的客戶端文件名（如果不可用，則爲空對象）。
• filescount: int，所選文件的計數包括已經上傳的文件（基本上返回getFilesCount方法的輸出）。
• extra：該插件的uploadExtraData設置（如果不可用，則爲空對象）。
• response：通過ajax響應發送的數據（如果不可用，則爲空對象）。
• reader：FileReader實例，如果可用。
• jqXHR：用於此事務的jQuery XMLHttpRequest對象（如果可用）。
• previewId：預覽窗口中每個文件的縮略圖div父節點的id。
• index：預覽列表中加載的文件的基於0的順序索引

         $('#input-id').on('fileuploaded', function(event, data, previewId, index) {

           var form = data.form, files = data.files, extra = data.extra,

               response = data.response, reader = data.reader;

           console.log('File uploaded triggered');

         });

filebatchpreupload

此事件僅對於ajax上傳的上傳按鈕被單擊之後且批量上傳開始之前纔會觸發（同步和異步上傳）。附加參數有：

• data：這是一個數據對象（關聯數組），它發送以下信息，其關鍵字是：
• form：FormData，通過XHR2傳遞的對象（如果不可用，則爲空對象）。
• files: 數組，文件棧數組（如果不可用，則爲空對象）。
• filenames：數組，堆棧數組中每個文件的客戶端文件名（如果不可用，則爲空對象）。
• filescount: int，所選文件的計數包括已經上傳的文件（基本上返回getFilesCount方法的輸出）。
• extra：該插件的uploadExtraData設置（如果不可用，則爲空對象）。
• response：通過ajax響應發送的數據（如果不可用，則爲空對象）。
• reader：FileReader實例，如果可用。
• jqXHR：用於此事務的jQuery XMLHttpRequest對象（如果可用）。

$('#input-id').on('filebatchpreupload', function(event, data, previewId, index) {

    var form = data.form, files = data.files, extra = data.extra,

        response = data.response, reader = data.reader;

    console.log('File batch pre upload');

});

filebatchuploadsuccess

此事件僅在ajax上傳且文件批量上傳成功之後觸發。此事件只有是AJAX上傳並在以下場景纔會觸發：

1. 當你將uploadAsync設置爲false並且已經觸發了批量上傳時。 在這種情況下，在所以文件成功上傳後會觸發filebatchuploadsuccess事件 。

附加參數有：

• data：這是一個數據對象（關聯數組），它發送以下信息，其關鍵字是：
• form：FormData，通過XHR2傳遞的對象（如果不可用，則爲空對象）。
• files： 數組，文件棧數組（如果不可用，則爲空對象）。
• filenames：數組，堆棧數組中每個文件的客戶端文件名（如果不可用，則爲空對象）。
• filescount：int，所選文件的計數包括已經上傳的文件（基本上返回getFilesCount方法的輸出）。
• extra：該插件的uploadExtraData設置（如果不可用，則爲空對象）。
• response：通過ajax響應發送的數據（如果不可用，則爲空對象）。
• reader：FileReader實例，如果可用。
• jqXHR：用於此事務的jQuery XMLHttpRequest對象（如果可用）。

$('#input-id').on('filebatchuploadsuccess', function(event, data, previewId, index) {

    var form = data.form, files = data.files, extra = data.extra,

        response = data.response, reader = data.reader;

    console.log('File batch upload success');

});

filebatchuploadcomplete

此事件僅對於ajax上傳且完成同步或異步ajax批量上傳後觸發。附加參數有：

• files：數組，文件棧數組（如果不可用，則爲空對象）。
• extra：該插件的uploadExtraData設置（如果不可用，則爲空對象）。

         $('#input-id').on('filebatchuploadcomplete', function(event, files, extra) {

          console.log('File batch upload complete');

         });

filesuccessremove

使用縮略圖刪除按鈕刪除成功上傳的縮略圖後，會觸發此事件。當showUploadedThumbs設置爲true時，這通常是適用的。附加參數有：

• id：縮略圖HTML容器節點的id屬性。

         $('#input-id').on('filesuccessremove', function(event, id) {

           if (some_processing_function(id)) {

             console.log('Uploaded thumbnail successfully removed');

           } else {

               return false; // 縮略圖刪除中斷

           }

         });

filedisabled

當使用disable方法禁用文件輸入小部件（防止任何修改）時觸發此事件。

$('#input-id').on('filedisabled', function(event) {

  console.log('File disabled');

});

fileenabled

當使用·enable·方法啓用文件輸入小部件（允許修改）時觸發此事件。

$('#input-id').on('fileenabled', function(event) {

  console.log('File enabled');

});

filesorted

當通過初始預覽中的拖放來對文件進行排序/重新排列時，會觸發此事件。以下參數將作爲JSON對象關鍵字另外發送：

• previewId：預覽縮略圖HTML容器節點的id屬性。
• oldIndex：initialPreview中縮略圖得舊索引
• newIndex：initialPreview中縮略圖得新索引
• stack：排序後修改的initialPreviewConfig

         $('#input-id').on('filesorted', function(event, params) {

           console.log('File sorted ', params.previewId, params.oldIndex, params.newIndex, params.stack);

         });

filezoomshow

單擊縮放按鈕（在模態對話框中顯示內容詳細預覽）時觸發此事件。以下參數將作爲JSON對象關鍵字另外發送：

• sourceEvent：事件，模態對話框源事件show.bs.modal。
• previewId：字符串，預覽縮略圖HTML容器節點的id屬性。
• modal：jQuery對象，模態框對象

$('#input-id').on('filezoomshow', function(event, params) {

    console.log('File zoom show ', params.sourceEvent, params.previewId, params.modal);

});

filezoomshown

在模態框已被用戶看到之後觸發此事件（將等待CSS轉換完成）​​。以下參數將作爲JSON對象關鍵字另外發送：

• sourceEvent：事件，模態對話框源事件show.bs.modal。
• previewId：字符串，預覽縮略圖HTML容器節點的id屬性。
• modal：jQuery對象，模態框對象

$('#input-id').on('filezoomshown', function(event, params) {

    console.log('File zoom shown ', params.sourceEvent, params.previewId, params.modal);

});

filezoomhide

通過關閉對話框按鈕隱藏模態框後觸發此事件。以下參數將作爲JSON對象關鍵字另外發送：

• sourceEvent：事件，模態對話框源事件show.bs.modal。
• previewId：字符串，預覽縮略圖HTML容器節點的id屬性。
• modal：jQuery對象，模態框對象

$('#input-id').on('filezoomhide', function(event, params) { console.log('File zoom hide ', params.sourceEvent, params.previewId, params.modal); });

filezoomhidden

在模態從用戶眼中隱藏完成之後觸發此事件（將等待CSS轉換完成）​​。以下參數將作爲JSON對象關鍵字另外發送：

• sourceEvent：事件，模態對話框源事件show.bs.modal。
• previewId：字符串，預覽縮略圖HTML容器節點的id屬性。
• modal：jQuery對象，模態框對象

$('#input-id').on('filezoomhidden', function(event, params) {

    console.log('File zoom hidden ', params.sourceEvent, params.previewId, params.modal);

});

filezoomloaded

在使用remote選項加載模態框內容之後觸發此事件。以下參數將作爲JSON對象關鍵字另外發送：

• sourceEvent：事件，模態對話框源事件show.bs.modal。
• previewId：字符串，預覽縮略圖HTML容器節點的id屬性。
• modal：jQuery對象，模態框對象

         $('#input-id').on('filezoomloaded', function(event, params) {

           console.log('File zoom loaded ', params.sourceEvent, params.previewId, params.modal);

         });

filezoomprev

在縮放預覽模式下觸發此事件，當單擊查看上一個導航按鈕時（也是在縮放模式下按下鍵盤左箭頭時觸發）。

• previewId：字符串，預覽縮略圖HTML容器節點的id屬性。
• modal：jQuery對象，模態框對象

$('#input-id').on('filezoomprev', function(event, params) {

    console.log('File zoom previous ', params.previewId, params.modal);

});

filezoomnext

在縮放預覽模式下觸發此事件，當查看下一個導航按鈕被點擊時（當在縮放模式下按下鍵盤右箭頭時也會觸發此事件）。

• previewId：字符串，預覽縮略圖HTML容器節點的id屬性。
• modal：jQuery對象，模態框對象

$('#input-id').on('filezoomnext', function(event, params) {

    console.log('File zoom next ', params.previewId, params.modal);

});

異常事件

用於文件驗證錯誤的事件。

fileerror

當上傳文件客戶端驗證錯誤時，會觸發此事件。它允許傳入對象data作爲參數。

• data：包含下面關鍵字的對象/關聯數組。
• id：預覽縮略圖標識符id（如果不可用，則爲undefined）
• index：文件索引或者預覽縮略圖索引（如果不可用，則爲undefined）
• file：文件對象（如果不可用，則爲undefined）
• reader：文件讀取器實例（如果不可用，則爲undefined）
• files：文件堆數組（如果不可用，則爲undefined）
• msg：字符串，生成的錯誤信息

範例：

$('#input-id').on('fileerror', function(event, data, msg) {

   console.log(data.id);

   console.log(data.index);

   console.log(data.file);

   console.log(data.reader);

   console.log(data.files);

   // 獲取信息

   alert(msg);

});

fileimageresizeerror

當調整圖像大小遇到錯誤或異常時，會觸發此事件（請參見resizeImage屬性）。附加參數有：

• data：包含下面關鍵字的對象/關聯數組。
• id：預覽縮略圖標識符id（如果不可用，則爲undefined）
• index：文件索引或者預覽縮略圖索引（如果不可用，則爲undefined）
• msg：字符串，生成的錯誤信息

範例：

$('#input-id').on('fileimageresizeerror', function(event, data, msg) {

   console.log(data.id);

   console.log(data.index);

   // get message

   alert(msg);

});

fileuploaderror

此事件僅在ajax上傳時觸發，並且主要針對ajax上傳時遇到上載或文件輸入驗證錯誤。此事件僅針對ajax上傳並在以下情況下觸發：

1. 當每個預覽縮略圖中的上傳圖標被點擊並且文件面臨上傳中的驗證錯誤時，或者
2. 當你將uploadAsync設置爲true並且已觸發批量上傳時。在這種情況下，在任何所選文件面臨上傳驗證錯誤後，會觸發fileuploaderror事件。

此事件可用的附加參數有：

• data：這是一個數據對象（關聯數組），它發送以下信息，其關鍵字是：
• id：預覽縮略圖的標識符（如果不可用，則爲空對象）。
• index：文件索引或者預覽縮略圖索引（如果不可用，則爲空對象）。
• form：FormData，通過XHR2傳遞的對象（如果不可用，則爲空對象）。
• files： 數組，文件棧數組（如果不可用，則爲空對象）。
• filenames：數組，堆棧數組中每個文件的客戶端文件名（如果不可用，則爲空對象）。
• filescount：int，所選文件的計數包括已經上傳的文件（基本上返回getFilesCount方法的輸出）。
• extra：該插件的uploadExtraData設置（如果不可用，則爲空對象）。
• response：通過ajax響應發送的數據（如果不可用，則爲空對象）。
• reader：FileReader實例，如果可用。
• jqXHR：用於此事務的jQuery XMLHttpRequest對象（如果可用）。
• msg：字符串，生成的錯誤信息。

         $('#input-id').on('fileuploaderror', function(event, data, msg) {

           var form = data.form, files = data.files, extra = data.extra,

               response = data.response, reader = data.reader;

           console.log('File upload error');

          // 獲取信息

          alert(msg);

         });

filebatchuploaderror

此事件僅在ajax上傳時觸發，並且同步批量上傳面臨上傳驗證錯誤之後。此事件僅針對ajax上傳並在以下情況下觸發：

• 當您將uploadAsync設置爲false並且已觸發批量上傳時。在這種情況下，在任何文件面臨上載錯誤或者你通過服務器操作JSON響應返回錯誤後觸發filebatchuploaderror事件。

此事件可用的附加參數有：

• data：這是一個數據對象（關聯數組），它發送以下信息，其關鍵字是：
• form：FormData，通過XHR2傳遞的對象（如果不可用，則爲空對象）。
• files： 數組，文件棧數組（如果不可用，則爲空對象）。
• filenames：數組，堆棧數組中每個文件的客戶端文件名（如果不可用，則爲空對象）。
• filescount：int，所選文件的計數包括已經上傳的文件（基本上返回getFilesCount方法的輸出）。
• extra：該插件的uploadExtraData設置（如果不可用，則爲空對象）。
• response：通過ajax響應發送的數據（如果不可用，則爲空對象）。
• reader：FileReader實例，如果可用。
• jqXHR：用於此事務的jQuery XMLHttpRequest對象（如果可用）。
• msg：字符串，生成的錯誤信息。

         $('#input-id').on('filebatchuploaderror', function(event, data, msg) {

           var form = data.form, files = data.files, extra = data.extra,

               response = data.response, reader = data.reader;

           console.log('File batch upload error');

          // 獲取信息

          alert(msg);

         });

filedeleteerror

當在initialPreview內容集中刪除每個縮略圖文件出現錯誤時觸發此事件。附加參數有：

• data：這是一個數據對象（關聯數組），它發送以下信息，其關鍵字是：
• id：預覽縮略圖的標識符（如果不可用，則爲空對象）。
• index：文件索引或者預覽縮略圖索引（如果不可用，則爲空對象）。
• extra：該插件的uploadExtraData設置（如果不可用，則爲空對象）。
• response：通過ajax響應發送的數據（如果不可用，則爲空對象）。
• jqXHR：用於此事務的jQuery XMLHttpRequest對象（如果可用）。
• msg：字符串，生成的錯誤信息。

·         $('#input-id').on('filedeleteerror', function(event, data, msg) {

·           console.log('File delete error');

·          // get message

·          alert(msg);

·         });

filefoldererror

當文件夾或多個文件夾被拖放到文件預覽放置區時，會觸發此事件。附加參數有：

• folders：整數，拖拽的文件夾數量。
• msg：字符串，生成的錯誤信息。

         $('#input-id').on('filefoldererror', function(event, folders, msg) {

           console.log('File folder dropped error');

          // 獲取信息

          alert(msg);

         });

filecustomerror

通過從源事件返回錯誤異常對象，用戶從其他事件之一手動觸發此事件。參考事件操作部分瞭解詳情。附加參數有：

• data：這是一個數據對象（關聯數組），它發送以下信息，其關鍵字是：
• form：FormData，通過XHR2傳遞的對象（如果不可用，則爲空對象）。
• files： 數組，文件棧數組（如果不可用，則爲空對象）。
• filenames：數組，堆棧數組中每個文件的客戶端文件名（如果不可用，則爲空對象）。
• filescount：int，所選文件的計數包括已經上傳的文件（基本上返回getFilesCount方法的輸出）。
• extra：該插件的uploadExtraData設置（如果不可用，則爲空對象）。
• response：通過ajax響應發送的數據（如果不可用，則爲空對象）。
• reader：FileReader實例，如果可用。
• jqXHR：用於此事務的jQuery XMLHttpRequest對象（如果可用）。
• msg：字符串，生成的錯誤信息。

         $("#input").on('filecustomerror', function(event, params, msg) {

          console.log(params.id);

          console.log(params.index);

          console.log(params.data);

          // 獲取信息

          alert(msg);

         });

事件處理

從版本v4.1.8開始，你可以操作事件並通過其他事件添加自定義驗證，通過返回大多數事件的數據並將其用於高級處理。除了以下事件之外，事件部分中列出的大多數事件都支持此功能。

• fileclear
• filecleared
• filereset
• fileerror
• fileuploaderror
• filebatchuploaderror
• filedeleteerror
• filefoldererror
• filecustomerror
• fileuploaded
• filebatchuploadcomplete
• filebatchuploadsuccess

對於除上述之外的所有事件，你可以設置自定義驗證錯誤，這將在啓動上傳之前觸發。

這將使你能夠添加其他自定義驗證來增強文件輸入控件適用於更多場景。它允許使用任何fileinput事件（除上述事件之外）返回關聯對象，例如，change、fileselect、filepreupload、filebatchpreupload等等。

該對象可以返回以下關鍵字：

• message：字符串，在上傳之前顯示是的驗證錯誤消息。如果設置了它，插件會在調用時自動中止上傳，並將其顯示爲錯誤消息。你可以使用此屬性來讀取文件並執行自己的自定義驗證。
• data：對象，一箇中止時可選的額外數據關聯數組，你可以給它傳值，稍後使用它。

範例：

• 步驟1： 你可以觸發一個從filepreupload中止的異常。

           $('#input').on('filepreupload', function(event, data, previewId, index, jqXHR) {

               // 進行自定義驗證並返回如下所示的錯誤

              if (customValidationFailed) {

                  return {

                      message: 'You are not allowed to do that',

                      data: {key1: 'Key 1', detail1: 'Detail 1'}

                  };

              }

           });

上傳中斷將在AJAX上傳或表單提交（非AJAX上傳）時觸發。

• 步驟2：通過捕獲filecustomerror中止事件來讀取額外的數據。

         $('#input').on('filecustomerror', function(event, params) {

          // `params.abortData`包含額外傳出的數據

          // `params.abortMessage`包含傳出的錯誤中斷信息

         });

如前所述，在以下事件中不支持使用filecustomerror的上述功能：

• fileclear
• filecleared
• filereset
• fileerror
• fileuploaderror
• filebatchuploaderror
• filedeleteerror
• filecustomerror
• fileuploaded
• filebatchuploadcomplete
• ·         filebatchuploadsuccess

樣例代碼

AJAX上傳實例

具有拖拽功能，基於AJAX 異步/同步的上傳。只需要設置uploadurl數據屬性，把multiple屬性設置爲true。請注意，多個上傳的文件輸入name屬性應設置爲數組格式。你可以修改上傳之前選擇的文件，例如增加或刪除。對於下面的示例，你可以在服務器上讀取上傳的name屬性爲kartik-input-700文件。

例1
<input id="input-700" name="kartik-input-700[]" type="file" multiple class="file-loading">

<script>

$("#input-700").fileinput({

uploadUrl: "http://localhost/file-upload-single/1", // 服務器端上傳處理程序

uploadAsync: true, //異步上傳

maxFileCount: 5 //最大上傳文件數爲5

});

</script>

例2
<input id="input-701" name="kartik-input-701[]" type="file" multiple=true class="file-loading">

<script>

$("#input-701").fileinput({

uploadUrl: "http://localhost/file-upload-batch/1", // 服務器端上傳處理程序

uploadAsync: true,

maxFileCount: 5

});

</script>

例3
<input id="input-702" name="kartik-input-702[]" type="file" multiple=true class="file-loading">
<script>
$("#input-702").fileinput({
uploadUrl: "http://localhost/file-upload-single/1", // 服務器端上傳處理程序
uploadAsync: true, //異步上傳
minFileCount: 1, //最小上傳文件數： 1
maxFileCount: 5, //最大上傳文件數： 5
overwriteInitial: false, //不能重載初始預覽
initialPreview: [ //初始預覽數據
"http://lorempixel.com/800/460/people/1",
"http://lorempixel.com/800/460/people/2"
],
initialPreviewAsData: true, // 確定傳入預覽數據，而不是原生標記語言
initialPreviewFileType: 'image', // 默認爲`image`，可以在下面配置中被覆蓋
initialPreviewConfig: [ //初始預覽配置
{caption: "People-1.jpg", size: 576237, width: "120px", url: "/site/file-delete", key: 1},
{caption: "People-2.jpg", size: 932882, width: "120px", url: "/site/file-delete", key: 2},
],
uploadExtraData: { //上傳額外數據
img_key: "1000",
img_keywords: "happy, places",
}
});
</script>
例4
PHP的寫法如下：
<input id="input-703" name="kartik-input-703[]" type="file" multiple class="file-loading">
<script>
$("#input-703").fileinput({
uploadUrl: "http://localhost/file-upload-single/2",
uploadAsync: true, //異步上傳
minFileCount: 1,
maxFileCount: 5,
uploadExtraData: function(previewId, index) {
return {key: index};
},
overwriteInitial: false,
initialPreviewAsData: true // 確定你是僅發送預覽數據，而不是標記
});
</script>
<?php
// ...
// 處理ajax上傳並返回JSON響應的服務器代碼。
// 你的服務器方法必須返回一個包含`initialPreview`、`initialPreviewConfig`和`append`的JSON對象。
// 一個PHP服務器代碼示例如下：
// ...
$key = '<解析圖像關鍵字的代碼>';
$url = '<你刪除這個文件的服務器方法URL>';
echo json_encode([
'initialPreview' => [
"http://path.to.uploaded.file/{$key}.jpg"
],
'initialPreviewConfig' => [
['caption' => "Sports-{$key}.jpg", 'size' => 627392, 'width' => '120px', 'url' => $url, 'key' => $key],
],
'append' => true // 是否把這些配置加入`initialPreview`。
// 如果設置爲`false`，它會重載初始預覽。
// 如果設置爲`true`，它會加入初始預覽之中。
// 如果這個屬性沒有被設置或者沒有傳出，它會默認爲`true`。
]);
?>

例5

<input id="input-704" name="kartik-input-704[]" type="file" multiple=true class="file-loading">
<script>
$("#input-704").fileinput({
uploadUrl: "http://localhost/file-upload-batch/2", // 服務器上傳接收方法
uploadAsync: false, //同步上傳
minFileCount: 1,
maxFileCount: 5,
initialPreviewAsData: true
});
</script>
<?php
// ...
// 處理ajax上傳並返回JSON響應的服務器代碼。
// 你的服務器方法必須返回一個包含`initialPreview`、`initialPreviewConfig`和`append`的JSON對象。
// 一個PHP服務器代碼示例如下：
// ...
$p1 = $p2 = [];
if (empty($_FILES['kartik-input-704']['name'])) {
echo '{}';
return;
}
for ($i = 0; $i < count($_FILES['kartik-input-704']['name']); $i++) {
$j = $i + 1;
$key = '<獲取圖像關鍵字的代碼>';
$url = '<你的服務器上刪除這個圖像的服務地址>';
$p1[$i] = "http://path.to.uploaded.file/{$key}.jpg"; // 發送的數據
$p2[$i] = ['caption' => "Animal-{$j}.jpg", 'size' => 732762, 'width' => '120px', 'url' => $url, 'key' => $key];
}
echo json_encode([
'initialPreview' => $p1,
'initialPreviewConfig' => $p2,
'append' => true // 是否把這些配置加入`initialPreview`。
// 如果設置爲`false`，它會重載初始預覽。
// 如果設置爲`true`，它會加入初始預覽之中。
// 如果這個屬性沒有被設置或者沒有傳出，它會默認爲`true`。
]);
?>

例6

<input id="input-705" name="kartik-input-705[]" type="file" multiple class="file-loading">
<script>
var $input = $("#input-705");
$input.fileinput({
uploadUrl: "http://localhost/file-upload-batch/2", // 服務器接收上傳文件的方法
uploadAsync: false,
showUpload: false, // 隱藏上傳按鈕
showRemove: false, // 隱藏移除按鈕
minFileCount: 1,
maxFileCount: 5
}).on("filebatchselected", function(event, files) {
// 選擇文件後立即觸發上傳方法
$input.fileinput("upload");
});
</script>
例7
<input id="input-706" name="kartik-input-706[]" type="file" multiple=true class="file-loading">
<style>
.krajee-default .file-thumb-progress {
top: 55px
}
</style> <!-- 樣式重載 -->
<script>
var $el2 = $("#input-706");

// 這個場景的自定義頁腳模板
// 自定義標籤在大括號裏

var footerTemplate = '<div class="file-thumbnail-footer" style ="height:94px">\n' +
' <div style="margin:5px 0">\n' +
' <input class="kv-input kv-new form-control input-sm text-center {TAG_CSS_NEW}" value="{caption}" placeholder="Enter caption...">\n' +
' <input class="kv-input kv-init form-control input-sm text-center {TAG_CSS_INIT}" value="{TAG_VALUE}" placeholder="Enter caption...">\n' +
' </div>\n' +
' {size} {progress} {actions}\n' +
'</div>';

$el2.fileinput({
uploadUrl: '/file-upload-batch/2',
uploadAsync: false,
maxFileCount: 5,
overwriteInitial: false,
layoutTemplates: {footer: footerTemplate, size: '<samp><small>({sizeText})</small></samp>'},
previewThumbTags: {
'{TAG_VALUE}': '', // 無值
'{TAG_CSS_NEW}': '', // 新的縮略圖輸入
'{TAG_CSS_INIT}': 'hide' // 隱藏初始輸入
},
initialPreview: [
"<img style='height:160px' src='http://angelasp.com/800/460/city/1'>",
"<img style='height:160px' src='http://angelasp.com/800/460/city/2'>",
],
initialPreviewConfig: [
{caption: "City-1.jpg", size: 327892, width: "120px", url: "/site/file-delete", key: 1},
{caption: "City-2.jpg", size: 438828, width: "120px", url: "/site/file-delete", key: 2},
],
initialPreviewThumbTags: [
{'{TAG_VALUE}': 'City-1.jpg', '{TAG_CSS_NEW}': 'hide', '{TAG_CSS_INIT}': ''},
{
'{TAG_VALUE}': function() { // 回調示例
return 'City-2.jpg';
},
'{TAG_CSS_NEW}': 'hide',
'{TAG_CSS_INIT}': ''
}
],
uploadExtraData: function() { // 回調示例
var out = {}, key, i = 0;
$('.kv-input:visible').each(function() {
$el = $(this);
key = $el.hasClass('kv-new') ? 'new_' + i : 'init_' + i;
out[key] = $el.val();
i++;
});
return out;
}
});
</script>
例8
<input id="input-707" name="kartik-input-707[]" type="file" multiple=true class="file-loading">
<script>
$("#input-707").fileinput({
uploadUrl: "/file-upload-batch/1",
uploadAsync: false,
minFileCount: 2,
maxFileCount: 5,
overwriteInitial: false,
initialPreview: [
"<img style='height:160px' src='http://angelasp.com/800/460/nature/1'>",
"<img style='height:160px' src='http://angelasp.com/800/460/nature/2'>",
"<img style='height:160px' src='http://angelasp.com/800/460/nature/3'>",
],
initialPreviewConfig: [
{caption: "Food-1.jpg", size: 329892, width: "120px", url: "/site/file-delete", key: 1},
{caption: "Food-2.jpg", size: 872378, width: "120px", url: "/site/file-delete", key: 2},
{caption: "Food-3.jpg", size: 632762, width: "120px", url: "/site/file-delete", key: 3},
],
uploadExtraData: {
img_key: "1000",
img_keywords: "happy, nature",
}
});
$("#input-707").on("filepredelete", function(jqXHR) {
var abort = true;
if (confirm("Are you sure you want to delete this image?")) {
abort = false;
}
return abort; // 你也可以發送任何數據/對象，只要你可以在`filecustomerror`事件接收。
});
<script>
例9
<input id="input-708" name="kartik-input-708[]" type="file" multiple=true class="file-loading">
<script>
$("#input-708").fileinput({
uploadUrl: "http://localhost/file-upload-batch/1", // 服務器接收上傳文件方法
uploadAsync: false,
maxFileCount: 5
}).on('filebatchpreupload', function(event, data) {
var n = data.files.length, files = n > 1 ? n + ' files' : 'one file';
if (!window.confirm("你確定要上傳 " + files + "？")) {
return {
message: "上傳中斷！", // 上傳異常信息
data:{} // 要發送的任何其他數據，可以在`filecustomerror`中引用
};
}
});
</script>
例10
<input id="input-709" name="kartik-input-709[]" type="file" multiple class="file-loading">
<div id="kv-error-1" style="margin-top:10px;display:none"></div>
<div id="kv-success-1" class="alert alert-success fade in" style="margin-top:10px;display:none"></div>
<script>
$("#input-709").fileinput({
uploadUrl: "http://localhost/file-upload-single/1", // 服務器接收上傳文件方法
uploadAsync: true,
showPreview: false,
allowedFileExtensions: ['jpg', 'png', 'gif'],
maxFileCount: 5,
elErrorContainer: '#kv-error-1'
}).on('filebatchpreupload', function(event, data, id, index) {
$('#kv-success-1').html('<h4>上傳狀態</h4><ul></ul>').hide();
}).on('fileuploaded', function(event, data, id, index) {
var fname = data.files[index].name,
out = '<li>' + 'U上傳文件 # ' + (index + 1) + ' - ' +
fname + ' 成功' + '</li>';
$('#kv-success-1 ul').append(out);
$('#kv-success-1').fadeIn('slow');
});
</script>
例11
<input id="input-710" name="kartik-input-710[]" type="file" multiple class="file-loading">
<div id="kv-error-2" style="margin-top:10px;display:none"></div>
<script>
<div id="kv-success-2" class="alert alert-success fade in" style="margin-top:10px;display:none"></div>
$("#input-700").fileinput({
uploadUrl: "http://localhost/file-upload-batch/1", // 服務器接收上傳文件方法
uploadAsync: false,
showPreview: false,
allowedFileExtensions: ['jpg', 'png', 'gif'],
maxFileCount: 5,
elErrorContainer: '#kv-error-2'
}).on('filebatchpreupload', function(event, data, id, index) {
$('#kv-success-2').html('<h4>上傳狀態</h4><ul></ul>').hide();
}).on('filebatchuploadsuccess', function(event, data) {
var out = '';
$.each(data.files, function(key, file) {
var fname = file.name;
out = out + '<li>' + '上傳文件 # ' + (key + 1) + ' - ' + fname + ' 成功。' + '</li>';
});
$('#kv-success-2 ul').append(out);
$('#kv-success-2').fadeIn('slow');
});
</script>
例12
<input id="input-711" name="kartik-input-711[]" type="file" multiple class="file-loading">
<script>
$("#input-711").fileinput({
uploadUrl: "http://localhost/file-upload-single/1", // 服務器接收上傳文件方法
uploadAsync: true,
maxFileCount: 5,
showBrowse: false,
browseOnZoneClick: true
});
</script>