SWFUpload v2 說明文檔

SWFUpload
SWFUpload 2
概述
入門
SWFUpload JavaScript 對象
1. 構造器
2. 全局變量和常量
3. 屬性
  1. customSettings
  2. movieName
4. 方法
  1. addSetting (不推薦使用)
  2. getSetting (不推薦使用)
  3. retrieveSetting (v2.1.0中已刪除)
  4. destroy (v2.1.0中新增)
  5. displayDebugInfo
  6. selectFile
  7. selectFiles
  8. startUpload
  9. cancelUpload
  10. stopUpload
  11. getStats
  12. setStats
  13. getFile
  14. addPostParam
  15. removePostParam
  16. addFileParam
  17. removeFileParam
  18. setUploadURL
  19. setPostParams
  20. setFileTypes
  21. setFileSizeLimit
  22. setFileUploadLimit
  23. setFileQueueLimit
  24. setFilePostName
  25. setUseQueryString
  26. setDebugEnabled
5. 事件
6. SWFUpload 功能對象
SWFUpload 插件（未譯）
存在的問題（未譯）

轉帖：http://gongstring.javaeye.com/blog/480151

SWFUpload

SWFUpload最初是由Vinterwebb.se開發的一個客戶端的上傳工具. 它結合了FLASH和JavaScript的功能，以提供一種超越了傳統的瀏覽器中<input type="file" />標籤提供的文件上傳功能。

SWFUpload提供的主要功能:

在文件選擇對話框中能夠進行文件多選
頁面無刷新的上傳
提供上傳進度的事件回調，實時顯示上傳進度
良好的瀏覽器兼容性
採用了命名空間以兼容其它JS的庫 (例如 jQuery, Prototype, 等等)
對FLASH8和FLASH9播放器的支持

SWFUpload背後的設計思想和其它基於Flash的上傳工具是不同的。它將瀏覽器的中UI交給開發人員來控制。開發人員能夠利用XHTML,CSS,Javascript來定製符合他們網站風格的UI上傳元素。然後使用它提供的一組簡單的JS事件來更新上傳狀態，開發人員能夠利用這些事件來及時更新頁面中的上傳進度UI。

SWFUpload v2

SWFUpload v2包含了新的高級功能，改善了穩定性，解決了FlashPlayer中的一些bug，並且提供一套有用的插件。新的功能包括：

在文件上傳的同時能夠發送額外的POST數據(只針對Flash 9 版本)
針對每一個文件上傳發送POST/GET數據
更直觀的事件回調
動態修改實例設置
接收服務端返回的數據 (只針對Flash 9 版本)
非取消形式的停止文件上傳
自定義上傳的順序
支持單文件、多文件的文件的選擇
文件入隊數量，文件上傳數量和文件大小的限制
更合理地處理0字節的文件
針對每個文件在上傳前都提供一個最後確認的時間回調
解決了v1.0.2版本中未描述到的關於Flash的bug
解決的v1.0.2中的bug:
- 在IE中，刷新的時候FLASH無法加載（詳細可見我之前的debug過程）
- 在FireFox中，如果窗口的滾動條沒有回滾到頂部，那麼Flash無法加載
- Race-conditions when files are cached
兼容ASP.Net Forms

SWFUpload v2 延續了SWFUpload的設計目標，將UI分離以交給開發人員控制和後續擴展

概述

傳統的HTML上傳

標準的HTML上傳表單爲用戶提供一個文本框和按鈕來選擇文件，選中的文件是隨着form表單提交的。整個文件上傳完成之後，下一個頁面纔會顯示，並且不能對選擇的文件做預設的文件檢驗，例如文件大小限制，文件類型限制。當文件上傳時，用戶獲得的可用的反饋信息很少。

傳統的HTML上傳模式十分簡單，線性的，幾乎所有瀏覽器都支持它。

SWFUpload

SWFUpload使用一個隱藏的Flash影片來控制文件的選擇和上傳。JavaScript用來激活文件選擇對話框。此文件選擇對話框是可以設置允許用戶選擇一個單獨的文件或者是多個文件。選擇的的文件類型也是可以被限制的，因此用戶只能選擇指定的適當的文件，例如*.jgp;*.gif。

當選定文件以後，每個文件都會被驗證和處理。當Flash上傳文件的時候，由開發人員預定義的Javascript事件會被定時觸發以便來更新頁面中的UI，同時還提供上傳狀態和錯誤信息。

選定的文件的上傳和它所在頁面、表單是獨立的。每個文件都是單獨上傳的，這就保證了服務端腳本能夠在一個時間點更容易地處理單個文件。雖然Flash提供了上傳服務，但是頁面並不會提交或者重新載入。相比於標準的HTML Form，SWFUpload的使用方式更像是AJAX程序，頁面中的Form會和FLASH控制的文件上傳單獨處理。

入門

SWFUpload並不是拖放式的上傳控件，它需要JavaScript和DOM的知識。一些可用的演示展示了它能夠完成什麼事情以及它是如何完成這些常見的任務。

SWFUpload由4部分組成：

初始化和設置
JavaScript 庫: SWFUpload.js
Flash控制元素: SWFUpload_f8.swf 或者 SWFupload_f9.swf
事件處理

使用SWFUpload遇到的多數問題是由不正確地設置或者定義了糟糕的處理事件引起的。

初始化和設置

SWFpload必須在頁面中初始化，一般可以在window.onload事件中完成此操作。它的構造函數需要一個Object類型的設置對象。這個設置對象一般是一個直接定義的Object類型變量，直接傳遞給SWFUpload的構造函數。

初始化的SWFUpload對象的引用需要保留下來，因爲當顯示文件選擇對話框和啓動文件上傳的時候需要這個實例的引用。

例如:用直接定義的Object類型變量設置初始化SWFUpload對象

var swfu;
window.onload = function () {
swfu = new SWFUpload({
upload_url : "http://www.swfupload.org/upload.php",
flash_url : "http://www.swfupload.org/swfupload_f9.swf",
file_size_limit : "20480"
});
};

例如:用存儲在變量中的設置對象初始化SWFUpload對象

var swfu;
window.onload = function () {
var settings_object = {
upload_url : "http://www.swfupload.org/upload.php",
flash_url : "http://www.swfupload.org/swfupload_f9.swf",
file_size_limit : "20480"
};
swfu = new SWFUpload(settings_object);
};

JavaScript 庫

該JavaScript庫文件(swfupload.js)應該包含在需要上傳功能的頁面中。它對 Flash Player 8 和 Flash Player 9 SWFUpload 版本都是兼容、可用的。

當SWFUpload創建完成並能訪問它的一系列功能時，開發人員可以來控制此實例。

例如: 添加SWFUpload.js到頁面中

<script type="text/javascript" src="http://www.swfupload.org/swfupload.js"></script>

例如: 根據需要的設置來初始化SWFUpload，同時把它的seleteFiles方法綁定到一個按鈕的Click事件上。

var swfu = new SWFUpload({
upload_url : "http://www.swfupload.org/upload.php",
flash_url : "http://www.swfupload.org/swfupload_f9.swf"
});
document.getElementById("BrowseButton").onclick = function () { swfu.selectFiles(); };

Flash 控制元素

SWFUpload JavaScript庫動態加載Flash控制元素（swfupload_f8.swf/swfupload_f9.swf）。該Flash控制元素有兩個版本。swfupload_f8.swf支持Flash Player8以及更高版本。它在提供了更好的兼容性同時犧牲了一些功能。swfupload_f9.swf支持Flash Player9.0.28以及更高版本。它在提供了額外的功能同時犧牲了使用Flash Player8的用戶。

Flash控制元素的文件地址在初始化的時候就應該在SWFUpload設置對象中定義。

Flash控制元素是一個不可見的的Flash影片，它提供了文件瀏覽、檢驗和上傳功能。它不提供任何用戶界面組件，但它會在需要時候通過與Javascript通信來通知瀏覽器處理更新。

事件處理

開發人員必須定義一系列JavaScript函數來處理SWFUpload事件回調，當一些不同的重要事件發生的時候，這些函數會被觸發。

通過處理SWFUpload的事件，開發人員能夠提供關於上傳進度、出錯信息以及上傳完成等的信息反饋。

例如: swfupload的處理事件和初始化

// uploadStart處理事件。該函數變量在設置對象中指定給了upload_start_handler屬性。
var uploadStartEventHandler = function (file) {
var continue_with_upload = true;
return continue_with_upload;
};
//uploadSuccess處理事件。 該函數變量在設置對象中指定給了upload_success_handler屬性。
var uploadSuccessEventHandler = function (file, server_data) {
alert("The file " + file.name + " has been delivered to the server.");
alert("The server responded with " + server_data);
};
//創建SWFUpload實例，設置事件回調函數
var swfu = new SWFUpload({
upload_url : "http://www.swfupload.org/upload.php",
flash_url : "http://www.swfupload.org/swfupload_f9.swf",
file_size_limit : "20480",
upload_start_handler : uploadStartEventHandler,
upload_success_handler : uploadSuccessEventHandler
});

SWFUpload JavaScript 對象

構造函數

SWFUpload(settings object)

返回:一個SWFUpload 實例

var swfupload_instance = new SWFUpload(settings_object);

全局變量和常量

SWFUpload定義了一些全局變量和常量，這對SWFUpload的高級應用程序和處理錯誤都是很有用的，它們都是隻讀的。

SWFUpload.instances

SWFUpload.instances是一個存儲了頁面中所有SWFUpload實例引用的數組。Flash播放器依靠這個數組來調用正確的處理事件。該數組是由movieName屬性來索引的關聯數組。例如：SWFUpload.instances.SWFUpload_0訪問的是第一個實例引用。

注意: SWFUpload.instances不是一個真正的JavaScript數組，實際上它是一個對象（關聯數組）。

SWFUpload.movieCount

SWFUpoad.movieCount是一個全局變量，用於記錄頁面中的SWFUpload實例個數，同時確保給每一個Flash影片分配一個惟一的movieName。

SWFUpload.QUEUE_ERROR

SWFUpload.QUEUE_ERROR是一個包含了Queue Error錯誤碼的JS對象，一般用它來查看fileQueueError事件的中發送的錯誤碼，以確定fileQueueError的具體類型。

SWFUpload.QUEUE_ERROR = {
QUEUE_LIMIT_EXCEEDED : -100,
FILE_EXCEEDS_SIZE_LIMIT : -110,
ZERO_BYTE_FILE : -120,
INVALID_FILETYPE : -130
};

SWFUpload.UPLOAD_ERROR

SWFUpload.UPLOAD_ERROR是一個包含了Upload Error錯誤碼的JS對象，一般用它來查看uploadError事件的中發送的錯誤碼，以確定uploadError的具體類型。

SWFUpload.UPLOAD_ERROR = {
HTTP_ERROR : -200,
MISSING_UPLOAD_URL : -210,
IO_ERROR : -220,
SECURITY_ERROR : -230,
UPLOAD_LIMIT_EXCEEDED : -240,
UPLOAD_FAILED : -250,
SPECIFIED_FILE_ID_NOT_FOUND : -260,
FILE_VALIDATION_FAILED : -270,
FILE_CANCELLED : -280,
UPLOAD_STOPPED : -290
};

SWFUpload.FILE_STATUS

SWFUpload.FILE_STATUS是一個包含File Status狀態碼的JS對象。它可以用來檢測File對象中的file status屬性，以確定文件的狀態。

SWFUpload.FILE_STATUS = {
QUEUED : -1,
IN_PROGRESS : -2,
ERROR : -3,
SUCCESS : -4,
CANCELLED : -5
};

默認處理事件

SWFUpload庫提供了一系列默認的處理事件。當開發人員沒有自定義處理事件時，SWFUpload庫將調用這些默認的處理事件。因此當自定義事件時，不要把這些默認的處理事件覆蓋了。自定義事件是需要在settings對象中被單獨定義的。

屬性

下面這個列表是相關屬性的具體描述。使用其它屬性或者對只讀屬性進行了寫的操作都會造成SWFUpload出現問題。

customSettings (可讀/可寫)

customSettings屬性是一個空的JavaScript對象，它被用來存儲跟SWFUpload實例相關聯的數據。它的內容可以使用設置對象中的custom_settings屬性來初始化。

注意:一些插件使用customSettings對象來實現它們的內部控制。當重寫整個customSettings對象的時候需要務必小心。

例如:

// 初始化包含自定義設置的SWFUpload對象
var swfu = new SWFUpload({
custom_settings : {
custom_setting_1 : "custom_setting_value_1",
custom_setting_2 : "custom_setting_value_2",
custom_setting_n : "custom_setting_value_n",
}
});
swfu.customSettings.custom_setting_1 = "custom_setting_value_1"; // 更改一個存在的自定義設置
swfu.customSettings.myNewCustomSetting = "new custom setting value"; // 添加一個新的自定義設置
//用一個全新的對象重寫customSettings
swfu.customSettings = {
custom_setting_A : "custom_setting_value_A",
custom_setting_B : "custom_setting_value_B"
};

movieName（只讀）

包含了該SWFUpload實例的惟一影片名字。該值被傳遞給Flash，用來完成Flash和JavaScript的通信。該值被用來索引實例在SWFUpload.instances數組中的位置。

方法

下面的方法用來操作SWFUpload。其中有些方法可以跟元素（例如，按鈕）的點擊事件綁定，其它的方法供SWFUpload內部處理事件中調用。

object addSetting(setting_name, value, default_value)

不贊成使用　V2.1.0源碼中註釋：addSetting和getSetting已經不再被使用了，只是考慮到兼容V2版本，才繼續保留在庫中。

object getSetting(setting_name)

不贊成使用　V2.1.0源碼中註釋：addSetting和getSetting已經不再被使用了，只是考慮到兼容V2版本，才繼續保留在庫中。

object retrieveSetting(setting_value, default_value)

v2.1.0中已被刪除

bool destroy()

v2.1.0中新增

用於將一個SWFUpload實例從頁面中銷燬。不但刪除DOM中的Flash元素，同時還刪除SWFUpload實例的相關引用。成功返回true，失敗返回false。

這個方法還沒有針對插件做兼容測試，可能會有不兼容問題。（尤其是SWFObject插件）

提醒SWFUpload在v2.1.0中改寫了Flash插入的代碼，V2版中使用SWFObject插入Flash會造成IE的一個刷新BUG。

void displayDebugInfo()

調用debug方法，在Debug輸出框中顯示SWFUpload實例的設置信息，如果設置中的debug屬性是true，那麼默認是在實例化完成以後自動調用此方法。

void selectFile()

彈出flash的文件選擇對話框，只能選擇單個文件。

void selectFiles()

彈出flash的文件選擇對話框，可一次性選擇多個文件。

void startUpload(file_id)

指定file_id來啓動該文件的上傳，如果file_id被忽略了，那麼默認開始上傳第一個文件。

void cancelUpload(file_id)

指定file_id來退出文件的上傳，從上傳隊列中刪除該文件。

如果忽略file_id，那麼默認文件上傳隊列中的第一個文件將被退出上傳。

如果取消的文件是正在上傳，那麼會觸發uploadError事件。

void stopUpload()

如果當前有文件上傳，那麼停止上傳，並且將文件還原到上傳隊列中。

停止了正在上傳的文件，uploadError事件會被觸發。如果此時沒有正在上傳文件，那麼不會發生任何操作，不會觸發任何事件。

object getStats()

獲取當前狀態的統計對象，具體見Stats Object。

void setStats(stats_object)

Stats統計對象是可以被修改的。如果你希望在上傳完畢之後修改上傳成功或者上傳失敗的統計數目時，那麼可以使用該方法。

提醒：可供修改的屬性只有successful_uploads ，upload_errors，upload_cancelled，queue_errors，並且值必須是Number類型。

object getFile(file_id|index)

根據file_id或者index來獲取文件隊列中的文件對象。file_id是文件對象中的id屬性，index是文件對象中的index屬性。

傳遞Number類型的參數會被認定爲index，那麼返回的是文件隊列（所有嘗試入隊文件，包括因沒有通過文件大小、類型檢測等而觸發fileQueueError，沒有成功加入文件上傳隊列的文件對象）數組中下標爲index的文件對象。如果index不在隊列數組範圍內，那麼返回null。

傳遞非Number類型的參數會被認定爲file_id，那麼返回的是文件上傳隊列（通過文件檢測，準備好進行上傳的文件）數組中id爲file_id的文件對象。如果參數爲空，或者沒有此id的文件對象，那麼返回文件等待隊列中的第一個文件對象，如果第一個文件對象爲空，那麼返回null。

void addPostParam(name, value)

給設置中的post_params對象添加值對，當文件上傳的時候，這個值對會一同在POST中發送。

如果設置的時候，post_params中以及存在該值，那麼實際上會被覆蓋。

提醒：SWFUload存在Cookie bug,你可以使用此方法避免。

void removePostParam(name)

從設置中的post_params對象中刪除name指定的屬性，當文件上傳的時候，刪除的值對不會繼續在POST中發送。

bool addFileParam(file_id, name, value)

爲指定file_id的特定文件對象添加POST值對，如果添加的name屬性已經存在，那麼原值會被覆蓋。

如果需要給所有文件對象添加POST值，那麼可以使用設置中的post_params屬性。

bool removeFileParam(file_id, name)

刪除由addFileParam添加的POST值對.

如果POST設置中沒有此屬性，那麼返回false。

void setUploadURL(url)

動態修改設置中的upload_url屬性。

void setPostParams(param_object)

動態修改post_params，以前的屬性全部被覆蓋。param_object必須是一個JavaScript的基本對象，所有屬性和值都必須是字符串類型。

void setFileTypes(types, description)

動態修改設置中的file_types 和 file_types_description，兩個參數都是必須的。

void setFileSizeLimit(file_size_limit)

動態修改設置中的file_size_limit，此修改針對之後的文件大小過濾有效。file_size_limit參數接收一個單位，有效的單位有B、KB、MB、GB，默認單位是KB。

例如: 2147483648 B, 2097152, 2097152KB, 2048 MB, 2 GB

void setFileUploadLimit(file_upload_limit)

動態修改設置中的file_upload_limit，特殊值0表示無限制。

提醒：這裏限制的是一個SWFUpload實例控制上傳成功的文件總數。

void setFileQueueLimit(file_queue_limit)

動態修改設置中的file_queue_limit，特殊值0表示無限制。

提醒：這裏限制的是文件上傳隊列中（入隊檢測通過的文件會添加到上傳隊列等待上傳）允許排隊的文件總數。

void setFilePostName(file_post_name)

動態修改設置中的file_post_name，注意在Linux環境下，FlashPlayer是忽略此設置的。

void setUseQueryString(use_query_string)

動態修改設置中的use_query_string，設置爲true的時候，SWFUpload以GET形式發送數據，如果爲false，那麼就以POST發送數據。

void setDebugEnabled(debug_enabled)

啓動/禁止 debug輸出，debug_enabled參數是一個布爾值。

事件

SWFUpload在操作過程中會觸發一系列事件，開發者可以利用這些回調的處理事件來控制UI，控制操作或者報告錯誤。

所有的事件都是在SWFUpload實例的上下文中調用的，因此在這些回調的事件中使用this能夠直接訪問到該觸發該事件的實例對象。

flashReady()

該事件函數是內部事件，因此不能被重寫。當SWFupload實例化，加載的FLASH完成所有初始化操作時觸發此事件。

提醒：對應設置中的自定義事件swfupload_loaded_handler

swfUploadLoaded()

V2.1.0版本中已經刪除了此事件

fileDialogStart()

此事件在selectFile或者selectFiles調用後，文件選擇對話框顯示之前觸發。只能同時存在一個文件對話框。

提醒：對應設置中的自定義事件file_dialog_start_handler

fileQueued(file object)

當文件選擇對話框關閉消失時，如果選擇的文件成功加入上傳隊列，那麼針對每個成功加入的文件都會觸發一次該事件（N個文件成功加入隊列，就觸發N次此事件）。

提醒：對應設置中的自定義事件file_queued_handler

fileQueueError(file object, error code, message)

當選擇文件對話框關閉消失時，如果選擇的文件加入到上傳隊列中失敗，那麼針對每個出錯的文件都會觸發一次該事件(此事件和fileQueued事件是二選一觸發，文件添加到隊列只有兩種可能，成功和失敗)。

文件添加隊列出錯的原因可能有：超過了上傳大小限制，文件爲零字節，超過文件隊列數量限制，設置之外的無效文件類型。

具體的出錯原因可由error code參數來獲取，error code的類型可以查看SWFUpload.QUEUE_ERROR中的定義。

提醒：對應設置中的自定義事件file_queue_error_handler

注意：如果選擇入隊的文件數量超出了設置中的數量限制，那麼所有文件都不入隊，此事件只觸發一次。如果沒有超出數目限制，那麼會對每個文件進行文件類型和大小的檢測，對於不通過的文件觸發此事件，通過的文件成功入隊。

fileDialogComplete(number of files selected, number of files queued)

當選擇文件對話框關閉，並且所有選擇文件已經處理完成（加入上傳隊列成功或者失敗）時，此事件被觸發，number of files selected是選擇的文件數目，number of files queued是此次選擇的文件中成功加入隊列的文件數目。

提醒：對應設置中的自定義事件file_dialog_complete_handler

注意：如果你希望文件在選擇以後自動上傳，那麼在這個事件中調用this.startUpload() 是一個不錯的選擇。如果需要更嚴格的判斷，在調用上傳之前，可以對入隊文件的個數做一個判斷，如果大於0，那麼可以開始上傳。

uploadStart(file object)

在文件往服務端上傳之前觸發此事件，可以在這裏完成上傳前的最後驗證以及其他你需要的操作，例如添加、修改、刪除post數據等。

在完成最後的操作以後，如果函數返回false，那麼這個上傳不會被啓動，並且觸發uploadError事件（code爲ERROR_CODE_FILE_VALIDATION_FAILED），如果返回true或者無返回，那麼將正式啓動上傳。

提醒：對應設置中的自定義事件upload_start_handler

uploadProgress(file object, bytes complete, total bytes)

該事件由flash定時觸發，提供三個參數分別訪問上傳文件對象、已上傳的字節數，總共的字節數。因此可以在這個事件中來定時更新頁面中的UI元素，以達到及時顯示上傳進度的效果。

注意: 在Linux下，Flash Player只在所有文件上傳完畢以後才觸發一次該事件，官方指出這是Linux Flash Player的一個bug，目前SWFpload庫無法解決（我沒有測試過）。

提醒：對應設置中的自定義事件upload_progress_handler

uploadError(file object, error code, message)

無論什麼時候，只要上傳被終止或者沒有成功完成，那麼該事件都將被觸發。error code參數表示了當前錯誤的類型，更具體的錯誤類型可以參見SWFUpload.UPLOAD_ERROR中的定義。Message參數表示的是錯誤的描述。File參數表示的是上傳失敗的文件對象。

例如，我們請求一個服務端的一個不存在的文件處理頁面，那麼error code會是-200，message會是404。停止、退出、uploadStart返回false、HTTP錯誤、IO錯誤、文件上傳數目超過限制等，都將觸發該事件，Upload error will not fire for files that are cancelled but still waiting in the queue。（對於官方的這句話我還存在疑問，文件退出以後怎麼還會保留在文件上傳隊列中保留呢？）

提醒：對應設置中的自定義事件upload_error_handler

注意：此時文件上傳的週期還沒有結束，不能在這裏開始下一個文件的上傳。

uploadSuccess(file object, server data)

當文件上傳的處理已經完成（這裏的完成只是指向目標處理程序發送了Files信息，只管發，不管是否成功接收），並且服務端返回了200的HTTP狀態時，觸發此事件。

提醒：對應設置中的自定義事件upload_success_handler

注意：

如果使用的是SWFUpload提供的9.0版本的SWF，那麼server data是服務端處理程序返回的數據。
如果使用的是8.0版本，那麼server data不可用，一直爲undefined。
此時文件上傳的週期還沒有結束，不能在這裏開始下一個文件的上傳。
在window平臺下，如果使用的是9.0版本，那麼服務端的處理程序在處理完文件存儲以後，必須返回一個非空值，否則此事件不會被觸發，隨後的uploadComplete事件也無法執行。

uploadComplete(file object)

當上傳隊列中的一個文件完成了一個上傳週期，無論是成功(uoloadSuccess觸發)還是失敗(uploadError觸發)，此事件都會被觸發，這也標誌着一個文件的上傳完成，可以進行下一個文件的上傳了。

如果要進行多文件自動上傳，那麼在這個時候調用this.startUpload()來啓動下一個文件的上傳是不錯的選擇。

提醒：對應設置中的自定義事件upload_complete_handler

注意：當在進行多文件上傳的時候，中途用cancelUpload取消了正在上傳的文件，或者用stopUpload停止了正在上傳的文件，那麼在uploadComplete中就要很小心的使用this. startUpload()，因爲在上述情況下，uploadError和uploadComplete會順序執行，因此雖然停止了當前文件的上傳，但會立即進行下一個文件的上傳，你可能會覺得這很奇怪，但事實上程序並沒有錯。如果你希望終止整個隊列的自動上傳，那麼你需要做額外的程序處理了。

debug(message)

如果debug setting設置爲true，那麼頁面底部會自動添加一個textArea， SWFUpload庫和Flash都會調用此事件來在頁面底部的輸出框中添加debug信息供調試使用。

提醒：對應設置中的自定義事件debug_handler

SWFUpload功能對象

Settings object

它是一個Object類型的變量，爲SWFUpload的實例初始化提供配置。 其中的每一個配置屬性都只能出現一次。 很多屬性都是可選的，如果可選屬性沒有被配置，那麼會使用SWFUpload庫中默認指定的合適的值，具體可查看setting的詳細介紹。

例如:（setting可以配置的所有屬性）

{
upload_url : "http://www.swfupload.org/upload.php",
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,
file_types : "*.jpg;*.gif",
file_types_description: "Web Image Files",
file_size_limit : "1024",
file_upload_limit : 10,
file_queue_limit : 2,
flash_url : "http://www.swfupload.org/swfupload_f9.swf",
flash_width : "1px",
flash_height : "1px",
flash_color : "#FFFFFF",
debug : false,
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,
custom_settings : {
custom_setting_1 : "custom_setting_value_1",
custom_setting_2 : "custom_setting_value_2",
custom_setting_n : "custom_setting_value_n",
}
}

Settings 描述

upload_url

默認值：空字符串

upload_url設置接收的是一個絕對的或者相對於SWF文件的完整URL。推薦使用完整的絕對路徑，以避免由瀏覽器和FlashPlayer修改了基準路徑設置而造成的請求路徑錯誤。

注意：這裏需要考慮FlashPlayer的安全域模型。

file_post_name

默認值：Filedata

(僅在Flash 9版本中可用)該參數設置了POST信息中上傳文件的name值（類似傳統Form中設置了<input type="file" name="uploadImg"/>的name屬性）。

注意：在Linux下面此參數設置無效，接收的name總爲Filedata，因此爲了保證最大的兼容性，建議此參數使用默認值。

post_params

默認值：空的Object對象

post_params定義的是一個包含值對的object類型數據，每個文件上傳的時候，其中的值對都會被一同發送到服務端。

注意：

設置值對的時候，值只能是字符串或者數字。
Flash8不支持額外的POST參數，因此post_params會以GET的方式發送。

use_query_string

默認值：false

(僅在Flash 9版本中可用) 該屬性可選值爲true和false，設置post_params是否以GET方式發送。如果爲false，那麼則以POST形式發送。

requeue_on_error

默認值：false

該屬性可選值爲true和false。如果設置爲true，當文件對象發生uploadError時（除開fileQueue錯誤和FILE_CANCELLED錯誤），該文件對象會被重新插入到文件上傳隊列的前端，而不是被丟棄。如果需要，重新入隊的文件可以被再次上傳。如果要從上傳隊列中刪除該文件對象，那麼必須使用cancelUpload方法。

跟上傳失敗關聯的所有事件同樣會被一一觸發，因此將上傳失敗的文件重新入隊可能會和Queue Plugin造成衝突（或者是自動上傳整個文件隊列的自定義代碼）。如果代碼中調用了startUpload方法自動進行下一個文件的上傳，同時也沒有采取任何措施讓上傳失敗的文件退出上傳隊列，那麼這個重新入隊的上傳失敗的文件又會開始上傳，然後又會失敗，重新入隊，重新上傳...，進入了無止境的循環。

該設置是在v2.1.0中引入的。

file_types

默認值：*.*

設置文件選擇對話框的文件類型過濾規則，該屬性接收的是以分號分隔的文件類型擴展名，例如“ *.jpg;*.gif”，則只允許用戶在文件選擇對話框中可見並可選jpg和gif類型的文件。默認接收所有類型的文件。

提醒：該設置只是針對客戶端瀏覽器的過濾，對服務端的文件處理中的文件類型過濾沒有任何限制，如果你需要做嚴格的文件過濾，那麼服務端同樣需要程序檢測。

file_types_description

默認值：All Files

設置文件選擇對話框中顯示給用戶的文件描述。

file_size_limit

默認值：0

設置文件選擇對話框的文件大小過濾規則，該屬性可接收一個帶單位的數值，可用的單位有B,KB,MB,GB。如果忽略了單位，那麼默認使用KB。特殊值0表示文件大小無限制。

提醒：該設置只對客戶端的瀏覽器有效，對服務端的文件處理沒有任何限制，如果你需要做嚴格文件過濾，那麼服務端同樣需要程序處理。

file_upload_limit

默認值：0

設置SWFUpload實例允許上傳的最多文件數量，同時也是設置對象中file_queue_limit屬性的上限。一旦用戶已經上傳成功或者添加文件到隊列達到上最大數量，那麼就不能繼續添加文件了。特殊值0表示允許上傳的數量無限制。只有上傳成功（上傳觸發了uploadSuccess事件）的文件纔會在上傳數量限制中記數。使用setStats方法可以修改成功上傳的文件數量。

注意：該值不能跨頁面使用，當頁面刷新以後該值也被重置。嚴格的文件上傳數量限制應該由服務端來檢測、管理。

file_queue_limit

默認值：0

設置文件上傳隊列

站內首發文章

必應珠峯

發佈了74 篇原創文章 · 獲贊 3 · 訪問量 15萬+

私信關注

SWFUpload v2 說明文檔

TOC

SWFUpload

SWFUpload v2

概述

傳統的HTML上傳

SWFUpload

入門

初始化和設置

JavaScript 庫

Flash 控制元素

事件處理

SWFUpload JavaScript 對象

構造函數

全局變量和常量

SWFUpload.instances

SWFUpload.movieCount

SWFUpload.QUEUE_ERROR

SWFUpload.UPLOAD_ERROR

SWFUpload.FILE_STATUS

默認處理事件

屬性

customSettings (可讀/可寫)

movieName（只讀）

方法

object addSetting(setting_name, value, default_value)

object getSetting(setting_name)

object retrieveSetting(setting_value, default_value)

bool destroy()

void displayDebugInfo()

void selectFile()

void selectFiles()

void startUpload(file_id)

void cancelUpload(file_id)

void stopUpload()

object getStats()

void setStats(stats_object)

object getFile(file_id|index)

void addPostParam(name, value)

void removePostParam(name)

bool addFileParam(file_id, name, value)

bool removeFileParam(file_id, name)

void setUploadURL(url)

void setPostParams(param_object)

void setFileTypes(types, description)

void setFileSizeLimit(file_size_limit)

void setFileUploadLimit(file_upload_limit)

void setFileQueueLimit(file_queue_limit)

void setFilePostName(file_post_name)

void setUseQueryString(use_query_string)

void setDebugEnabled(debug_enabled)

事件

flashReady()

swfUploadLoaded()

fileDialogStart()

fileQueued(file object)

fileQueueError(file object, error code, message)

fileDialogComplete(number of files selected, number of files queued)

uploadStart(file object)

uploadProgress(file object, bytes complete, total bytes)

uploadError(file object, error code, message)

uploadSuccess(file object, server data)

uploadComplete(file object)

debug(message)

SWFUpload功能對象

Settings object

Settings 描述

upload_url

file_post_name

post_params

use_query_string

requeue_on_error

file_types

file_types_description

file_size_limit

file_upload_limit

file_queue_limit