swfupload參數說明

文件上傳利器SWFUpload使用指南

被風遺忘 發佈於 9個月前，共有 5 條評論

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

SWFUpload的特色：

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

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

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

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

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

一、引入相應的js文件

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

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

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

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

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

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

 

<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(){}
...等等

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