文件上傳利器SWFUpload使用指南

時間 2019-11-11

原文原文鏈接

SWFUpload是一個flash和js相結合而成的文件上傳插件，其功能很是強大。之前在項目中用過幾回，但它的配置參數太多了，用事後就忘記怎麼用了，到之後要用時又獲得官網上看它的文檔，真是太煩了。因此索性就把它的用法記錄下來，也方便英語拙計的同窗查看，利人利己，一勞永逸。 php

SWFUpload的特色： css

一、用flash進行上傳，頁面無刷新，且可自定義Flash按鈕的樣式; html

二、能夠在瀏覽器端就對要上傳的文件進行限制; 瀏覽器

三、容許一次上傳多個文件，但會有一個上傳隊列，隊列裏文件的上傳是逐個進行的，服務器端接收文件時跟普通的表單上傳文件是同樣的; 緩存

四、提供了豐富的事件接口供開發者使用; 安全

SWFUpload的文件上傳流程是這樣的：服務器

一、引入相應的js文件 dom

二、實例化SWFUpload對象，傳入一個配置參數對象進行各方面的配置。函數

三、點擊SWFUpload提供的Flash按鈕，彈出文件選取窗口選擇要上傳的文件； post

四、文件選取完成後符合規定的文件會被添加到上傳的隊列裏；

五、調用startUpload方法讓隊列裏文件開始上傳；

六、文件上傳過程當中會觸發相應的事件，開發者利用這些事件來更新ui、處理錯誤、發出提示等等；

SWFUpload包括三部分的內容：SWFUpload.js、swfupload.swf、初始化配置參數及各類事件處理函數。因此首先在頁面引入SWFUpload.js

1	<script src='SWFUpload.js'></script>

而後實例化一個SWFUpload對象：

         var swfu; 
       
         window.onload =function () { 
       
             var settings_object = {//定義參數配置對象 
       
                 upload_url :" 
        http://www.swfupload.org/upload.php", 
       
                     flash_url :" 
        http://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 :" 
        http://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上傳功能很簡單，就是實例化一個swfupload對象。但繁瑣的地方就在於實例化實要用到的參數配置對象，以及各類事件的發生時機以和提供的參數。因此重點來了。下面幾個表格對開發中要用到的東西列舉了出來，雖然已經蠻多了，但並非swfupload的所有，我列出來的只是經常使用的。要查看完整的文檔，請到swfupload官網上查詢。

1、配置參數對象中的經常使用屬性及說明

屬性	類型	默認值	描述
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事件偵聽函數

2、各類事件說明

要實現與用戶的交互，靠的就是在這些事件上作文章了

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 )
當一次文件上傳的流程完成時（不論是成功的仍是不成功的）會觸發該事件，該事件代表本次上傳已經完成，上傳隊列裏的下一個文件能夠開始上傳了。該事件發生後隊列中下一個文件的上傳將會開始

3、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的值

4、文件信息對象 File Object

在事件監聽函數中，常常要用到文件信息對象來獲取文件的信息以供下一步的操做

屬性	類型	描述
id	String	SWFUpload定義的文件id,用來控制文件的上傳
index	Number	文件的索引，用在getFile(i)方法中
name	String	文件的原始名稱，不包括路徑
type	String	文件類型
creationdate	Date	文件的建立日期
modificationdate	Date	文件的最後修改日期
filestatus	Number	當前文件的狀態，詳細的請參照SWFUpload.FILE_STATUS中定義的常量

5、隊列狀態對象 Stats Object

用來獲取當前隊列的情況

屬性	類型	描述
in_progress	Number	獲得的值爲1或0，代表當前隊列是否有文件正在上傳中
files_queued	Number	目前上傳隊列中的文件數量
successful_uploads	Number	已成功上傳(指觸發了uploadSuccess事件)的文件數量
upload_errors	Number	上傳失敗的文件數量(包括被取消上傳的文件)
upload_cancelled	Number	被取消上傳的文件數量
queue_errors	Number	觸發了fileQueueError事件的文件數量

6、一些常量

定義的一些常量，便於理解

常量名	描述
SWFUpload.instances	該常量是一個對象，表明一個頁面上全部的SWFUpload實例的引用的集合，用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()方法傳入的文件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.FILE_STATUS.	文件被取消上傳

SWFUpload.CURSOR.ARROW	鼠標以箭頭顯示
SWFUpload.CURSOR.HAND	鼠標以手形顯示

SWFUpload.WINDOW_MODE.WINDOW	Flash按鈕會顯示在頁面的全部dom元素上面
SWFUpload.WINDOW_MODE.OPAQUE	容許其餘dom元素覆蓋住Flash按鈕
SWFUpload.WINDOW_MODE.TRANSPARENT	容許Flash按鈕透明顯示