我之前寫過一篇文章《文件上傳利器SWFUpload使用指南》，裏面介紹了上傳組件SWFUpload的使用方法，但現在隨着html5技術的逐漸推廣和普及，再去使用以flash爲上傳手段的SWFUpload顯然就有點過時了，畢竟html5原生的就給我們提供了文件上傳的API。Plupload是一款由著名的web編輯器TinyMCE團隊開發的上傳組件，簡單易用且功能強大，我們完全可以使用Plupload來代替以前的SWFUpload。
Plupload有以下功能和特點：
1、擁有多種上傳方式：HTML5、flash、silverlight以及傳統的<input type=”file” />。Plupload會自動偵測當前的環境，選擇最合適的上傳方式，並且會優先使用HTML5的方式。所以你完全不用去操心當前的瀏覽器支持哪些上傳方式，Plupload會自動爲你選擇最合適的方式。
2、支持以拖拽的方式來選取要上傳的文件
3、支持在前端壓縮圖片，即在圖片文件還未上傳之前就對它進行壓縮
4、可以直接讀取原生的文件數據，這樣的好處就是例如可以在圖片文件還未上傳之前就能把它顯示在頁面上預覽
5、支持把大文件切割成小片進行上傳，因爲有些瀏覽器對很大的文件比如幾G的一些文件無法上傳。
Plupload的使用方法也與SWFUpload非常類似，可以分爲以下幾步：
1、引入js文件，plupload的源文件可以到github上去下載
2、實例化一個plupload對象，傳入一個配置參數對象進行各方面的配置。
3、調用plupload實例對象的init()方法進行初始化
4、在plupload實例對象上註冊各種你需要的事件。plupload從選取文件到文件上傳完成這個過程中，會觸發很多事件。我們可以通過這些事件來跟plupload進行交互。
5、實現你自己所註冊的那些事件的監聽函數，利用這些監聽函數來進行更新UI、提示上傳進度等工作。
大家可以到http://chaping.github.io/plupload/demo/看一下我寫的關於plupload的幾個上傳demo。
下面用一段代碼來說明Plupload的使用方法。
首先看下我的目錄結構
index.html的代碼如下：
<!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <title>Plupload使用指南</title> <!-- 首先需要引入plupload的源代碼 --> <script src="js/plupload.full.min.js"></script> </head> <body> <!-- 這裏我們只使用最基本的html結構：一個選擇文件的按鈕，一個開始上傳文件的按鈕(甚至該按鈕也可以不要) --> <p> <button id="browse">選擇文件</button> <button id="start_upload">開始上傳</button> </p> <script> //實例化一個plupload上傳對象 var uploader = new plupload.Uploader({ browse_button : 'browse', //觸發文件選擇對話框的按鈕，爲那個元素id url : 'upload.php', //服務器端的上傳頁面地址 flash_swf_url : 'js/Moxie.swf', //swf文件，當需要使用swf方式進行上傳時需要配置該參數 silverlight_xap_url : 'js/Moxie.xap' //silverlight文件，當需要使用silverlight方式進行上傳時需要配置該參數 }); //在實例對象上調用init()方法進行初始化 uploader.init(); //綁定各種事件，並在事件監聽函數中做你想做的事 uploader.bind('FilesAdded',function(uploader,files){ //每個事件監聽函數都會傳入一些很有用的參數， //我們可以利用這些參數提供的信息來做比如更新UI，提示上傳進度等操作 }); uploader.bind('UploadProgress',function(uploader,file){ //每個事件監聽函數都會傳入一些很有用的參數， //我們可以利用這些參數提供的信息來做比如更新UI，提示上傳進度等操作 }); //...... //...... //最後給"開始上傳"按鈕註冊事件 document.getElementById('start_upload').onclick = function(){ uploader.start(); //調用實例對象的start()方法開始上傳文件，當然你也可以在其他地方調用該方法 } </script> </body> </html>
使用Plupload的關鍵是瞭解它衆多的配置參數、事件以及屬性和方法。我把它官網上的文檔翻譯成了中文並整理如下。我也把它放到了github上，你可以到http://chaping.github.io/plupload/doc/去查閱。
目錄：
一、配置參數
實例化一個plupload對象時，也就是 new plupload.Uploader()，需要傳入一個對象作爲配置參數。後面內容中出現的plupload實例均是指new plupload.Uploader()得到的實例對象
| 屬性 | 類型 | 默認值 | 描述 |
|---|---|---|---|
| browse_button | String / DOM | 觸發文件選擇對話框的DOM元素，當點擊該元素後便後彈出文件選擇對話框。該值可以是DOM元素對象本身，也可以是該DOM元素的id | |
| url | String | 服務器端接收和處理上傳文件的腳本地址，可以是相對路徑(相對於當前調用Plupload的文檔)，也可以是絕對路徑 | |
| filters | Object | { } |
可以使用該參數來限制上傳文件的類型，大小等，該參數以對象的形式傳入，它包括三個屬性：
mime_types：用來限定上傳文件的類型，爲一個數組，該數組的每個元素又是一個對象，該對象有title和extensions兩個屬性，title爲該過濾器的名稱，extensions爲文件擴展名，有多個時用逗號隔開。該屬性默認爲一個空數組，即不做限制。 max_file_size：用來限定上傳文件的大小，如果文件體積超過了該值，則不能被選取。值可以爲一個數字，單位爲b,也可以是一個字符串，由數字和單位組成，如'200kb' prevent_duplicates：是否允許選取重複的文件，爲true時表示不允許，爲false時表示允許，默認爲false。如果兩個文件的文件名和大小都相同，則會被認爲是重複的文件 filters完整的配置示例如下(當然也可以只配置其中的某一項)： filters: {
mime_types : [ //只允許上傳圖片和zip文件
{ title : "Image files", extensions : "jpg,gif,png" },
{ title : "Zip files", extensions : "zip" }
],
max_file_size : '400kb', //最大隻能上傳400kb的文件
prevent_duplicates : true //不允許選取重複文件
}
|
| headers | Object | 設置上傳時的自定義頭信息，以鍵/值對的形式傳入，鍵代表頭信息屬性名，鍵代表屬性值。html4上傳方式不支持設置該屬性。 | |
| multipart | Boolean | true |
爲true時將以multipart/form-data的形式來上傳文件，爲false時則以二進制的格式來上傳文件。html4上傳方式不支持以二進制格式來上傳文件，在flash上傳方式中，二進制上傳也有點問題。並且二進制格式上傳還需要在服務器端做特殊的處理。一般我們用multipart/form-data的形式來上傳文件就足夠了。 |
| multipart_params | Object |
上傳時的附加參數，以鍵/值對的形式傳入，服務器端可是使用$_POST來獲取這些參數(以php爲例)。比如：
multipart_params: {
one: '1',
two: '2',
three: { //值還可以是一個字面量對象
a: '4',
b: '5'
},
four: ['6', '7', '8'] //也可以是一個數組
}
|
|
| max_retries | Number | 0 |
當發生plupload.HTTP_ERROR錯誤時的重試次數，爲0時表示不重試 |
| chunk_size | Number/String | 0 |
分片上傳文件時，每片文件被切割成的大小，爲數字時單位爲字節。也可以使用一個帶單位的字符串，如"200kb"。當該值爲0時表示不使用分片上傳功能 |
| resize | Object |
可以使用該參數對將要上傳的圖片進行壓縮，該參數是一個對象，裏面包括5個屬性：
width：指定壓縮後圖片的寬度，如果沒有設置該屬性則默認爲原始圖片的寬度 height：指定壓縮後圖片的高度，如果沒有設置該屬性則默認爲原始圖片的高度 crop：是否裁剪圖片 quality：壓縮後圖片的質量，只對jpg格式的圖片有效，默認爲90。 preserve_headers：壓縮後是否保留圖片的元數據， resize參數的配置示例如下： resize: {
width: 100,
height: 100,
crop: true,
quality: 60,
preserve_headers: false
}
|
|
| drop_element | DOM/String/Array | 指定了使用拖拽方式來選擇上傳文件時的拖拽區域，即可以把文件拖拽到這個區域的方式來選擇文件。該參數的值可以爲一個DOM元素的id,也可是DOM元素本身，還可以是一個包括多個DOM元素的數組。如果不設置該參數則拖拽上傳功能不可用。目前只有html5上傳方式才支持拖拽上傳。 | |
| multi_selection | Boolean | true | 是否可以在文件瀏覽對話框中選擇多個文件，true爲可以，false爲不可以。默認true，即可以選擇多個文件。需要注意的是，在某些不支持多選文件的環境中，默認值是false。比如在ios7的safari瀏覽器中，由於存在bug，造成不能多選文件。當然，在html4上傳方式中，也是無法多選文件的。 |
| required_features | Mix | 可以使用該參數來設置你必須需要的一些功能特徵，Plupload會根據你的設置來選擇合適的上傳方式。因爲，不同的上傳方式，支持的功能是不同的，比如拖拽上傳只有html5上傳方式支持，圖片壓縮則只有html5,flash,silverlight上傳方式支持。該參數的值是一個混合類型，可以是一個以逗號分隔的字符串， | |
| unique_names | Boolean | false |
當值爲true時會爲每個上傳的文件生成一個唯一的文件名，並作爲額外的參數post到服務器端，參數明爲name,值爲生成的文件名。 |
| runtimes | String |
html5,flash, silverlight, html4 |
用來指定上傳方式，指定多個上傳方式請使用逗號隔開。一般情況下，你不需要配置該參數，因爲Plupload默認會根據你的其他的參數配置來選擇最合適的上傳方式。如果沒有特殊要求的話，Plupload會首先選擇html5上傳方式，如果瀏覽器不支持html5，則會使用flash或silverlight，如果前面兩者也都不支持，則會使用最傳統的html4上傳方式。如果你想指定使用某個上傳方式，或改變上傳方式的優先順序，則你可以配置該參數。 |
| file_data_name | String | file |
指定文件上傳時文件域的名稱，默認爲file,例如在php中你可以使用$_FILES['file']來獲取上傳的文件信息 |
| container | DOM/String |
用來指定Plupload所創建的html結構的父容器，默認爲前面指定的browse_button的父元素。該參數的值可以是一個元素的id,也可以是DOM元素本身。 |
|
| flash_swf_url | String | js/Moxie.swf | flash上傳組件的url地址，如果是相對路徑，則相對的是調用Plupload的html文檔。當使用flash上傳方式會用到該參數。 |
| silverlight_xap_url | String | js/Moxie.xap | silverlight上傳組件的url地址，如果是相對路徑，則相對的是調用Plupload的html文檔。當使用silverlight上傳方式會用到該參數。 |
二、各種事件說明
要了解plupload的運行狀況，靠的就是在這些事件了
| Init |
|---|
|
當Plupload初始化完成後觸發
監聽函數參數：(uploader)
|
| PostInit |
|
當Init事件發生後觸發
監聽函數參數：(uploader)
|
| OptionChanged |
|
當使用Plupload實例的setOption()方法改變當前配置參數後觸發
監聽函數參數：(uploader,option_name,new_value,old_value)
|
| Refresh |
|
當調用plupload實例的refresh()方法後會觸發該事件，暫時不清楚還有什麼其他動作會觸發該事件，但據我測試，把文件添加到上傳隊列後也會觸發該事件。
監聽函數參數：(uploader)
|
| StateChanged |
|
當上傳隊列的狀態發生改變時觸發
監聽函數參數：(uploader)
|
| UploadFile |
|
當上傳隊列中某一個文件開始上傳後觸發
監聽函數參數：(uploader,file)
|
| BeforeUpload |
|
當隊列中的某一個文件正要開始上傳前觸發
監聽函數參數：(uploader,file)
|
| QueueChanged |
|
當上傳隊列發生變化後觸發，即上傳隊列新增了文件或移除了文件。QueueChanged事件會比FilesAdded或FilesRemoved事件先觸發
監聽函數參數：(uploader)
|
| UploadProgress |
|
會在文件上傳過程中不斷觸發，可以用此事件來顯示上傳進度
監聽函數參數：(uploader,file)
|
| FilesRemoved |
|
當文件從上傳隊列移除後觸發
監聽函數參數：(uploader,files)
|
| FileFiltered |
|
暫不清楚該事件的意義，但根據測試得出，該事件會在每一個文件被添加到上傳隊列前觸發
監聽函數參數：(uploader,file)
|
| FilesAdded |
|
當文件添加到上傳隊列後觸發
監聽函數參數：(uploader,files)
|
| FileUploaded |
|
當隊列中的某一個文件上傳完成後觸發
監聽函數參數：(uploader,file,responseObject)
response：服務器返回的文本 responseHeaders：服務器返回的頭信息 status：服務器返回的http狀態碼，比如200 |
| ChunkUploaded |
|
當使用文件小片上傳功能時，每一個小片上傳完成後觸發
監聽函數參數：(uploader,file,responseObject)
offset：該文件小片在整體文件中的偏移量 response：服務器返回的文本 responseHeaders：服務器返回的頭信息 status：服務器返回的http狀態碼，比如200 total：該文件(指的是被切割成了許多文件小片的那個文件)的總大小，單位爲字節 |
| UploadComplete |
|
當上傳隊列中所有文件都上傳完成後觸發
監聽函數參數：(uploader,files)
|
| Error |
|
當發生錯誤時觸發
監聽函數參數：(uploader,errObject)
code：錯誤代碼，具體請參考plupload上定義的表示錯誤代碼的常量屬性 file：與該錯誤相關的文件對象 message：錯誤信息 |
| Destroy |
|
當調用destroy方法時觸發
監聽函數參數：(uploader)
|
三、Plupload實例的屬性
| 屬性 | 描述 |
|---|---|
| id | Plupload實例的唯一標識id |
| state |
當前的上傳狀態，可能的值爲plupload.STARTED或plupload.STOPPED，該值由Plupload實例的stop()或statr()方法控制。默認爲plupload.STOPPED |
| runtime | 當前使用的上傳方式 |
| files | 當前的上傳隊列，是一個由上傳隊列中的文件對象組成的數組 |
| settings | 當前的配置參數對象 |
| total | 表示總體進度信息的QueueProgress對象 |
四、Plupload實例的方法
| 方法 | 描述 |
|---|---|
| init() | 初始化Plupload實例 |
| setOption(option, [value]) | 設置某個特定的配置參數,option爲參數名稱，value爲要設置的參數值。option也可以爲一個由參數名和參數值鍵/值對組成的對象，這樣就可以一次設定多個參數，此時該方法的第二個參數value會被忽略。 |
| getOption([option]) | 獲取當前的配置參數，參數option爲需要獲取的配置參數名稱，如果沒有指定option，則會獲取所有的配置參數 |
| refresh() | 刷新當前的plupload實例，暫時還不明白什麼時候需要使用 |
| start() | 開始上傳隊列中的文件 |
| stop() | 停止隊列中的文件上傳 |
| disableBrowse(disable) |
禁用或啓用plupload的文件瀏覽按鈕,參數disable爲true時爲禁用，爲false時爲啓用。默認爲true |
| getFile(id) | 通過id來獲取文件對象 |
| addFile(file, [fileName]) |
向上傳隊列中添加文件，如果成功添加了文件，會觸發FilesAdded事件。參數file爲要添加的文件,可以是一個原生的文件,或者一個plupload文件對象,或者一個input[type="file"]元素,還可以是一個包括前面那幾種東西的數組；fileName爲給該文件指定的名稱 |
| removeFile(file) |
從上傳隊列中移除文件，參數file爲plupload文件對象或先前指定的文件名稱 |
| splice(start, length) |
從上傳隊列中移除一部分文件，start爲開始移除文件在隊列中的索引，length爲要移除的文件的數量，該方法的返回值爲被移除的文件。該方法會觸發FilesRemoved 和QueueChanged事件 |
| trigger(name, Multiple) |
觸發某個事件。name爲要觸發的事件名稱，Multiple爲傳給該事件監聽函數的參數，是一個對象 |
| hasEventListener(name) |
用來判斷某個事件是否有監聽函數，name爲事件名稱 |
| bind(name, func, scope) |
給某個事件綁定監聽函數，name爲事件名，func爲監聽函數，scope爲監聽函數的作用域，也就是監聽函數中this的指向 |
| unbind(name, func) |
移除事件的監聽函數，name爲事件名稱，func爲要移除的監聽函數 |
| unbindAll() | 移除所有事件的所有監聽函數 |
| destroy() | 銷燬plupload實例 |
五、文件對象的屬性和方法
在很多事件監聽函數中，都會提供文件對象給你
| 屬性/方法 | 描述 |
|---|---|
| id | 文件id |
| name | 文件名，例如"myfile.gif" |
| type | 文件類型，例如"image/jpeg" |
| size | 文件大小，單位爲字節，當啓用了客戶端壓縮功能後，該值可能會改變 |
| origSize | 文件的原始大小，單位爲字節 |
| loaded | 文件已上傳部分的大小，單位爲字節 |
| percent | 文件已上傳部分所佔的百分比，如50就代表已上傳了50% |
| status |
文件的狀態，可能爲以下幾個值之一：plupload.QUEUED, plupload.UPLOADING, plupload.FAILED, plupload.DONE |
| lastModifiedDate | 文件最後修改的時間 |
| getNative() | 獲取原生的文件對象 |
| getSource() | 獲取mOxie.File 對象，想了解mOxie是什麼東西，可以看下https://github.com/moxiecode/moxie/wiki/API |
| destroy() | 銷燬文件對象 |
六、QueueProgress 對象的屬性
plupload實例的total屬性是一個QueueProgress對象
| 屬性 | 描述 |
|---|---|
| size | 上傳隊列中所有文件加起來的總大小，單位爲字節 |
| loaded | 隊列中當前已上傳文件加起來的總大小,單位爲字節 |
| uploaded | 已完成上傳的文件的數量 |
| failed | 上傳失敗的文件數量 |
| queued | 隊列中剩下的(也就是除開已經完成上傳的文件)需要上傳的文件數量 |
| percent | 整個隊列的已上傳百分比，如50就代表50% |
| bytesPerSec | 上傳速率，單位爲 byte/s，也就是 字節/秒 |
七、plupload命名空間上的一些屬性
plupload的命名空間上有一些屬性，用來表示一些常量。記住，不是plupload實例的屬性，而是plupload的屬性
| 屬性名稱 | 描述 |
|---|---|
| VERSION | 當前plupload的版本號 |
| STOPPED |
值爲1，代表上傳隊列還未開始上傳或者上傳隊列中的文件已經上傳完畢時plupload實例的state屬性值 |
| STARTED |
值爲2，代表隊列中的文件正在上傳時plupload實例的state屬性值 |
| QUEUED |
值爲1，代表某個文件已經被添加進隊列等待上傳時該文件對象的status屬性值 |
| UPLOADING |
值爲2，代表某個文件正在上傳時該文件對象的status屬性值 |
| FAILED |
值爲4，代表某個文件上傳失敗後該文件對象的status屬性值 |
| DONE |
值爲5，代表某個文件上傳成功後該文件對象的status屬性值 |
| GENERIC_ERROR | 值爲-100，發生通用錯誤時的錯誤代碼 |
| HTTP_ERROR | 值爲-200，發生http網絡錯誤時的錯誤代碼，例如服務氣端返回的狀態碼不是200 |
| IO_ERROR | 值爲-300，發生磁盤讀寫錯誤時的錯誤代碼，例如本地上某個文件不可讀 |
| SECURITY_ERROR | 值爲-400，發生因爲安全問題而產生的錯誤時的錯誤代碼 |
| INIT_ERROR | 值爲-500，初始化時發生錯誤的錯誤代碼 |
| FILE_SIZE_ERROR | 值爲-600，當選擇的文件太大時的錯誤代碼 |
| FILE_EXTENSION_ERROR | 值爲-601，當選擇的文件類型不符合要求時的錯誤代碼 |
| FILE_DUPLICATE_ERROR | 值爲-602，當選取了重複的文件而配置中又不允許有重複文件時的錯誤代碼 |
| IMAGE_FORMAT_ERROR | 值爲-700，發生圖片格式錯誤時的錯誤代碼 |
| IMAGE_MEMORY_ERROR | 當發生內存錯誤時的錯誤代碼 |
| IMAGE_DIMENSIONS_ERROR | 值爲-702，當文件大小超過了plupload所能處理的最大值時的錯誤代碼 |