SWFUpload v2 說明文檔 非常棒的多文件上傳。SWFUpload v2 說明文檔特別提醒 TOC
SWFUploadSWFUpload最初是由Vinterwebb.se開發(fā)的一個客戶端的上傳工具. 它結合了FLASH和JavaScript的功能，以提供一種超越了傳統(tǒng)的瀏覽器中<input type="file" />標簽提供的文件上傳功能。 SWFUpload提供的主要功能:
SWFUpload背后的設計思想和其它基于Flash的上傳工具是不同的。它將瀏覽器的中UI交給開發(fā)人員來控制。開發(fā)人員能夠利用XHTML,CSS,Javascript來定制符合他們網站風格的UI上傳元素。然后使用它提供的一組簡單的JS事件來更新上傳狀態(tài)，開發(fā)人員能夠利用這些事件來及時更新頁面中的上傳進度UI。 SWFUpload v2SWFUpload v2包含了新的高級功能，改善了穩(wěn)定性，解決了FlashPlayer中的一些bug，并且提供一套有用的插件。新的功能包括：
SWFUpload v2 延續(xù)了SWFUpload的設計目標，將UI分離以交給開發(fā)人員控制和后續(xù)擴展 概述傳統(tǒng)的HTML上傳標準的HTML上傳表單為用戶提供一個文本框和按鈕來選擇文件，選中的文件是隨著form表單提交的。整個文件上傳完成之后，下一個頁面才會顯示，并且不能對選擇的文件做預設的文件檢驗，例如文件大小限制，文件類型限制。當文件上傳時，用戶獲得的可用的反饋信息很少。 傳統(tǒng)的HTML上傳模式十分簡單，線性的，幾乎所有瀏覽器都支持它。 SWFUploadSWFUpload使用一個隱藏的Flash影片來控制文件的選擇和上傳。JavaScript用來激活文件選擇對話框。 此文件選擇對話框是可以設置允許用戶選擇一個單獨的文件或者是多個文件。 選擇的的文件類型也是可以被限制的，因此用戶只能選擇指定的適當?shù)奈募?，例?.jgp;*.gif。 當選定文件以后，每個文件都會被驗證和處理。當Flash上傳文件的時候，由開發(fā)人員預定義的Javascript事件會被定時觸發(fā)以便來更新頁面中的UI，同時還提供上傳狀態(tài)和錯誤信息。 選定的文件的上傳和它所在頁面、表單是獨立的。每個文件都是單獨上傳的，這就保證了服務端腳本能夠在一個時間點更容易地處理單個文件。雖然Flash提供了上傳服務，但是頁面并不會提交或者重新載入。相比于標準的HTML Form，SWFUpload的使用方式更像是AJAX程序，頁面中的Form會和FLASH控制的文件上傳單獨處理。 入門SWFUpload并不是拖放式的上傳控件，它需要JavaScript和DOM的知識。一些可用的演示展示了它能夠完成什么事情以及它是如何完成這些常見的任務。 SWFUpload由4部分組成：
使用SWFUpload遇到的多數(shù)問題是由不正確地設置或者定義了糟糕的處理事件引起的。 初始化和設置SWFpload必須在頁面中初始化，一般可以在window.onload事件中完成此操作。它的構造函數(shù)需要一個Object類型的設置對象。 這個設置對象一般是一個直接定義的Object類型變量，直接傳遞給SWFUpload的構造函數(shù)。 初始化的SWFUpload對象的引用需要保留下來，因為當顯示文件選擇對話框和啟動文件上傳的時候需要這個實例的引用。 例如:用直接定義的Object類型變量設置初始化SWFUpload對象 var swfu; window.onload = function () { swfu = new SWFUpload({ upload_url : "http://www./upload.php", flash_url : "http://www./swfupload_f9.swf", file_size_limit : "20480" }); };
例如:用存儲在變量中的設置對象初始化SWFUpload對象 var swfu; window.onload = function () { var settings_object = { upload_url : "http://www./upload.php", flash_url : "http://www./swfupload_f9.swf", file_size_limit : "20480" }; swfu = new SWFUpload(settings_object); };
JavaScript 庫該JavaScript庫文件(swfupload.js)應該包含在需要上傳功能的頁面中。它對 Flash Player 8 和 Flash Player 9 SWFUpload 版本都是兼容、可用的。 當SWFUpload創(chuàng)建完成并能訪問它的一系列功能時，開發(fā)人員可以來控制此實例。 例如: 添加SWFUpload.js到頁面中 <script type="text/javascript" src="http://www./swfupload.js"></script>
例如: 根據(jù)需要的設置來初始化SWFUpload，同時把它的seleteFiles方法綁定到一個按鈕的Click事件上。 var swfu = new SWFUpload({ upload_url : "http://www./upload.php", flash_url : "http://www./swfupload_f9.swf" }); document.getElementById("BrowseButton").onclick = function () { swfu.selectFiles(); };
Flash 控制元素SWFUpload JavaScript庫動態(tài)加載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通信來通知瀏覽器處理更新。 事件處理開發(fā)人員必須定義一系列JavaScript函數(shù)來處理SWFUpload事件回調，當一些不同的重要事件發(fā)生的時候，這些函數(shù)會被觸發(fā)。 通過處理SWFUpload的事件，開發(fā)人員能夠提供關于上傳進度、出錯信息以及上傳完成等的信息反饋。 例如: swfupload的處理事件和初始化 // uploadStart處理事件。該函數(shù)變量在設置對象中指定給了upload_start_handler屬性。 var uploadStartEventHandler = function (file) { var continue_with_upload = true; return continue_with_upload; }; //uploadSuccess處理事件。 該函數(shù)變量在設置對象中指定給了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); }; //創(chuàng)建SWFUpload實例，設置事件回調函數(shù) var swfu = new SWFUpload({ upload_url : "http://www./upload.php", flash_url : "http://www./swfupload_f9.swf", file_size_limit : "20480", upload_start_handler : uploadStartEventHandler, upload_success_handler : uploadSuccessEventHandler });
SWFUpload JavaScript 對象構造函數(shù)SWFUpload(settings object) 返回:一個SWFUpload 實例 var swfupload_instance = new SWFUpload(settings_object);
全局變量和常量SWFUpload定義了一些全局變量和常量，這對SWFUpload的高級應用程序和處理錯誤都是很有用的，它們都是只讀的。 SWFUpload.instancesSWFUpload.instances是一個存儲了頁面中所有SWFUpload實例引用的數(shù)組。Flash播放器依靠這個數(shù)組來調用正確的處理事件。該數(shù)組是由movieName屬性來索引的關聯(lián)數(shù)組。例如：SWFUpload.instances.SWFUpload_0訪問的是第一個實例引用。 注意: SWFUpload.instances不是一個真正的JavaScript數(shù)組，實際上它是一個對象（關聯(lián)數(shù)組）。 SWFUpload.movieCountSWFUpoad.movieCount是一個全局變量，用于記錄頁面中的SWFUpload實例個數(shù)，同時確保給每一個Flash影片分配一個惟一的movieName。 SWFUpload.QUEUE_ERRORSWFUpload.QUEUE_ERROR是一個包含了Queue Error錯誤碼的JS對象，一般用它來查看fileQueueError事件的中發(fā)送的錯誤碼，以確定fileQueueError的具體類型。 SWFUpload.QUEUE_ERROR = { QUEUE_LIMIT_EXCEEDED : -100, FILE_EXCEEDS_SIZE_LIMIT : -110, ZERO_BYTE_FILE : -120, INVALID_FILETYPE : -130 };
SWFUpload.UPLOAD_ERRORSWFUpload.UPLOAD_ERROR是一個包含了Upload Error錯誤碼的JS對象，一般用它來查看uploadError事件的中發(fā)送的錯誤碼，以確定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_STATUSSWFUpload.FILE_STATUS是一個包含F(xiàn)ile Status狀態(tài)碼的JS對象。它可以用來檢測File對象中的file status屬性，以確定文件的狀態(tài)。 SWFUpload.FILE_STATUS = { QUEUED : -1, IN_PROGRESS : -2, ERROR : -3, SUCCESS : -4, CANCELLED : -5 };
默認處理事件SWFUpload庫提供了一系列默認的處理事件。當開發(fā)人員沒有自定義處理事件時，SWFUpload庫將調用這些默認的處理事件。因此當自定義事件時，不要把這些默認的處理事件覆蓋了。自定義事件是需要在settings對象中被單獨定義的。 屬性下面這個列表是相關屬性的具體描述。使用其它屬性或者對只讀屬性進行了寫的操作都會造成SWFUpload出現(xiàn)問題。 customSettings (可讀/可寫)customSettings屬性是一個空的JavaScript對象，它被用來存儲跟SWFUpload實例相關聯(lián)的數(shù)據(jù)。它的內容可以使用設置對象中的custom_settings屬性來初始化。 注意:一些插件使用customSettings對象來實現(xiàn)它們的內部控制。當重寫整個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數(shù)組中的位置。 方法下面的方法用來操作SWFUpload。其中有些方法可以跟元素（例如，按鈕）的點擊事件綁定，其它的方法供SWFUpload內部處理事件中調用。 object addSetting(setting_name, value, default_value)不贊成使用 V2.1.0源碼中注釋：addSetting和getSetting已經不再被使用了，只是考慮到兼容V2版本，才繼續(xù)保留在庫中。 object getSetting(setting_name)不贊成使用 V2.1.0源碼中注釋：addSetting和getSetting已經不再被使用了，只是考慮到兼容V2版本，才繼續(xù)保留在庫中。 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，那么默認文件上傳隊列中的第一個文件將被退出上傳。 如果取消的文件是正在上傳，那么會觸發(fā)uploadError事件。 void stopUpload()如果當前有文件上傳，那么停止上傳，并且將文件還原到上傳隊列中。 停止了正在上傳的文件，uploadError事件會被觸發(fā)。如果此時沒有正在上傳文件，那么不會發(fā)生任何操作，不會觸發(fā)任何事件。 object getStats()獲取當前狀態(tài)的統(tǒng)計對象，具體見Stats Object。 void setStats(stats_object)Stats統(tǒng)計對象是可以被修改的。如果你希望在上傳完畢之后修改上傳成功或者上傳失敗的統(tǒng)計數(shù)目時，那么可以使用該方法。 提醒：可供修改的屬性只有successful_uploads ，upload_errors，upload_cancelled，queue_errors，并且值必須是Number類型。 object getFile(file_id|index)根據(jù)file_id或者index來獲取文件隊列中的文件對象。file_id是文件對象中的id屬性，index是文件對象中的index屬性。 傳遞Number類型的參數(shù)會被認定為index，那么返回的是文件隊列（所有嘗試入隊文件，包括因沒有通過文件大小、類型檢測等而觸發(fā)fileQueueError，沒有成功加入文件上傳隊列的文件對象）數(shù)組中下標為index的文件對象。如果index不在隊列數(shù)組范圍內，那么返回null。 傳遞非Number類型的參數(shù)會被認定為file_id，那么返回的是文件上傳隊列（通過文件檢測，準備好進行上傳的文件）數(shù)組中id為file_id的文件對象。如果參數(shù)為空，或者沒有此id的文件對象，那么返回文件等待隊列中的第一個文件對象，如果第一個文件對象為空，那么返回null。 void addPostParam(name, value)給設置中的post_params對象添加值對，當文件上傳的時候，這個值對會一同在POST中發(fā)送。 如果設置的時候，post_params中以及存在該值，那么實際上會被覆蓋。 void removePostParam(name)從設置中的post_params對象中刪除name指定的屬性，當文件上傳的時候，刪除的值對不會繼續(xù)在POST中發(fā)送。 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)動態(tài)修改設置中的upload_url屬性。 void setPostParams(param_object)動態(tài)修改post_params，以前的屬性全部被覆蓋。param_object必須是一個JavaScript的基本對象，所有屬性和值都必須是字符串類型。 void setFileTypes(types, description)動態(tài)修改設置中的file_types 和 file_types_description，兩個參數(shù)都是必須的。 void setFileSizeLimit(file_size_limit)動態(tài)修改設置中的file_size_limit，此修改針對之后的文件大小過濾有效。file_size_limit參數(shù)接收一個單位，有效的單位有B、KB、MB、GB，默認單位是KB。 例如: 2147483648 B, 2097152, 2097152KB, 2048 MB, 2 GB void setFileUploadLimit(file_upload_limit)動態(tài)修改設置中的file_upload_limit，特殊值0表示無限制。 提醒：這里限制的是一個SWFUpload實例控制上傳成功的文件總數(shù)。 void setFileQueueLimit(file_queue_limit)動態(tài)修改設置中的file_queue_limit，特殊值0表示無限制。 提醒：這里限制的是文件上傳隊列中（入隊檢測通過的文件會添加到上傳隊列等待上傳）允許排隊的文件總數(shù)。 void setFilePostName(file_post_name)動態(tài)修改設置中的file_post_name，注意在Linux環(huán)境下，F(xiàn)lashPlayer是忽略此設置的。 void setUseQueryString(use_query_string)動態(tài)修改設置中的use_query_string，設置為true的時候，SWFUpload以GET形式發(fā)送數(shù)據(jù)，如果為false，那么就以POST發(fā)送數(shù)據(jù)。 void setDebugEnabled(debug_enabled)啟動/禁止 debug輸出，debug_enabled參數(shù)是一個布爾值。 事件SWFUpload在操作過程中會觸發(fā)一系列事件，開發(fā)者可以利用這些回調的處理事件來控制UI，控制操作或者報告錯誤。 所有的事件都是在SWFUpload實例的上下文中調用的，因此在這些回調的事件中使用this能夠直接訪問到該觸發(fā)該事件的實例對象。 flashReady()該事件函數(shù)是內部事件，因此不能被重寫。當SWFupload實例化，加載的FLASH完成所有初始化操作時觸發(fā)此事件。 提醒：對應設置中的自定義事件swfupload_loaded_handler swfUploadLoaded()V2.1.0版本中已經刪除了此事件 fileDialogStart()此事件在selectFile或者selectFiles調用后，文件選擇對話框顯示之前觸發(fā)。只能同時存在一個文件對話框。 提醒：對應設置中的自定義事件file_dialog_start_handler fileQueued(file object)當文件選擇對話框關閉消失時，如果選擇的文件成功加入上傳隊列，那么針對每個成功加入的文件都會觸發(fā)一次該事件（N個文件成功加入隊列，就觸發(fā)N次此事件）。 提醒：對應設置中的自定義事件file_queued_handler fileQueueError(file object, error code, message)當選擇文件對話框關閉消失時，如果選擇的文件加入到上傳隊列中失敗，那么針對每個出錯的文件都會觸發(fā)一次該事件(此事件和fileQueued事件是二選一觸發(fā)，文件添加到隊列只有兩種可能，成功和失敗)。 文件添加隊列出錯的原因可能有：超過了上傳大小限制，文件為零字節(jié)，超過文件隊列數(shù)量限制，設置之外的無效文件類型。 具體的出錯原因可由error code參數(shù)來獲取，error code的類型可以查看SWFUpload.QUEUE_ERROR中的定義。 提醒：對應設置中的自定義事件file_queue_error_handler 注意：如果選擇入隊的文件數(shù)量超出了設置中的數(shù)量限制，那么所有文件都不入隊，此事件只觸發(fā)一次。如果沒有超出數(shù)目限制，那么會對每個文件進行文件類型和大小的檢測，對于不通過的文件觸發(fā)此事件，通過的文件成功入隊。 fileDialogComplete(number of files selected, number of files queued)當選擇文件對話框關閉，并且所有選擇文件已經處理完成（加入上傳隊列成功或者失?。r，此事件被觸發(fā)，number of files selected是選擇的文件數(shù)目，number of files queued是此次選擇的文件中成功加入隊列的文件數(shù)目。 提醒：對應設置中的自定義事件file_dialog_complete_handler 注意：如果你希望文件在選擇以后自動上傳，那么在這個事件中調用this.startUpload() 是一個不錯的選擇。如果需要更嚴格的判斷，在調用上傳之前，可以對入隊文件的個數(shù)做一個判斷，如果大于0，那么可以開始上傳。 uploadStart(file object)在文件往服務端上傳之前觸發(fā)此事件，可以在這里完成上傳前的最后驗證以及其他你需要的操作，例如添加、修改、刪除post數(shù)據(jù)等。 在完成最后的操作以后，如果函數(shù)返回false，那么這個上傳不會被啟動，并且觸發(fā)uploadError事件（code為ERROR_CODE_FILE_VALIDATION_FAILED），如果返回true或者無返回，那么將正式啟動上傳。 提醒：對應設置中的自定義事件upload_start_handler uploadProgress(file object, bytes complete, total bytes)該事件由flash定時觸發(fā)，提供三個參數(shù)分別訪問上傳文件對象、已上傳的字節(jié)數(shù)，總共的字節(jié)數(shù)。因此可以在這個事件中來定時更新頁面中的UI元素，以達到及時顯示上傳進度的效果。 注意: 在Linux下，F(xiàn)lash Player只在所有文件上傳完畢以后才觸發(fā)一次該事件，官方指出這是Linux Flash Player的一個bug，目前SWFpload庫無法解決（我沒有測試過）。 提醒：對應設置中的自定義事件upload_progress_handler uploadError(file object, error code, message)無論什么時候，只要上傳被終止或者沒有成功完成，那么該事件都將被觸發(fā)。error code參數(shù)表示了當前錯誤的類型，更具體的錯誤類型可以參見SWFUpload.UPLOAD_ERROR中的定義。Message參數(shù)表示的是錯誤的描述。File參數(shù)表示的是上傳失敗的文件對象。 例如，我們請求一個服務端的一個不存在的文件處理頁面，那么error code會是-200，message會是404。停止、退出、uploadStart返回false、HTTP錯誤、IO錯誤、文件上傳數(shù)目超過限制等，都將觸發(fā)該事件，Upload error will not fire for files that are cancelled but still waiting in the queue。（對于官方的這句話我還存在疑問，文件退出以后怎么還會保留在文件上傳隊列中保留呢？） 提醒：對應設置中的自定義事件upload_error_handler 注意：此時文件上傳的周期還沒有結束，不能在這里開始下一個文件的上傳。 uploadSuccess(file object, server data)當文件上傳的處理已經完成（這里的完成只是指向目標處理程序發(fā)送了Files信息，只管發(fā)，不管是否成功接收），并且服務端返回了200的HTTP狀態(tài)時，觸發(fā)此事件。 提醒：對應設置中的自定義事件upload_success_handler 注意：
uploadComplete(file object)當上傳隊列中的一個文件完成了一個上傳周期，無論是成功(uoloadSuccess觸發(fā))還是失敗(uploadError觸發(fā))，此事件都會被觸發(fā)，這也標志著一個文件的上傳完成，可以進行下一個文件的上傳了。 如果要進行多文件自動上傳，那么在這個時候調用this.startUpload()來啟動下一個文件的上傳是不錯的選擇。 提醒：對應設置中的自定義事件upload_complete_handler 注意：當在進行多文件上傳的時候，中途用cancelUpload取消了正在上傳的文件，或者用stopUpload停止了正在上傳的文件，那么在uploadComplete中就要很小心的使用this. startUpload()，因為在上述情況下，uploadError和uploadComplete會順序執(zhí)行，因此雖然停止了當前文件的上傳，但會立即進行下一個文件的上傳，你可能會覺得這很奇怪，但事實上程序并沒有錯。如果你希望終止整個隊列的自動上傳，那么你需要做額外的程序處理了。 debug(message)如果debug setting設置為true，那么頁面底部會自動添加一個textArea， SWFUpload庫和Flash都會調用此事件來在頁面底部的輸出框中添加debug信息供調試使用。 提醒：對應設置中的自定義事件debug_handler SWFUpload功能對象Settings object它是一個Object類型的變量，為SWFUpload的實例初始化提供配置。 其中的每一個配置屬性都只能出現(xiàn)一次。 很多屬性都是可選的，如果可選屬性沒有被配置，那么會使用SWFUpload庫中默認指定的合適的值，具體可查看setting的詳細介紹。 例如:（setting可以配置的所有屬性） { upload_url : "http://www./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_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版本中可用)該參數(shù)設置了POST信息中上傳文件的name值（類似傳統(tǒng)Form中設置了<input type="file" name="uploadImg"/>的name屬性）。 注意：在Linux下面此參數(shù)設置無效，接收的name總為Filedata，因此為了保證最大的兼容性，建議此參數(shù)使用默認值。 post_params默認值：空的Object對象 post_params定義的是一個包含值對的object類型數(shù)據(jù)，每個文件上傳的時候，其中的值對都會被一同發(fā)送到服務端。 注意：
use_query_string默認值：false (僅在Flash 9版本中可用) 該屬性可選值為true和false，設置post_params是否以GET方式發(fā)送。如果為false，那么則以POST形式發(fā)送。 requeue_on_error默認值：false 該屬性可選值為true和false。如果設置為true，當文件對象發(fā)生uploadError時（除開fileQueue錯誤和FILE_CANCELLED錯誤），該文件對象會被重新插入到文件上傳隊列的前端，而不是被丟棄。如果需要，重新入隊的文件可以被再次上傳。如果要從上傳隊列中刪除該文件對象，那么必須使用cancelUpload方法。 跟上傳失敗關聯(lián)的所有事件同樣會被一一觸發(fā)，因此將上傳失敗的文件重新入隊可能會和Queue Plugin造成沖突（或者是自動上傳整個文件隊列的自定義代碼）。如果代碼中調用了startUpload方法自動進行下一個文件的上傳，同時也沒有采取任何措施讓上傳失敗的文件退出上傳隊列，那么這個重新入隊的上傳失敗的文件又會開始上傳，然后又會失敗，重新入隊，重新上傳...，進入了無止境的循環(huán)。 該設置是在v2.1.0中引入的。 file_types默認值：*.* 設置文件選擇對話框的文件類型過濾規(guī)則，該屬性接收的是以分號分隔的文件類型擴展名，例如“ *.jpg;*.gif”，則只允許用戶在文件選擇對話框中可見并可選jpg和gif類型的文件。默認接收所有類型的文件。 提醒：該設置只是針對客戶端瀏覽器的過濾，對服務端的文件處理中的文件類型過濾沒有任何限制，如果你需要做嚴格的文件過濾，那么服務端同樣需要程序檢測。 file_types_description默認值：All Files 設置文件選擇對話框中顯示給用戶的文件描述。 file_size_limit默認值：0 設置文件選擇對話框的文件大小過濾規(guī)則，該屬性可接收一個帶單位的數(shù)值，可用的單位有B,KB,MB,GB。如果忽略了單位，那么默認使用KB。特殊值0表示文件大小無限制。 提醒：該設置只對客戶端的瀏覽器有效，對服務端的文件處理沒有任何限制，如果你需要做嚴格文件過濾，那么服務端同樣需要程序處理。 file_upload_limit默認值：0 設置SWFUpload實例允許上傳的最多文件數(shù)量，同時也是設置對象中file_queue_limit屬性的上限。一旦用戶已經上傳成功或者添加文件到隊列達到上最大數(shù)量，那么就不能繼續(xù)添加文件了。特殊值0表示允許上傳的數(shù)量無限制。只有上傳成功（上傳觸發(fā)了uploadSuccess事件）的文件才會在上傳數(shù)量限制中記數(shù)。使用setStats方法可以修改成功上傳的文件數(shù)量。 注意：該值不能跨頁面使用，當頁面刷新以后該值也被重置。嚴格的文件上傳數(shù)量限制應該由服務端來檢測、管理。 file_queue_limit默認值：0 設置文件上傳隊列中等待文件的最大數(shù)量限制。當一個文件被成功上傳，出錯，或者被退出上傳時，如果文件隊列中文件數(shù)量還沒有達到上限，那么可以繼續(xù)添加新的文件入隊，以頂替該文件在文件上傳隊列中的位置。如果允許上傳的文件上限（file_upload_limit）或者剩余的允許文件上傳數(shù)量小于文件隊列上限（file_queue_limit），那么該值將采用這個更小的值。 flash_url默認值：空字符串 設置絕對或者相對于此上傳頁面的完整URL，一旦SWFupload實例化以后，此設置不能再被修改。 提醒：測試發(fā)現(xiàn)使用setUploadURL方法是可以修改此設置的。 flash_width固定值：1px (v2.1.0已刪除) 設置插入flash影片的HTML元素容器的寬度。如果此設置小于1像素，一些瀏覽器會出現(xiàn)功能異常。 因此該值在v2.1.0中刪除了自定義設置，默認設置為1像素了。 flash_height固定值：1px (v2.1.0已刪除) 設置插入flash影片的HTML元素容器的高度。如果此設置小于1像素，一些瀏覽器會出現(xiàn)功能異常。 因此該值在v2.1.0中刪除了自定義設置，默認設置為1像素了。 flash_color默認值：#FFFFFF 設置HTML頁面中的flash背景色，默認為#FFFFFF 提醒：對一個1*1像素的flash元素設置背景顏色，在視覺上的改變基本無效。 debug默認值：false 該值是布爾類型，設置debug事件是否被觸發(fā)。 注意：SWFUpload代碼中是將此變量和字符串true做的恒等判斷，因此它只認定true為DEBUG模式開啟，如果設置為1，雖然JS認定是開啟模式，并且在初始化完畢后會有生成Debug Console，但后續(xù)操作中FLASH不會輸出調試信息。（因為我習慣用1和0代表布爾變量，因此一度疑惑為何Flash的debug信息無法輸出。） custom_settings默認值：空的Object對象 該屬性接收一個Object類型數(shù)據(jù)，可用于安全地存儲與SWFUpload實例關聯(lián)的自定義信息，例如屬性和方法，而不用擔心跟SWFUpload內部的方法和屬性沖突以及版本升級的兼容。 設置完畢以后，可以通過實例的customSettings屬性來訪問。 var swfu = new SWFUpload({ custom_settings : { "My Setting" : "This is my setting", myothersetting : "This is my other setting", integer_setting : 100, a_dom_setting : document.getElementById("some_element_id") } }); var my_setting = swfu.customSettings["My Setting"]); swfu.customSettings["My Setting"] = "This is my new setting"; swfu.customSetting.myothersetting = "another new value"; swfu.customSetting.integer_setting += 25; swfu.customSetting["a_dom_setting"].style.visibility = "hidden";
Event Handlers默認值：null 剩下的設置定義的是一系列事件處理的回調函數(shù)，在SWFUpload的操作過程中相應的事件會被觸發(fā)。如果你需要在這些回調中進行自定義操作，那么你應該在設置中定義對應的JavaScript函數(shù)。 File ObjectFile Object包含了一組可用的文件屬性，很多處理事件都會傳遞一個File Object參數(shù)來訪問該文件的相關屬性。 { id : string, // SWFUpload控制的文件的id,通過指定該id可啟動此文件的上傳、退出上傳等 index : number, // 文件在選定文件隊列（包括出錯、退出、排隊的文件）中的索引，getFile可使用此索引 name : string, // 文件名，不包括文件的路徑。 size : number, // 文件字節(jié)數(shù) type : string, // 客戶端操作系統(tǒng)設置的文件類型 creationdate : Date, // 文件的創(chuàng)建時間 modificationdate : Date, // 文件的最后修改時間 filestatus : number // 文件的當前狀態(tài)，對應的狀態(tài)代碼可查看SWFUpload.FILE_STATUS }
Stats Object該對象提供了上傳隊列的狀態(tài)信息，訪問實例的getStats方法可獲取此對象。 該對象包括下面屬性： { in_progress : number // 值為1或0，1表示當前有文件正在上傳，0表示當前沒有文件正在上傳 files_queued : number // 當前上傳隊列中存在的文件數(shù)量 successful_uploads : number // 已經上傳成功（uploadSuccess觸發(fā)）的文件數(shù)量 upload_errors : number // 已經上傳失敗的文件數(shù)量 (不包括退出上傳的文件) upload_cancelled : number // 退出上傳的文件數(shù)量 queue_errors : number // 入隊失?。╢ileQueueError觸發(fā)）的文件數(shù)量 }
所有這些屬性的值都可以使用setStats方法來修改，除了in_progress 和 files_queued。 SWFUpload 插件With SWFUpload v2.0 several plugins have been introduced. They are provided to help with common tasks associated with implementing SWFUpload. Currently most of the documentation for using the plugins is contained in the plugin JavaScript file. SWFObjectThe SWFObject plugin uses the SWFObject library to handle the embedding of the SWFUpload Flash Component into the page. This plugin also provides support for Document Ready loading and Flash Version Detection. Usage details are documented in the plugin file itself. Using this plugin can eliminate the flicker seen in the Graceful Degradation plugin and provides events for loading failure. Graceful DegradationThis plugin has been superseded by the SWFObject plugin. This plugin provides additional settings and logic for automatically hiding and showing page elements based on whether SWFUpload loads. SWFUpload v1.0.2 CompatibilityCreates compatibility with v1.0.2. Using this plugin you should be able to drop SWFUpload v2.0 in to a v1.0.2 page. This plugin is not supported and is only intended for users of SWFUpload v1.0.2 who wish to upgrade to v2 without recoding their pages. CookiesIn response to the Flash Cookie Bug the Cookies Plugin automatically retrieves your browser's cookies and sends them with the uploads. The are sent as POST or GET variables to the upload url. Queue HandlingThis plugin provides Queue Handling features such as entire queue uploading, entire queue cancelling and automatic starting of uploads after being queued. Known IssuesThe Flash Player and many Browsers have bugs that have a direct impact on the performance of SWFUpload. While we have worked hard to get around many issues there are some things that cannot be fix. Cancelling in LinuxFlash 8 and older Flash 9 Players for Linux cause the browser to crash if an upload is cancelled. Newer Flash 9 Players behave better. Upload Progress in LinuxThe Flash Player in Linux sends a single uploadProgress event after the file has finished uploading. Upload Progress in OS XThere have been some reports that uploadProgress events are not fired in MAC Flash Players. The specifics haven't been pinned down but be aware of the possible issue. ProxiesThe Flash Player may not properly use proxies. It does not handle authenticating proxies well (if at all) and will some-times crash. Some anti-virus software uses a proxy to scan uploads and cause SWFUpload to believe the entire file has been uploaded. SWFUpload will fire uploadProgress events very quickly until it reaches 100% and will then seem to pause until the proxy completes uploading the file to the server. Apache mod_securityApache's mod_security validates POST to the server. Flash Player has implemented an edge case (there is argument as to whether it is invalid or note) POST for file uploads and so servers implementing mod_security will reject the upload. mod_security can be disabled using your .htaccess file SSLThere have been some reports that the Flash Player cannot upload through SSL. The issue has not been pinned down but uploading over SSL may be unreliable. There especially seems to be an issue with using self-signed certificates. AuthenticationHTTP Authentication is not well supported by the Flash Player. Later versions of Flash Player behave better. Old version of Flash Player would crash the browser. Prematurely terminated connectionsPrematurely ending the response (such as a Response.end() in ASP.Net) can sometimes cause successful uploads to be reported as failed. Filedata in LinuxChanging the Filedata value (file_post_name setting) is ignored in Linux Flash Player. uploadSuccess & Server DataThe uploadSuccess will not fire if no data is returned from the server. This is especially problematic on the Mac version of the Flash Player. Cookie issueOn Windows the Non-IE Flash Player plugin (FireFox, Opera, Safari, etc) sends the IE cookies regardless of the browser used. This breaks authentication and sessions for many server-side scripting technologies. Developers should manually pass Session and Authentication cookie information and manually restore Sessions on the Server Side if they wish to use Sessions The SWFUpload package contains work-around sample code for PHP and ASP.Net ExternalInterface bugsFlash Player does not properly escape data when communication with the browser/JavaScript. SWFUpload goes to great lengths to work-around this issue. If this bug is fixed in future Flash Players/Browsers then SWFUpload will send extra escaped data. Server Data length bugsVery long server data is corrupted on Mac and Linux Flash Players. Server data will be truncated, garbled, and/or repeated. We recommend keeping data returned from the server short and concise. Avant BrowserFor some users the Avant Browser does not work with SWFUpload after the Flash Control has been cached. This has been reproduced by the SWFUpload developers but the Avant Browser developers did not experience any problems. When the page is reloaded SWFUpload loads and fires the swfupload_loaded event. However, none of the ExternalInterface callback functions are defined on the movie element. SWFUpload v2.0.2 has added checks which prevent swfupload_loaded from firing if the callback functions are not detected. File Dialog & Page ChangingLeaving or reloading the current page while the File Browser Dialog window is open will cause the browser to crash (all browsers, all OSs). Most commonly this is caused by failing to cancel a click event on an <a> tag where the onclick event calls the selectFile or selectFiles function. Long Running Upload ScriptsAfter Flash has uploaded the file to the webserver the upload script is executed. This script handles the file whether that means saving it, creating a thumbnail, scanning for viruses, etc. If the upload script does not return any data within 30 seconds Flash will disconnect and return an IO Error. You can prevent this by returning characters or data while the script runs (if possible). For PHP, the script continues to run and complete successfully even though Flash has terminated the connection. Any data returned by the script after Flash has disconnected is lost. Other Mac Issues
|
|
|
