前端上傳元件Plupload使用指南 與swfupload一樣強大
Plupload有以下功能和特點：
1、擁有多種上傳方式：HTML5、flash、silverlight以及傳統的<input type=”file” />。Plupload會自動偵測當前的環境，選擇最合適的上傳方式，並且會優先使用HTML5的方式。所以你完全不用去操心當前的瀏覽器支援哪些上傳方式，Plupload會自動為你選擇最合適的方式。
2、支援以拖拽的方式來選取要上傳的檔案
3、支援在前端壓縮圖片，即在圖片檔案還未上傳之前就對它進行壓縮
4、可以直接讀取原生的檔案資料，這樣的好處就是例如可以在圖片檔案還未上傳之前就能把它顯示在頁面上預覽
5、支援把大檔案切割成小片進行上傳，因為有些瀏覽器對很大的檔案比如幾G的一些檔案無法上傳。
Plupload的使用方法也與SWFUpload非常類似，可以分為以下幾步：
1、引入js檔案
2、例項化一個plupload物件，傳入一個配置引數物件進行各方面的配置。
3、呼叫plupload例項物件的init()方法進行初始化
4、在plupload例項物件上註冊各種你需要的事件。plupload從選取檔案到檔案上傳完成這個過程中，會觸發很多事件。我們可以通過這些事件來跟plupload進行互動。
5、實現你自己所註冊的那些事件的監聽函式，利用這些監聽函式來進行更新UI、提示上傳進度等工作。
下面用一段程式碼來說明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()得到的例項物件
| 屬性 | 型別 | 預設值 | 描述 |
|---|---|---|---|
| String / DOM | 觸發檔案選擇對話方塊的DOM元素，當點選該元素後便後彈出檔案選擇對話方塊。該值可以是DOM元素物件本身，也可以是該DOM元素的id | ||
| url | String | 伺服器端接收和處理上傳檔案的指令碼地址，可以是相對路徑(相對於當前呼叫Plupload的文件)，也可以是絕對路徑 | |
| 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 //不允許選取重複檔案
}
|
|
| Object | 設定上傳時的自定義頭資訊，以鍵/值對的形式傳入，鍵代表頭資訊屬性名，鍵代表屬性值。html4上傳方式不支援設定該屬性。 | ||
| Boolean | true | 為true時將以multipart/form-data的形式來上傳檔案，為false時則以二進位制的格式來上傳檔案。html4上傳方式不支援以二進位制格式來上傳檔案，在flash上傳方式中，二進位制上傳也有點問題。並且二進位制格式上傳還需要在伺服器端做特殊的處理。一般我們用multipart/form-data的形式來上傳檔案就足夠了。 |
|
| Object | 上傳時的附加引數，以鍵/值對的形式傳入，伺服器端可是使用$_POST來獲取這些引數(以php為例)。比如：
multipart_params: {
one: '1',
two: '2',
three: { //值還可以是一個字面量物件
a: '4',
b: '5'
},
four: ['6', '7', '8'] //也可以是一個數組
}
|
||
| Number | 0 | 當發生plupload.HTTP_ERROR錯誤時的重試次數，為0時表示不重試 |
|
| Number/String | 0 | 分片上傳檔案時，每片檔案被切割成的大小，為數字時單位為位元組。也可以使用一個帶單位的字串，如"200kb"。當該值為0時表示不使用分片上傳功能 |
|
| Object | 可以使用該引數對將要上傳的圖片進行壓縮，該引數是一個物件，裡面包括5個屬性：
width：指定壓縮後圖片的寬度，如果沒有設定該屬性則預設為原始圖片的寬度 height：指定壓縮後圖片的高度，如果沒有設定該屬性則預設為原始圖片的高度 crop：是否裁剪圖片 quality：壓縮後圖片的質量，只對jpg格式的圖片有效，預設為90。 preserve_headers：壓縮後是否保留圖片的元資料， resize引數的配置示例如下： resize: {
width: 100,
height: 100,
crop: true,
quality: 60,
preserve_headers: false
}
|
||
| DOM/String/Array | 指定了使用拖拽方式來選擇上傳檔案時的拖拽區域，即可以把檔案拖拽到這個區域的方式來選擇檔案。該引數的值可以為一個DOM元素的id,也可是DOM元素本身，還可以是一個包括多個DOM元素的陣列。如果不設定該引數則拖拽上傳功能不可用。目前只有html5上傳方式才支援拖拽上傳。 | ||
| Boolean | true | 是否可以在檔案瀏覽對話方塊中選擇多個檔案，true為可以，false為不可以。預設true，即可以選擇多個檔案。需要注意的是，在某些不支援多選檔案的環境中，預設值是false。比如在ios7的safari瀏覽器中，由於存在bug，造成不能多選檔案。當然，在html4上傳方式中，也是無法多選檔案的。 | |
| Mix | 可以使用該引數來設定你必須需要的一些功能特徵，Plupload會根據你的設定來選擇合適的上傳方式。因為，不同的上傳方式，支援的功能是不同的，比如拖拽上傳只有html5上傳方式支援，圖片壓縮則只有html5,flash,silverlight上傳方式支援。該引數的值是一個混合型別，可以是一個以逗號分隔的字串， | ||
| Boolean | false | 當值為true時會為每個上傳的檔案生成一個唯一的檔名，並作為額外的引數post到伺服器端，引數明為name,值為生成的檔名。 |
|
| String | html5,flash, silverlight, html4 |
用來指定上傳方式，指定多個上傳方式請使用逗號隔開。一般情況下，你不需要配置該引數，因為Plupload預設會根據你的其他的引數配置來選擇最合適的上傳方式。如果沒有特殊要求的話，Plupload會首先選擇html5上傳方式，如果瀏覽器不支援html5，則會使用flash或silverlight，如果前面兩者也都不支援，則會使用最傳統的html4上傳方式。如果你想指定使用某個上傳方式，或改變上傳方式的優先順序，則你可以配置該引數。 | |
| String | file | 指定檔案上傳時檔案域的名稱，預設為file,例如在php中你可以使用$_FILES['file']來獲取上傳的檔案資訊 |
|
| DOM/String | 用來指定Plupload所建立的html結構的父容器，預設為前面指定的browse_button的父元素。該引數的值可以是一個元素的id,也可以是DOM元素本身。 |
||
| String | js/Moxie.swf | flash上傳元件的url地址，如果是相對路徑，則相對的是呼叫Plupload的html文件。當使用flash上傳方式會用到該引數。 | |
| String | js/Moxie.xap | silverlight上傳元件的url地址，如果是相對路徑，則相對的是呼叫Plupload的html文件。當使用silverlight上傳方式會用到該引數。 |
二、各種事件說明
要了解plupload的執行狀況，靠的就是在這些事件了
| Init |
|---|
| 當Plupload初始化完成後觸發
監聽函式引數：(uploader)
|
| 當Init事件發生後觸發
監聽函式引數：(uploader)
|
| 當使用Plupload例項的setOption()方法改變當前配置引數後觸發
監聽函式引數：(uploader,option_name,new_value,old_value)
|
| 當呼叫plupload例項的refresh()方法後會觸發該事件，暫時不清楚還有什麼其他動作會觸發該事件，但據我測試，把檔案新增到上傳佇列後也會觸發該事件。
監聽函式引數：(uploader)
|
| 當上傳佇列的狀態發生改變時觸發
監聽函式引數：(uploader)
|
| 當上傳佇列中某一個檔案開始上傳後觸發
監聽函式引數：(uploader,file)
|
| 當佇列中的某一個檔案正要開始上傳前觸發
監聽函式引數：(uploader,file)
|
| 當上傳佇列發生變化後觸發，即上傳佇列新增了檔案或移除了檔案。QueueChanged事件會比FilesAdded或FilesRemoved事件先觸發
監聽函式引數：(uploader)
|
| 會在檔案上傳過程中不斷觸發，可以用此事件來顯示上傳進度
監聽函式引數：(uploader,file)
|
| 當檔案從上傳佇列移除後觸發
監聽函式引數：(uploader,files)
|
| 暫不清楚該事件的意義，但根據測試得出，該事件會在每一個檔案被新增到上傳佇列前觸發
監聽函式引數：(uploader,file)
|
| 當檔案新增到上傳佇列後觸發
監聽函式引數：(uploader,files)
|
| 當佇列中的某一個檔案上傳完成後觸發
監聽函式引數：(uploader,file,responseObject)
response：伺服器返回的文字 responseHeaders：伺服器返回的頭資訊 status：伺服器返回的http狀態碼，比如200 |
| 當使用檔案小片上傳功能時，每一個小片上傳完成後觸發
監聽函式引數：(uploader,file,responseObject)
offset：該檔案小片在整體檔案中的偏移量 response：伺服器返回的文字 responseHeaders：伺服器返回的頭資訊 status：伺服器返回的http狀態碼，比如200 total：該檔案(指的是被切割成了許多檔案小片的那個檔案)的總大小，單位為位元組 |
| 當上傳佇列中所有檔案都上傳完成後觸發
監聽函式引數：(uploader,files)
|
| Error |
| 當發生觸發時觸發
監聽函式引數：(uploader,errObject)
code：錯誤程式碼，具體請參考plupload上定義的表示錯誤程式碼的常量屬性 file：與該錯誤相關的檔案物件 message：錯誤資訊 |
| 當呼叫destroy方法時觸發
監聽函式引數：(uploader)
|
三、Plupload例項的屬性
| 屬性 | 描述 |
|---|---|
| id | Plupload例項的唯一標識id |
| state | 當前的上傳狀態，可能的值為plupload.STARTED或plupload.STOPPED，該值由Plupload例項的stop()或statr()方法控制。預設為plupload.STOPPED |
| files | 當前的上傳佇列，是一個由上傳佇列中的檔案物件組成的陣列 |
| total | 表示總體進度資訊的QueueProgress物件 |
四、Plupload例項的方法
| 方法 | 描述 |
|---|---|
| 初始化Plupload例項 | |
| 設定某個特定的配置引數,option為引數名稱，value為要設定的引數值。option也可以為一個由引數名和引數值鍵/值對組成的物件，這樣就可以一次設定多個引數，此時該方法的第二個引數value會被忽略。 | |
| 獲取當前的配置引數，引數option為需要獲取的配置引數名稱，如果沒有指定option，則會獲取所有的配置引數 | |
| 重新整理當前的plupload例項，暫時還不明白什麼時候需要使用 | |
| 停止佇列中的檔案上傳 | |
禁用或啟用plupload的檔案瀏覽按鈕,引數disable為true時為禁用，為false時為啟用。預設為true |
|
向上傳佇列中新增檔案，如果成功添加了檔案，會觸發FilesAdded事件。引數file為要新增的檔案,可以是一個原生的檔案,或者一個plupload檔案物件,或者一個input[type="file"]元素,還可以是一個包括前面那幾種東西的陣列；fileName為給該檔案指定的名稱 |
|
從上傳佇列中移除檔案，引數file為plupload檔案物件或先前指定的檔名稱 |
|
從上傳佇列中移除一部分檔案，start為開始移除檔案在佇列中的索引，length為要移除的檔案的數量，該方法的返回值為被移除的檔案。該方法會觸發FilesRemoved
和QueueChanged事件 |
|
觸發某個事件。name為要觸發的事件名稱，Multiple為傳給該事件監聽函式的引數，是一個物件 |
|
給某個事件繫結監聽函式，name為事件名，func為監聽函式，scope為監聽函式的作用域，也就是監聽函式中this的指向 |
|
移除事件的監聽函式，name為事件名稱，func為要移除的監聽函式 |
五、檔案物件的屬性和方法
在很多事件監聽函式中，都會提供檔案物件給你
| 屬性/方法 | 描述 |
|---|---|
| id | 檔案id |
| name | 檔名，例如"myfile.gif" |
| type | 檔案型別，例如"image/jpeg" |
| size | 檔案大小，單位為位元組，當啟用了客戶端壓縮功能後，該值可能會改變 |
| 檔案的原始大小，單位為位元組 | |
| 檔案已上傳部分的大小，單位為位元組 | |
| 檔案已上傳部分所佔的百分比，如50就代表已上傳了50% | |
檔案的狀態，可能為以下幾個值之一：plupload.QUEUED, plupload.UPLOADING,
plupload.FAILED, plupload.DONE |
|
| 獲取mOxie.File 物件，想了解mOxie是什麼東西，可以看下https://github.com/moxiecode/moxie/wiki/API |
六、QueueProgress 物件的屬性
plupload例項的total屬性是一個QueueProgress物件
| 屬性 | 描述 |
|---|---|
| size | 上傳佇列中所有檔案加起來的總大小，單位為位元組 |
| 佇列中當前已上傳檔案加起來的總大小,單位為位元組 | |
| 上傳失敗的檔案數量 | |
| 佇列中剩下的(也就是除開已經完成上傳的檔案)需要上傳的檔案數量 | |
| 整個佇列的已上傳百分比，如50就代表50% | |
| 上傳速率，單位為 byte/s，也就是 位元組/秒 |
七、plupload名稱空間上的一些屬性
plupload的名稱空間上有一些屬性，用來表示一些常量。記住，不是plupload例項的屬性，而是plupload的屬性
| 屬性名稱 | 描述 |
|---|---|
| 當前plupload的版本號 | |
值為1，代表上傳佇列還未開始上傳或者上傳佇列中的檔案已經上傳完畢時plupload例項的state屬性值 |
|
值為2，代表隊列中的檔案正在上傳時plupload例項的state屬性值 |
|
值為1，代表某個檔案已經被新增進佇列等待上傳時該檔案物件的status屬性值 |
|
值為2，代表某個檔案正在上傳時該檔案物件的status屬性值 |
|
值為4，代表某個檔案上傳失敗後該檔案物件的status屬性值 |
|
| DONE | 值為5，代表某個檔案上傳成功後該檔案物件的status屬性值 |
| 值為-200，發生http網路錯誤時的錯誤程式碼，例如服務氣端返回的狀態碼不是200 | |
| 值為-300，發生磁碟讀寫錯誤時的錯誤程式碼，例如本地上某個檔案不可讀 | |
| 值為-400，發生因為安全問題而產生的錯誤時的錯誤程式碼 | |
| 值為-500，初始化時發生錯誤的錯誤程式碼 | |
| 值為-602，當選取了重複的檔案而配置中又不允許有重複檔案時的錯誤程式碼 | |
| 值為-702，當檔案大小超過了plupload所能處理的最大值時的錯誤程式碼 |