介紹 bootstrap-fileinput是一款非常優秀的HTML5文件上傳插件,支持文件預覽、多文件上傳等一系列特性。 一款非常優秀的HTML5文件上傳插件,支持bootstrap 3.x 和4.x版本,具有非常多的特性:多文件類型上傳。這個插件能最簡單的幫你完成文件上傳功能,且使用bootst ...
介紹
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
標準。大多數現代瀏覽器都支持此標準,但插件在不支持的瀏覽器中將自動降級為正常格式提交。
- 添加AJAX功能,基於
HTML5 FormData
大多數現代瀏覽器支持)上傳方式。如果不支持,將降級到正常的基於表單的文件提交。 - 要使用AJAX上傳,必須設置
uploadUrl
屬性。 - 增強插件,現在允許添加,附加,刪除文件(基於許多的反饋)。因此,可以附加文件到預覽。
- 可以通過
DRAG & DROP
區域來拖放和附加文件。New DRAG & DROP zone available in preview to drag and drop files and append. - 逐個或批量刪除、上傳文件。
- 如果
showPreview
設置為false
,或者未設置uploadUrl
,插件將降級到基於正常的form
形式上傳。 - 可配置指示燈來同步文件等待上傳,文件成功上傳,文件上傳錯誤狀態。
- 能夠添加額外的表單數據到基於ajax的上傳中。
- 上傳進度條和單個縮略圖的上傳標識。
- 能夠取消和中止正在進行的AJAX上傳。
- 建立初始預覽內容(例如保存的圖像庫)。您可以設置初始預覽操作(預定義支持預先預覽刪除)。也可以設置其他自定義操作按鈕初始化預覽縮略圖。
- 確保插件仍然尺寸精簡,並最佳地利用
HTML5
和jquery
功能優化上述功能的性能。 - 一旦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
文件中。
依賴項
- Bootstrap 3.X。但是,可以使用任何CSS框架模板來定製插件。
- 最新的JQuery
- 大多數支持HTML5文件輸入和FileReader API的現代瀏覽器,包括對CSS3和JQuery的支持。
- 為了正常使用文件預覽功能,瀏覽器必須支持HTML5 FileReaderAPI,否則插件會自動降級到普通的表單文件輸入。對於Internet Explorer,必須使用IE 10及更高版本。IE9及以下版本將作為普通文件輸入,並且不支持多個文件選擇和HTML5 FileReader API。
- 版本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 |
支持 |
上傳進度欄 |
不支持 |
支持 |
閱讀其他表單數據 |
直接通過表單提交 |
通過 |
模式比較
- 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上傳時適用。)這個方法不會返回驗證失敗或者已經上傳的文件。
varfiles = $(
'#input-id').fileinput(
'getFileStack');
// 返回選中的文件隊列
如上所述,請註意,此方法僅對於為ajax上傳獲取文件對象非常有用。對於正常的基於表單的提交,你可以通過直接讀取輸入值來獲取選定的文件。例如$('#input-id').val()
。
getFilesCount
此方法返回所有待上傳的文件和已上傳的文件(基於初始預覽)的計數。計數將包括從客戶端(未上傳)中選擇的文件加上傳到伺服器並通過初始預覽顯示的文件。validateInitialCount將用於檢查是否使用初始預覽計數。當設置uploadUrl
時,此方法將返回正常表單提交以及ajax上傳的文件數。
varfilesCount = $(
'#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){
returnn !=
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){
returnn !=
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
。只有通過每個縮略圖上傳按鈕觸發上傳時,才可以使