SWFUpload是一個flash和js相結合而成的文件上傳插件，其功能非常強大。以前在項目中用過幾次，但它的配置參數太多了，用過後就忘記怎麼用了，到以後要用時又得到官網上看它的文檔，真是太煩了。所以索性就把它的用法記錄下來，也方便英語拙計的同學查看，利人利己，一勞永逸。
SWFUpload的特點：
1、用flash進行上傳，頁面無刷新，且可自定義Flash按鈕的樣式;
2、可以在瀏覽器端就對要上傳的文件進行限制;
3、允許一次上傳多個文件，但會有一個上傳隊列，隊列裏文件的上傳是逐個進行的，服務器端接收文件時跟普通的表單上傳文件是一樣的;
4、提供了豐富的事件接口供開發者使用;
SWFUpload的文件上傳流程是這樣的：
1、引入相應的js文件
2、實例化SWFUpload對象，傳入一個配置參數對象進行各方面的配置。
3、點擊SWFUpload提供的Flash按鈕，彈出文件選取窗口選擇要上傳的文件；
4、文件選取完成後符合規定的文件會被添加到上傳的隊列裏；
5、調用startUpload方法讓隊列裏文件開始上傳；
6、文件上傳過程中會觸發相應的事件，開發者利用這些事件來更新ui、處理錯誤、發出提示等等；
SWFUpload包括三部分的內容：SWFUpload.js、swfupload.swf、初始化配置參數及各種事件處理函數。所以首先在頁面引入SWFUpload.js
|
1
|
<script
src='SWFUpload.js'></script> |
然後實例化一個SWFUpload對象：
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
|
var swfu; window.onload
= function ()
{ var settings_object
= {//定義參數配置對象 file_post_name
: "Filedata", post_params
: { "post_param_name_1" :
"post_param_value_1", "post_param_name_2" :
"post_param_value_2", "post_param_name_n" :
"post_param_value_n" }, use_query_string
: false, requeue_on_error
: false, http_success
: [201, 202], assume_success_timeout
: 0, file_types
: "*.jpg;*.gif", file_types_description:
"Web
Image Files", file_size_limit
: "1024", file_upload_limit
: 10, file_queue_limit
: 2, debug
: false, prevent_swf_caching
: false, preserve_relative_urls
: false, button_placeholder_id
: "element_id", button_width
: 61, button_height
: 22, button_text
: "<b>Click</b>
<span class="redText">here</span>", button_text_style
: ".redText
{ color: #FF0000; }", button_text_left_padding
: 3, button_text_top_padding
: 2, button_action
: SWFUpload.BUTTON_ACTION.SELECT_FILES, button_disabled
: false, button_cursor
: SWFUpload.CURSOR.HAND, button_window_mode
: SWFUpload.WINDOW_MODE.TRANSPARENT, swfupload_loaded_handler
: swfupload_loaded_function, file_dialog_start_handler
: file_dialog_start_function, file_queued_handler
: file_queued_function, file_queue_error_handler
: file_queue_error_function, file_dialog_complete_handler
: file_dialog_complete_function, upload_start_handler
: upload_start_function, upload_progress_handler
: upload_progress_function, upload_error_handler
: upload_error_function, upload_success_handler
: upload_success_function, upload_complete_handler
: upload_complete_function, debug_handler
: debug_function, }; swfu
= new SWFUpload(settings_object);//實例化一個SWFUpload，傳入參數配置對象};/*定義各種事件監聽函數*/function swfupload_loaded_function(){}function file_dialog_start_function(){}...等等 |
我們看到要實現一個swfupload上傳功能很簡單，就是實例化一個swfupload對象。但繁瑣的地方就在於實例化實要用到的參數配置對象，以及各種事件的發生時機以和提供的參數。所以重點來了。下面幾個表格對開發中要用到的東西列舉了出來，雖然已經蠻多了，但並不是swfupload的全部，我列出來的只是常用的。要查看完整的文檔，請到swfupload官網上查詢。
一、配置參數對象中的常用屬性及說明
| 屬性 | 類型 | 默認值 | 描述 |
|---|---|---|---|
| upload_url | String | 處理上傳文件的服務器端頁面的url地址，可以是絕對地址，也可以是相對地址，當爲相對地址時相對的是當前代碼所在的文檔地址 | |
| preserve_relative_urls | Boolean | false | 如果爲false則SWFUpload會把swfupload.swf用到的相對地址轉換爲絕對地址，以達到更好的兼容性 |
| file_post_name | String | Filedata | 相當於用普通的文件域上傳文件時的name屬性，服務器端接收頁面通過該名稱來獲取上傳的文件 |
| post_params | Object(直接量) | 一個對象直接量，裏面的鍵/值對會隨着每一個文件一起上傳，文件上傳要附加一些信息時很有用 | |
| use_query_string | Boolean | false | 爲false時,post_params屬性定義的參數會以post方式上傳；爲true時，則會以get方式上傳（即參數會以查詢字符串的形式附加到url後面） |
| file_types | String | 該屬性指定了允許上傳的文件類型，當有多個類型時使用分號隔開，比如：*.jpg;*.png ,允許所有類型時請使用 *.* | |
| file_types_description | String | 指定在文件選取窗口中顯示的文件類型描述，起一個提示和說明的作用吧 | |
| file_size_limit | String | 指定要上傳的文件的最大體積，可以帶單位，合法的單位有:B、KB、MB、GB，如果省略了單位，則默認爲KB。該屬性爲0時，表示不限制文件的大小。 | |
| file_upload_limit | Number | 指定最多能上傳多少個文件，當上傳成功的文件數量達到了這個最大值後，就不能再上傳文件了，也不能往上傳隊列裏添加文件了。把該屬性設爲0時表示不限制文件的上傳數量。 | |
| file_queue_limit | Number | 指定文件上傳隊列裏最多能同時存放多少個文件。當超過了這個數目後只有當隊列裏有文件上傳成功、上傳出錯或被取消上傳後，等同數量的其他文件纔可以被添加進來。當file_upload_limit的數值或者剩餘的能上傳的文件數量小於file_queue_limit時，則取那個更小的值 | |
| flash_url | String | swfupload.swf文件的絕對或相對地址，相對地址是指相對於當前的頁面地址。實例化swfupload後，就不能再改變該屬性的值了。 | |
| prevent_swf_caching | Boolean | 爲true時會加一個隨機數在swfupload.swf地址的後面，以阻止flash影片被緩存，這是爲了防止某些版本的IE瀏覽器在讀取緩存的falsh影片時出現的bug | |
| button_placeholder_id | String | 指定一個dom元素的id,該dom元素在swfupload實例化後會被Flash按鈕代替，這個dom元素相當於一個佔位符 | |
| button_placeholder | DOMElement | 指定一個dom元素,該dom元素在swfupload實例化後會被Flash按鈕代替，這個dom元素相當於一個佔位符。當button_placeholder_id與button_placeholder都存在時，以button_placeholder_id爲優先 | |
| button_image_url | String |
指定Flash按鈕的背景圖片，相對地址或絕對地址都可以。該地址會受到preserve_relative_urls屬性的影響，遵從與upload_url一樣的規則。 該背景圖片必須是一個sprite圖片,從上到下包含了Flash按鈕的正常、鼠標懸停、按下、禁用這四種狀態。因此該圖片的高度應該是Flash按鈕高度的四倍 |
|
| button_width | Number | 指定Flash按鈕的寬度 | |
| button_height | Number | 指定Flash按鈕的高度，應該爲button_image_url所指定的按鈕背景圖片高度的1/4 | |
| button_text | String | 指定Flash按鈕上的文字，也可以是html代碼 | |
| button_text_style | String | Flash按鈕上的文字的樣式，使用方法見示例 | |
| button_text_top_padding | Number | 指定Flash按鈕頂部的內邊距，可使用負值 | |
| button_text_left_padding | Number | 指定Flash按鈕左邊的內邊距，可使用負值 | |
| button_disabled | Boolean | false | 爲true時Flash按鈕將變爲禁用狀態，點擊也不會觸發任何行爲 |
| button_cursor | 指定鼠標懸停在Flash按鈕上時的光標樣式，可用值爲SWFUpload.CURSOR裏定義的常量 | ||
| button_window_mode | 指定Flash按鈕的WMODE屬性，可用值爲SWFUpload.WINDOW_MODE裏定義的常量 | ||
| file_dialog_start_handler | Function | fileDialogStart事件偵聽函數 | |
| file_queued_handler | Function | fileQueued事件偵聽函數 | |
| file_queue_error_handler | Function | fileQueueError事件偵聽函數 | |
| file_dialog_complete_handler | Function | fileDialogComplete事件偵聽函數 | |
| upload_start_handler | Function | uploadStart事件偵聽函數 | |
| upload_progress_handler | Function | uploadProgress事件偵聽函數 | |
| upload_error_handler | Function | uploadError事件偵聽函數 | |
| upload_success_handler | Function | uploadSuccess事件偵聽函數 | |
| upload_complete_handler | Function | uploadComplete事件偵聽函數 |
二、各種事件說明
要實現與用戶的交互，靠的就是在這些事件上做文章了
| fileDialogStart ( ) | ||
|---|---|---|
| 在文件選取窗口將要彈出時觸發 | ||
| fileQueued ( file object ) | ||
| 當一個文件被添加到上傳隊列時會觸發此事件，提供的唯一參數爲包含該文件信息的file object對象 | ||
| fileQueueError ( file object, error code, message ) | ||
|
當文件添加到上傳隊列失敗時觸發此事件，失敗的原因可能是文件大小超過了你允許的數值、文件是空的或者文件隊列已經滿員了等。 該事件提供了三個參數。第一個參數是當前出現問題的文件對象，第二個參數是具體的錯誤代碼，可以參照SWFUpload.QUEUE_ERROR中定義的常量 |
||
| fileDialogComplete ( number of files selected, number of files queued, total number of files in the queued ) | ||
|
當文件選取完畢且選取的文件經過處理後（指添加到上傳隊列），會立即觸發該事件。可以在該事件中調用this.startUpload()方法來實現文件的自動上傳 參數number of files selected指本次在文件選取框裏選取的文件數量 參數number of files queued指本次被添加到上傳隊列的文件數量 參數total number of files in the queued指當前上傳隊列裏共有多少個文件（包括了本次添加進去的文件） |
||
| uploadStart ( file object ) | ||
|
當文件即將上傳時會觸發該事件,該事件給了你在文件上傳前的最後一次機會來驗證文件信息、增加要隨之上傳的附加信息或做其他工作。可以通過返回false來取消本次文件的上傳 參數file object爲當前要上傳的文件的信息對象 |
||
| uploadProgress ( file object, bytes complete, total bytes ) | ||
|
該事件會在文件的上傳過程中反覆觸發，可以利用該事件來實現上傳進度條 參數file object爲文件信息對象 參數bytes complete爲當前已上傳的字節數 參數total bytes爲文件總的字節數 |
||
| uploadError ( file object, error code, message ) | ||
|
文件上傳被中斷或是文件沒有成功上傳時會觸發該事件。停止、取消文件上傳或是在uploadStart事件中返回false都會引發這個事件，但是如果某個文件被取消了但仍然還在隊列中則不會觸發該事件 參數file object爲文件信息對象 參數error code爲錯誤代碼，具體的可參照SWFUpload.UPLOAD_ERROR中定義的常量 |
||
| uploadSuccess ( file object, server data, received response ) | ||
|
當一個文件上傳成功後會觸發該事件 參數file object爲文件信息對象 參數server data爲服務器端輸出的數據 |
||
| uploadComplete( file object ) | ||
| 當一次文件上傳的流程完成時（不管是成功的還是不成功的）會觸發該事件，該事件表明本次上傳已經完成，上傳隊列裏的下一個文件可以開始上傳了。該事件發生後隊列中下一個文件的上傳將會開始 |
三、swfupload實例的方法
方法中大多數是動態改變參數配置對象的方法
| destroy ( ) | ||
|---|---|---|
| 當不需要再使用SWFUpload了的時候,可以使用該方法來銷燬它的實例和dom元素 | ||
| startUpload( file_id ) | ||
|
開始上傳隊列中指定的文件 參數file_id代表要上傳的文件的id，如果未填寫這個參數，則會上傳隊列中第一個文件 |
||
| cancelUpload ( file_id, trigger_error_event ) | ||
|
取消文件的上傳 參數file_id爲要取消的文件的id,如果該參數爲undefined或者未填寫，則會取消隊列裏的第一個文件 參數trigger_error_event接受一個布爾值，當爲false時取消文件不會觸發uploadError事件，默認爲true |
||
| stopUpload ( ) | ||
| 終止當前正在上傳的文件，會觸發uploadError事件。如果當前沒有文件在上傳，則該方法什麼都不會做 | ||
| getStats ( ) | ||
| 獲取隊列的stats object | ||
| setStats ( stats_object ) | ||
| 修改隊列的stats_object，傳入修改過的stats_object作爲參數 | ||
| getFile ( file_id|index ) | ||
| 根據文件id或文件索引來獲取一個File Object,當使用文件id時只能獲得隊列裏的文件，當使用文件索引時所有文件（包括隊列內和隊列外）都可獲得 | ||
| addPostParam ( name, value) | ||
| 往配置對象中post_params指定的附加信息對象中增加鍵/值對 | ||
| removePostParam ( name) | ||
| 移除置配置對象中的post_params包含的某一個鍵/值對，參數name爲要移除的值的鍵名 | ||
| addFileParam ( file_id, name, value) | ||
|
爲某個特定文件增加隨之一起上傳的附加信息。注意，只有在該指定的文件上傳時，附加的信息纔會一起上傳。而配置對象中post_param設置的附加信息在任一文件上傳時都會與之一起發送。 參數file_id爲要指定的文件id,參數name和value分別爲附加信息的名稱和值 |
||
| removeFileParam ( file_id, name) | ||
| 移除通過addFileParam方法增加的附加信息，兩個參數相信就不用我多講了吧 | ||
| setUploadURL ( url) | ||
| 動態設置配置對象中upload_url的值 | ||
| setPostParams ( param_object) | ||
|
動態設置配置對象中post_params屬性的值，新的值會覆蓋舊的值。 參數param_object必須爲一個對象直接量，且裏面的屬性和值都只能爲字符串 |
||
| setFileTypes ( types, description) | ||
| 動態設置配置對象中file_types 和 file_types_description屬性的值。兩個參數都不能省略 | ||
| setFileSizeLimit ( file_size_limit) | ||
| 動態設置配置對象中file_size_limit屬性的值 | ||
| setFileUploadLimit ( file_upload_limit) | ||
| 動態設置配置對象中file_upload_limit屬性的值 | ||
| setFileQueueLimit ( file_queue_limit) | ||
| 動態設置配置對象中file_queue_limit屬性的值 | ||
| setFilePostName ( file_post_name) | ||
| 動態設置配置對象中file_post_name屬性的值 | ||
| setUseQueryString ( use_query_string) | ||
| 動態設置配置對象中use_query_string屬性的值 | ||
| setButtonImageURL ( url) | ||
| 動態設置配置對象中button_image_url屬性的值 | ||
| setButtonDimensions ( width, height) | ||
| 動態設置Flash按鈕的寬度和高度，兩個參數分別爲寬度和高度的值，類型爲數字，且不能帶單位 | ||
| setButtonText ( text) | ||
| 動態設置配置對象中button_text屬性的值 | ||
| setButtonTextStyle ( css_style_text) | ||
| 動態設置配置對象中button_text_style屬性的值 | ||
| setButtonTextPadding ( left, top ) | ||
| 動態設置Flash按鈕的左邊內邊距和頂部內邊距 | ||
| setButtonDisabled ( isDisabled ) | ||
| 動態對Flash按鈕進行禁用和不禁用的操作，參數爲一個布爾值 | ||
| setButtonCursor ( buttonCursor ) | ||
| 動態設置配置對象中button_cursor的值 |
四、文件信息對象 File Object
在事件監聽函數中，經常要用到文件信息對象來獲取文件的信息以供下一步的操作
| 屬性 | 類型 | 描述 |
|---|---|---|
| id | String | SWFUpload定義的文件id,用來控制文件的上傳 |
| index | Number | 文件的索引，用在getFile(i)方法中 |
| name | String | 文件的原始名稱，不包括路徑 |
| type | String | 文件類型 |
| creationdate | Date | 文件的創建日期 |
| modificationdate | Date | 文件的最後修改日期 |
| filestatus | Number | 當前文件的狀態，詳細的請參照SWFUpload.FILE_STATUS中定義的常量 |
五、隊列狀態對象 Stats Object
用來獲取當前隊列的狀況
| 屬性 | 類型 | 描述 |
|---|---|---|
| in_progress | Number | 得到的值爲1或0，表明當前隊列是否有文件正在上傳中 |
| files_queued | Number | 目前上傳隊列中的文件數量 |
| successful_uploads | Number | 已成功上傳(指觸發了uploadSuccess事件)的文件數量 |
| upload_errors | Number | 上傳失敗的文件數量(包括被取消上傳的文件) |
| upload_cancelled | Number | 被取消上傳的文件數量 |
| queue_errors | Number | 觸發了fileQueueError事件的文件數量 |
六、一些常量
定義的一些常量，便於理解
內容太多了，感覺有點亂了，如果還不清楚怎麼使用，建議看下官網的使用流程，明白怎麼使用後再來看這些屬性、事件、方法、常量什麼的吧。