SWFUpload 是一款結合 Flash 與 JavaScript 的檔案上傳外掛,功能十分強大。以前在專案中我用過幾次,但它的設定參數實在太多,用完就忘、下次要使用前又得回官網翻文件,實在麻煩。於是乾脆把用法記錄下來,也方便英文不太好的朋友查閱,利己利人、一勞永逸。(附註:SWFUpload 早已停止更新,官網也已無法開啟,建議大家改用 Plupload 來取代它。Plupload 以 HTML5 上傳為主,遇到不支援 HTML5 的瀏覽器會自動回退到 Flash 上傳方式,功能非常強大!用法可參考我寫的《前端上傳元件 Plupload 使用指南》。)
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:
<script src='SWFUpload.js'></script>
接著實例化一個 SWFUpload 物件:
var swfu; window.onload = function () { var settings_object = {//定義參數配置對象 upload_url : "https://www.swfupload.org/upload.php", flash_url : "https://www.swfupload.org/swfupload.swf", 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_image_url : "https://www.swfupload.org/button_sprite.png", 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 上傳功能很簡單,就是實例化一個物件;麻煩的地方在於實例化時要用到的設定參數物件,以及各種事件的觸發時機與所帶參數。以下幾個表格整理了開發中常用的內容(並非全部,完整文件請至官網查詢)。
一、設定參數物件中的常用屬性與說明
屬性 | 類型 | 預設值 | 描述 | upload_url | String 處理上傳檔案的伺服器端頁面網址,可以是絕對或相對路徑,相對路徑時相對於當前程式碼所在文件
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 方式(參數附加在網址後的查詢字串)
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 取較小值
flash_url | String swfupload.swf 的絕對或相對路徑(相對於當前頁面),實例化後不可再更改
prevent_swf_caching | Boolean 為 true 時會在 swfupload.swf 網址後加隨機數以阻止快取,避免某些 IE 版本讀取快取 Flash 時出現 bug
button_placeholder_id | String 指定一個 DOM 元素的 id,該元素在實例化後會被 Flash 按鈕取代,作為佔位符
button_placeholder | DOMElement 指定一個 DOM 元素作為佔位符,與 button_placeholder_id 同時存在時以前者為優先
button_image_url | String 指定 Flash 按鈕的背景圖,必須是 sprite 圖,由上到下包含正常、滑鼠懸停、按下、禁用四種狀態,因此高度應為按鈕高度的四倍
button_width | Number 指定 Flash 按鈕的寬度
button_height | Number 指定 Flash 按鈕的高度,應為背景圖高度的 1/4
button_text | String 指定按鈕上的文字,也可以是 HTML 程式碼
button_text_style | String 按鈕文字的樣式
button_text_top_padding | Number 按鈕頂部內邊距,可用負值
button_text_left_padding | Number 按鈕左側內邊距,可用負值
button_disabled | Boolean false 為 true 時按鈕禁用,點擊不會觸發任何行為
button_cursor | 滑鼠懸停在按鈕上時的光標樣式,取值參照 SWFUpload.CURSOR 常量
button_window_mode | 指定按鈕的 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() 實現自動上傳;三個參數分別為本次選擇數量、本次加入佇列數量、目前佇列總數
uploadStart ( file object ) | 檔案即將上傳時觸發,是最後一次驗證檔案、附加資訊或做其他處理的機會,回傳 false 可取消本次上傳
uploadProgress ( file object, bytes complete, total bytes ) | 上傳過程中反覆觸發,可用來實作進度條;參數為檔案資訊、已上傳位元組數、總位元組數
uploadError ( file object, error code, message ) | 上傳被中斷或未成功時觸發;停止、取消上傳或在 uploadStart 回傳 false 都會引發,但被取消且仍在佇列中則不會;錯誤碼參照 SWFUpload.UPLOAD_ERROR
uploadSuccess ( file object, server data, received response ) | 檔案上傳成功後觸發;參數為檔案資訊、伺服器端輸出的資料
uploadComplete( file object ) | 一次上傳流程完成時(不論成功與否)觸發,表示本次上傳結束、佇列中下一個檔案可開始上傳
三、SWFUpload 實例的方法
多數方法為動態改變設定參數物件的方法。
destroy ( ) | 不再需要時,用來銷毀實例與 DOM 元素
startUpload( file_id ) | 開始上傳佇列中指定檔案,未填 file_id 則上傳第一個
cancelUpload ( file_id, trigger_error_event ) | 取消檔案上傳;trigger_error_event 為 false 時不觸發 uploadError,預設 true
stopUpload ( ) | 終止目前上傳的檔案並觸發 uploadError;無檔案上傳時不做事
getStats ( ) | 取得佇列的 stats object
setStats ( stats_object ) | 修改佇列的 stats_object
getFile ( file_id|index ) | 依檔案 id 或索引取得 File Object;用 id 只能取佇列內檔案,用索引則可取全部
addPostParam ( name, value) | 往 post_params 附加資訊中增加鍵/值對
removePostParam ( name) | 移除 post_params 中的某個鍵/值對
addFileParam ( file_id, name, value) | 為特定檔案增加隨之上傳的附加資訊,僅該檔案上傳時才一起送出
removeFileParam ( file_id, name) | 移除透過 addFileParam 增加的附加資訊
setUploadURL ( url) | 動態設定 upload_url
setPostParams ( param_object) | 動態設定 post_params,新值覆蓋舊值,須為物件直接量且屬性與值皆為字串
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) | 動態設定按鈕寬高,數值型別且不帶單位
setButtonText ( text) | 動態設定 button_text
setButtonTextStyle ( css_style_text) | 動態設定 button_text_style
setButtonTextPadding ( left, top ) | 動態設定按鈕左側與頂部內邊距
setButtonDisabled ( isDisabled ) | 動態啟用或禁用按鈕
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 已成功上傳的檔案數量
upload_errors | Number 上傳失敗的檔案數量(含被取消)
upload_cancelled | Number 被取消上傳的檔案數量
queue_errors | Number 觸發 fileQueueError 的檔案數量
六、一些常量
便於理解的常數定義。
常量名 | 描述 | SWFUpload.instances | 一個物件,代表頁面上所有 SWFUpload 實例引用的集合,以 movieName 屬性索引
SWFUpload.movieCount | 頁面上 SWFUpload 實例的數量
SWFUpload.QUEUE_ERROR.QUEUE_LIMIT_EXCEEDED | 選取的檔案超過允許數量
SWFUpload.QUEUE_ERROR.FILE_EXCEEDS_SIZE_LIMIT | 檔案體積超過允許大小
SWFUpload.QUEUE_ERROR.ZERO_BYTE_FILE | 檔案是空的
SWFUpload.QUEUE_ERROR.INVALID_FILETYPE | 不允許的檔案類型
SWFUpload.UPLOAD_ERROR.HTTP_ERROR | 伺服器回傳狀態碼非 200
SWFUpload.UPLOAD_ERROR.MISSING_UPLOAD_URL | 未設定 upload_url
SWFUpload.UPLOAD_ERROR.IO_ERROR | 讀取或傳輸檔案時發生錯誤
SWFUpload.UPLOAD_ERROR.SECURITY_ERROR | 上傳受到安全限制
SWFUpload.UPLOAD_ERROR.UPLOAD_LIMIT_EXCEEDED | 上傳數量超過允許最大值
SWFUpload.UPLOAD_ERROR.UPLOAD_FAILED | 上傳出現錯誤
SWFUpload.UPLOAD_ERROR.SPECIFIED_FILE_ID_NOT_FOUND | 傳給 startUpload() 的 file_id 不存在
SWFUpload.UPLOAD_ERROR.FILE_VALIDATION_FAILED | uploadStart() 中回傳了 false
SWFUpload.UPLOAD_ERROR.FILE_CANCELLED | 上傳被取消
SWFUpload.UPLOAD_ERROR.UPLOAD_STOPPED | 上傳被終止
SWFUpload.FILE_STATUS.QUEUED | 檔案在佇列中等待上傳
SWFUpload.FILE_STATUS.IN_PROGRESS | 檔案正在上傳
SWFUpload.FILE_STATUS.ERROR | 檔案在加入佇列或上傳時出錯
SWFUpload.FILE_STATUS.COMPLETE | 檔案已上傳成功
SWFUpload.CURSOR.ARROW | 滑鼠以箭頭顯示
SWFUpload.CURSOR.HAND | 滑鼠以手形顯示
SWFUpload.WINDOW_MODE.WINDOW | Flash 按鈕顯示在所有 DOM 元素之上
SWFUpload.WINDOW_MODE.OPAQUE | 允許其他 DOM 元素覆蓋 Flash 按鈕
SWFUpload.WINDOW_MODE.TRANSPARENT | 允許 Flash 按鈕透明顯示
內容相當多,如果還不清楚怎麼使用,建議先看官網的使用流程,理解大致用法後,再回頭參考這些屬性、事件、方法與常數。