DIV CSS 佈局教程網

檔案上傳外掛 SWFUpload 使用指南完整整理
編輯:關於JavaScript     

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 按鈕透明顯示

內容相當多,如果還不清楚怎麼使用,建議先看官網的使用流程,理解大致用法後,再回頭參考這些屬性、事件、方法與常數。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved