SWFUpload 2.5.0版官方說明文檔中文翻譯版

本文轉載自查看原文 2012-07-13 12:29 96224 JavaScript/ swfupload

SWFUpload v2.5.0 Documentation

Table of Contents 內容列表詳情請點擊翻譯：yukon12345 2010.6.10

SWFUpload
SWFUpload 版本 2
概覽（Overview）
入門（ Getting Started）
js對象（SWFUpload JavaScript Object）
相關插件 SWFUpload Plug-ins
【新增內容】已知問題 Known Issues

SWFUpload

SWFUpload 最初是Vinterwebb.se 開發的客戶端文件上傳工具。它聯合javascript和flash，在瀏覽器中提供一個優於傳統上傳標簽 <input type="file" /> 的功能（和良好的用戶體驗）。

SWFUpload 的主要特性:

文件瀏覽對話框中可以選擇多個文件
AJAX風格的上傳，不用重刷新
上傳過程中的各種事件.
可以在客戶端調節圖片大小
它使用的類命名空間兼容各種js庫(i.e., jQuery, Prototype, 等.).
支持 Flash 9 and Flash 10 (2.2.0版本后取消對flash 8的支持)

SWFUpload 的設計理念與其他基於flash的上傳工具不同。SWFUpload 給開發者盡可能多的UI控制能力. 開發者可以使用 XHTML, CSS, JavaScript 來使它更符合自己網站的樣式風格. 它提供一組簡單的js事件更新上傳狀態，開發者可以根據這些事件來在網頁中顯示文件上傳進度

不過不幸的是 Flash Player 10 迫使我們不得不用一個按鈕（點擊后）才能觸發文件選擇對話框，但SWFUpload允許開發者用js來修改這個按鈕的文字等外觀。

SWFUpload v2

SWFUpload v2 包含了許多新的特性，增強的穩定性，解決了Flash Player 中的一些bug，提供了一些有用的插件（Plug-ins）. 新特性包括:

可利用Flash Player 10 安全特性.
可以隨上傳來POST額外的數據
針對每一個文件上傳發送POST數據
完善的各種事件組.
所有設置，參數，都可以靈活配置.
可獲取服務器回傳的數據.
可暫停正在上傳的文件，而不是取消.
任意修改上傳的次序.
可提供單一或多文件的選擇對話框.
可限制上傳文件隊列長度，文件大小，上傳文件個數
可更好地處理0字節文件.
每個文件都有上傳確認事件.

Overview

HTML Upload

標准的HTML上傳框只提供一個按鈕和一個文本框讓用戶選擇單個文件。然后通過表單提交。整個文件必須等到它上傳完畢后才能確認並檢查文件大小，文件擴展名，而且上傳的過程中，回傳反饋很少。這就造成了一些使用上的不便利。

但傳統的HTML上傳十分簡單，單一步驟，所有瀏覽器都支持它。

SWFUpload

SWFUpload 使用Flash 影片（flash movie）來選擇和上傳文件。影片里有一個可定制的按鈕來激活文件選擇對話框。文件選擇對話框允許用戶選擇單一的文件或者多個文件。選擇的的文件類型也是可以被限制的，開發人員可以限定用戶只能選擇指定的適當的文件，例如*.jgp;*.gif。

一旦選擇並點擊確定，每個文件都會被驗證，並放入隊列。當Flash上傳文件的時候，由開發人員預定義的Javascript事件會被觸發以便來更新頁面中的UI顯示，並且還能實時提供上傳狀態和錯誤信息。

文件的上傳是獨立於頁面和表單的。每個文件單獨的上傳到處理頁面，這就使服務器可以簡單輕松地處理文件。flash提供的上傳服務使得整個頁面不必提交或者刷新。這有點像AJAX程序。頁面中的Form表單數據會和FLASH控制的文件上傳單獨處理。

入門 Getting Started

SWFUpload 不是拖放式的上傳控件。因此需要一些dom和js的知識。幾個demo將會展示swfUpload的能力以及如何使用它們完成任務。

SWFUpload 包含4部分:

初始化和設置 (JavaScript)
JavaScript 庫: SWFUpload.js
Flash控件: swfupload.swf 和 swfupload_fp9.swf
事件處理機制 (JavaScript)

許多使用 SWFUpload 的問題都出在設置上。錯誤的事件處理， Flash/瀏覽器的Bug,或者服務器配置。

初始化和設置 Initialization and Settings

SWFUpload 必須在頁面上初始化.它通常在js的window.onload事件里完成. SWFUpload 的構造函數需要獲取一個Object類型的對象（js）. 這個對象的數據直接的傳遞給構造函數.

初始化的SWFUpload對象的引用（reference）應該保存好，（yukon:即用變量存儲起來.如例子中的swfu）因為在啟動文件上傳以及控制其他特性的時候也需要這個引用。

例子:初始化SWFUpload時直接傳入一個匿名對象來配置參數

var swfu; window.onload = function () { swfu = new SWFUpload({ upload_url : "http://www.swfupload.org/upload.php", //處理上傳文件的地址 flash_url : "http://www.swfupload.org/swfupload.swf", //核心功能swf的地址 flash9_url : "http://www.swfupload.org/swfupload_fp9.swf", file_size_limit : "20 MB" //文件大小限制 }); };

例子: 也可以在初始化SWFUpload時使用一個對象變量（settings_object）傳入配置參數

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

js庫 JavaScript library

如果想使用swfupload， js庫文件(swfupload.js) 必須被引入到使用的頁面中.

一旦 SWFUpload 對象被創建，就可以訪問許多功能函數。開發者可以以此來控制SWFUpload。

例: 如何引入swfupload.js庫

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

例: 按需初始化 SWFUpload.

var swfu = new SWFUpload({ upload_url : "http://www.swfupload.org/upload.php", flash_url : "http://www.swfupload.org/swfupload.swf", flash9_url : "http://www.swfupload.org/swfupload_fp9.swf", button_placeholder_id : "spanSWFUploadButton" //yukon：這里有個新參數，將會使用js在id為“spanSWFUploadButton”的標簽容器如span，div中創建一個“選擇”按鈕 });

【新增內容】flash控件 Flash Control

SWFUpload js庫能動態的加載 Flash 控件 (swfupload.swf 或 swfupload_fp9.swf).

Flash控件的文件地址在初始化的時候就必須在SWFUpload設置對象中定義。

Flash控件實際上是個Flash小影片，它可以控制文件的選擇，驗證和上傳。

它在頁面中展現給用戶的是一個UI可自定制的按鈕，並且能檢測Flash Player的版本（9，10）自動加載適合用戶播放器版本的flash控件

使用 flash_url 和 flash9_url 可以設置swfupload.swf 或者 swfupload_fp9.swf 的路徑。（yukon：前面幾個例子已經有寫了）

事件處理 The Event Handlers

開發者必須創建一組js函數來處理SWFUpload的事件. 當各種重要的事件發生的時候，這些函數會被觸發執行。

通過處理SWFUpload的事件，開發人員能夠提供關於上傳進度、出錯信息以及上傳完成等的信息反饋。注意：開發人員不要重寫了存儲在SWFUpload.prototype的函數。

例: SWFUpload事件處理和初始化.

// 上傳開始（uploadStart）事件處理函數. 設置對象的“upload_start_handler”屬性的值應是此函數的名字 var myCustomUploadStartEventHandler = function (file) { var continue_with_upload; if (file.name === "the sky is blue") { continue_with_upload = true; } else { continue_with_upload = false; } return continue_with_upload; }; // 上傳成功（ uploadSuccess ）事件處理函數. 設置對象的“upload_success_handler”屬性的值應是此函數的名字 var myCustomUploadSuccessEventHandler = function (file, server_data, receivedResponse) { alert("The file " + file.name + " has been delivered to the server. The server responded with " + server_data); }; // Create the SWFUpload Object var swfu = new SWFUpload({ upload_url : "http://www.swfupload.org/upload.php", flash_url : "http://www.swfupload.org/swfupload.swf", flash9_url : "http://www.swfupload.org/swfupload_fp9.swf", file_size_limit : "200 MB", upload_start_handler : myCustomUploadStartEventHandler, upload_success_handler : myCustomUploadSuccessEventHandler

swfupload js 對象 SWFUpload JavaScript Object

構造函數 Constructor

SWFUpload(settings object) //SWFUpload(設置對象）

返回: 一個SWFUpload 實例

var swfupload_instance = new SWFUpload(settings_object);

全局變量和常量 Globals and Constants

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

【新增內容】SWFUpload.instances

SWFUpload.instances 是存貯着一個頁面中所有SWFUpload實例引用的數組對象。Flash Player依靠這個對象數組來調用正確的事件處理函數。SWFUpload.instances對象數組的索引（SWFUpload.instances[index]）是屬性movieName。

SWFUpload.movieCount

SWFUpload.movieCount 是一個全局變量，記錄頁面中已創建了多少個SWFUpload對象實例，並用來確保每個flash影片均被賦予一個唯一的movieName.

【新增內容】SWFUpload.QUEUE_ERROR

SWFUpload.QUEUE_ERROR 是一個簡單的js對象，包含了隊列錯誤碼（Queue Error code）的常量。用來決定當文件隊列錯誤（fileQueueError）發生時，將發送什么錯誤碼。

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

QUEUE_LIMIT_EXCEEDED - 指出用戶入隊過多，超過隊列最大長度。不過一旦在隊列中的文件被上傳或者刪除，用戶仍然可以添加文件到文件上傳等待隊列中。
FILE_EXCEEDS_SIZE_LIMIT -指出超過了所限制的文件大小（file_size_limit）.
ZERO_BYTE_FILE - 指出選擇的文件時0字節的。Flash Player不能處理空文件。上傳Windows快捷方式圖標也會觸發這個錯誤。
INVALID_FILETYPE - 指出選擇的文件擴展名與允許不符。用戶手工輸入擴展名不符的文件名，而不是用鼠標點擊選擇文件的時候就有可能觸發這個錯誤。

【新增內容】SWFUpload.UPLOAD_ERROR

SWFUpload.UPLOAD_ERROR 也是一個簡單的js數組對象，它包含了上傳錯誤碼常量（Upload Error code constants）.用來決定當上傳錯誤（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 };

HTTP_ERROR - 嘗試上傳給服務器，但服務器沒有返回200狀態碼（200表示無異常）
MISSING_UPLOAD_URL - 沒有設置上傳地址（upload_url）.
IO_ERROR - 當讀取和發送文件時出現了一些錯誤。通常發生在服務器非預期地關閉了終端連接的時候。
SECURITY_ERROR - 安全錯誤，上傳違反了安全約束。比較少見。
UPLOAD_LIMIT_EXCEEDED - 用戶嘗試上傳比預設數多的文件
UPLOAD_FAILED - 嘗試初始化上傳時出現了錯誤。比較少見。
SPECIFIED_FILE_ID_NOT_FOUND - 一個文件開始上傳，但沒有找到這個文件。（yukon：文件選擇完並添加到隊列后，用戶又在磁盤上改了文件名或者刪除了文件等）
FILE_VALIDATION_FAILED - 當上傳開始時傳回了某錯誤
FILE_CANCELLED - 取消了上傳（調用了cancelUpload函數）
UPLOAD_STOPPED - 暫停了上傳（調用了stopUpload函數）
RESIZE_ERROR - 當調整圖像大小時出現了某錯誤

【新增內容】SWFUpload.FILE_STATUS

SWFUpload.FILE_STATUS 是一個js數組對象，包含了文件狀態碼常量（ File Status code constants）. 用來檢測File對象的屬性file status

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

QUEUED - 指示此文件正在等待上傳隊列中
IN_PROGRESS - 指示此文件現在正在上傳中
ERROR - 指示此文件引發了一個隊列或上傳錯誤
COMPLETE - 指示此文件已成功傳輸給服務器
CANCELLED - 指示此文件被取消上傳（調用了cancelUpload函數）.

【新增】SWFUpload.UPLOAD_TYPE[作用：確定上傳類型]

SWFUpload.UPLOAD_TYPE 是一個js數組對象，包含了上傳類型常量（Upload Type constants）. 用於檢測File對象的上傳類型屬性（ upload type property）

NORMAL - 普通的SWFUpload 上傳
RESIZED - 被調整大小的圖片上傳，數據以HTTP的post方式發送。

【新增內容】SWFUpload.BUTTON_ACTION[作用：決定點擊按鈕后執行的動作]

SWFUpload.BUTTON_ACTION 是一個js數組對象，包含了按鈕動作碼常量（button action code constants）. 用於按鈕動作（button_action）的值設置，從而可設置flash影片中的那個交互式按鈕對各種鼠標動作的的相關響應.

SWFUpload.BUTTON_ACTION = { SELECT_FILE : -100, SELECT_FILES : -110, START_UPLOAD : -120 }

SELECT_FILE - 點擊按鈕時，打開單一文件選擇對話框。（js設定的）鼠標點擊事件不會被觸發
SELECT_FILES - 點擊按鈕時，打開多文件選擇對話框。（js設定的）鼠標點擊事件不會被觸發
START_UPLOAD - 點擊按鈕時，在上傳隊列的第一個文件將被上傳。（js設定的）鼠標點擊事件不會被觸發
NONE - 這種情況下，（js設定的）鼠標點擊事件會被觸發
JAVASCRIPT - 和NONE相同。這個值已被棄用

【新增內容】SWFUpload.CURSOR[作用：改變鼠標樣式]

SWFUpload.CURSOR 是一個js數組對象，包含了按鈕光標常量。用於按鈕光標（button_cursor）的值的設置，從而改變鼠標指向按鈕時，鼠標的樣式。

SWFUpload.CURSOR = { ARROW : -1, HAND : -2 }

ARROW - 光標呈現成箭頭指針
HAND - 光標呈現成手型

【新增內容】SWFUpload.WINDOW_MODE[作用：影片的顯示模式]

SWFUpload.WINDOW_MODE 是一個js數組對象，包含了按鈕影片窗口模式參數常量（button movie wmode parameter constants）. 用於告訴瀏覽器如何呈現flash影片。

有些 WINDOW_MODE/WMODE 設置會導致一些瀏覽器問題具體請看 Known Issues.

SWFUpload.WINDOW_MODE = { WINDOW : "window", TRANSPARENT : "transparent", OPAQUE : "opaque" };

WINDOW 是默認模式. flash影片繪制在頁面的最上層.
OPAQUE 允許頁面其他元素遮蓋這個按鈕影片。
TRANSPARENT 透明。按鈕的背景呈透明狀，允許html元素在它下面顯示

【新增】SWFUpload.RESIZE_ENCODING[作用：指出圖片編碼格式]

SWFUpload.RESIZE_ENCODING 是一個js數組對象，包含了大小調整類型常量（ resize encoding type constants）.用以指出被大小調整的圖片的編碼格式

JPEG - JPEG編碼格式
PNG - PNG 編碼格式

【新增】SWFUpload.onload [作用：定義頁面加載完畢后的操作函數]

onload 是一個可以通過swfobject的addDOMLoadEvent方法執行的函數. 你通過這個方法，在頁面加載完畢之后可以執行你的腳本程序。不過你應該確定你沒有使用其他類似的方法 (比如 jQuery框架的 “Ready” 或者 Prototype庫中的 dom:loaded).

SWFUpload.onload = function () { new SWFUpload(settingsObject); }

上面一個例子將在最早的瀏覽器加載事件中初始化SWFUpload。大多DOM准備完畢事件（DOMReady event）的執行時緊隨window.onload事件之后。

屬性 Properties

請遵循下面的屬性列表描述來使用這些屬性。如果把錯誤的使用一個只讀或只寫屬性屬性，將會導致SWFUpload錯誤.

【新增內容】customSettings (可讀寫)[作用：開發人員自定義設置]

“自定義設置”屬性（ customSettings）是一個js空對象。用以存儲與一個SWFUpload實例有關的數據。它的內容可以使用設置對象中的custom_settings屬性來初始化。

Example:

// 初始化 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"; // 添加一個新的自定義設置 // 用一個全新的對象來重寫自定義設置 swfu.customSettings = { custom_setting_A : "custom_setting_value_A", custom_setting_B : "custom_setting_value_B" };

存儲在自定義設置對象（customSettings object）的值可以輕松地被事件處理函數訪問：（yukon：這個屬性是利用js的動態特性，給開發者高度的開發自由）

function uploadSuccess(file, serverData, receivedResponse) { if (this.customSettings.custom_setting_A === true) { alert("Checked the custom setting!"); } }

movieName （只讀）[作用：存儲一個swfload實例的唯一標示]

包含了某SWFUpload實例的唯一標示名. 這個值可傳遞給Flash，以幫助as-js之間的交互。用於索引存儲在SWFUpload.instances數組的實例. 你不應該也不能改變它。

方法 Methods

下面的方法用於操作SWFUpload. 有些方法可以與DOM元素的單擊事件綁定，其它的方法供SWFUpload內部處理事件中調用。

object addSetting(setting_name, value, default_value)

不贊成使用 The addSetting function sets a setting value. If the value is undefined then the default_value is used. The function is used by SWFUpload

addSetting returns the value that was stored in the setting.

object getSetting(setting_name)

不贊成使用 The getSetting function retrieves the value of a setting. If the setting is not found an empty string is returned.

object retrieveSetting(setting_value, default_value)

在 v2.1.0 中移除 The retrieveSetting function is similar to the addSetting function except it does not modify the internal settings object. retrieveSetting returns the setting_value unless it is undefined in which case it returns the default_value

This is a utility function.

bool destroy() [作用：銷毀一個SWFUpload實例]

自 v2.1.0 添加

移除一個SWF的DOM元素，並且銷毀SWFUpload的內部引用. 用以徹底刪除頁面中的一個SWFUpload實例. 防止在ie中的內存泄露問題

如果成功移除，返回true，如果出現任何導致SWFUpload實例的狀態出現錯誤的問題，將返回false（Returns false if any error occurs leaving the SWFUpload instance in an inconsistent state）.

void displayDebugInfo()[作用：輸出調試信息]

在debug事件中displayDebugInfo（）輸出SWFUpload 設置. 如果在初始化時候debug setting被設置為true，這個函數會被自動的調用。

void selectFile()

不推薦. 不兼容 Flash Player 10.

selectFile causes the Flash Control to display a File Selection Dialog window. A single file may be selected from the Dialog window.

Calling selectFile begins the File Event Chain.

void selectFiles()

不推薦. 不兼容Flash Player 10.

selectFiles causes the Flash Control to display a File Selection Dialog window. A multiple files may be selected from the Dialog window.

Calling selectFiles begins the File Event Chain.

void startUpload(file_id)【作用：開始上傳文件】

startUpload接收file_id來上傳文件。如果不傳給它file_id值，那么將默認上傳待上傳隊列的第一個文件

調用startUpload會觸發上傳事件鏈（the Upload Event Chain）.

【新增】void startResizedUpload(file_id, width, height, encoding, quality, allowEnlarging)【作用：附帶調整圖片大小功能的上傳】

startResizedUpload 接收file_id參數來上傳文件. SWFUpload嘗試調整文件長寬等設置（如果是flash支持的圖片格式） .如果圖片格式不被支持，會引發一個上傳錯誤（uploadError）.

width和height參數用來設定圖片最大寬和高。但調整過程中會保持圖片寬高比。

encoding的值必須是是存在SWFUpload.RESIZE_ENCODING中的常量.

quality 只能用於調節JPEG格式圖像的品質。接收范圍是0-100。如果在這個范圍外，會強制成0或100.

allowEnlarging參數定義了SWFUpload是否允許將原圖像擴大。（默認為true）如果原圖像的長寬小於前面所說的width和height。如果設置其值為false的話，圖像仍然會被編碼，但不會將它擴大。

調用startResizedUpload方法會引發一個普通的上傳事件鏈鎖 . 但是Flash Player不會定時地提供 uploadProgress 事件. SWFUpload只會發送模擬 0% 和 100% 的上傳過程事件（uploadProgress events）.

被調節大小的圖片以POST方式傳遞數據，(而不是像FILE那樣) 因為Flash Player 10引入了安全特性 .附帶調整圖片大小功能的上傳的php處理頁面和普通的上傳php處理頁面有所不同：

$resizedImageData = $_POST["Filedata"]; // 服務器端以$_POST方式接收數據而不是 $_FILE $fileHandle = fopen("image.jpg", "w"); //以file系列操作函數來存儲圖片 fwrite($fileHandle, $resizedImageData); fclose($fileHandle);

void cancelUpload(file_id, trigger_error_event)【作用：移除一個上傳】

cancelUpload接收file_id 參數來移除一個文件的上傳.這個文件會被移除出待上傳隊列 .

如果不給它file_id，默認上傳隊列中的第一個文件將會被取消.

可選參數trigger_error_event如果被設置為false，uploadError事件將不會被觸發.

void stopUpload()【作用：停止上傳文件】

stopUpload停止當前正在上傳的文件，並且把它還原到待上傳隊列中。（yukon：和移除不同，就是取消這個文件的上傳，但不會移除出上傳隊列）

調用stopUpload時，如果有正在上傳的文件，uploadError事件會被觸發；如果此時沒有正在上傳文件，那么不會發生任何操作，也不會觸發任何事件。

【新增】bool requeueUpload(file_id or index)【作用：重新入隊】

requeueUpload將之前曾經入隊的文件重新加入等待上傳隊列

如果文件沒有找到，或者正在被上傳，會返回false

注意：被重新入隊的文件不會被再一次檢查文件大小，隊列大小，總上傳個數或其他限制，只會把文件添加到隊列中，如果這個文件引用仍然存在

object getStats()【作用：返回當前狀態對象】

返回狀態對象（stats object）.

void setStats(stats_object)【作用：設置或修改狀態對象】

設置或修改狀態對象（ Stats Object) . 如果你在上傳完畢后改變上傳成功數，上傳失敗數，你可以使用此方法

object getFile(file_id|index)【作用：在隊列中獲取特定文件對象】

getFile通過接收file id (某個文件對象的id) 或者 file index (某個文件對象的index屬性)，返回在隊列中的文件對象.

當給getFile傳遞一個file_id,只有在隊列中的文件才可能被獲取，如果找不到文件，將返回null

當給getFile傳遞一個index，所有嘗試入隊的（包括哪些入隊時產生了錯誤的文件）將可能被獲取。如果index索引超出范圍，會返回null

【新增】object getQueueFile(file_id|index)【作用：返回等待上傳隊列中特定的文件對象】

getQueueFile 用來從等待上傳隊列中返回單個文件對象。具體是通過接收file id (某個文件對象的id) 或者 file index (某個文件對象的index屬性)，返回在隊列中的文件對象.index 索引從0開始計算.

當給 getQueueFile傳遞一個file_id,只有在等待上傳隊列中的文件才可能被獲取，如果找不到文件，將返回null

當給 getQueueFile傳遞一個index，只有在等待上傳隊列中的文件才可以被獲取例如: getQueueFile(0) 返回一個在等待上傳隊列首部的文件對象. 如果調用了startUpload函數，它將在當前上傳文件上傳完畢后被上傳。

（yukon：上面2個方法的區別可能是：getFile是獲取文件隊列中的文件。包括已上傳的，錯誤的，等待上傳的隊列。而getQueueFile只獲取等待上傳隊列中的文件）

void addPostParam(name, value)【作用：添加一個鍵/值對】

addPostParam 添加一個鍵/值對，在每個的文件被上傳時以POST方式捎帶發送

它對應着post_params設置中的相同鍵值對。如果post_params中已經存在該值，那么實際上會被覆蓋。

void removePostParam(name)【作用：移除一個鍵/值對】

removePostParam 移除一個鍵/值對，這個鍵值對之前將在每個的文件被上傳時以POST方式捎帶發送

它對應着post_params設置中的相同鍵值對。如果post_params中已經存在該值，那么實際上會被移除。

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參數是一個布爾值。

void setButtonImageURL(url)

動態修改按鈕的圖片。url參數是相對於該swf文件或者是絕對地址的圖片(例如：以 /開始的相對路徑或者是絕對路徑：http://www.swfupload.org/buttonImage.png)。所有FLASH支持的圖片類型都可以使用（gif,jpg,png）。

該按鈕圖片需要經過一定規則（CSS Sprite）的處理。按鈕圖片中需要包括按鈕的4個狀態，從上到下依次是normal, hover, down/click, disabled.（可以參照官方demo中的圖片）

void setButtonDimensions(width, height)

動態修改SWF影片的尺寸以適應Button的圖片大小。值必須是純數值不能包括長度單位.高必須是整個圖片按鈕高的1/4，以此來保證顯示的正確

void setButtonText(text)

動態設置Flash Button中顯示的文字，支持HTML。HTML文本的樣式可以通過CSS選擇器並配合setButtonTextStyle方法來設置。如果文字過大，將會被隱藏超過的部分關於Flash文本對HTML的支持詳細可見 Adobe's Flash documentation。

void setButtonTextStyle(css_style_text)

配合setButtonText方法，可以通過CSS樣式來動態設置Flash Button中的文字樣式。關於Flash文本對CSS的支持詳細可見Adobe's Flash documentation

void setButtonTextPadding(left, top)

設置flash按鈕文本的左邊和右邊的padding。值可以為負數

void setButtonDisabled(isDisabled)

當設置為 'true'是會禁用flash按鈕，任何關於按鈕的動作與操作都會被忽略。

void setButtonAction(buttonAction)

定義鼠標被點擊后執行的動作。BUTTON_ACTION常量枚舉中存儲着這個方法可用的值

void setButtonCursor(buttonCursor)

設置鼠標指針指向按鈕時的樣式。CURSOR常量枚舉中存儲着這個方法可用的值

【新增內容】事件 Events

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

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

所有事件應該在實例初始化時setting參數中預設完成。

【新：】

上傳一個文件時，事件按照下面的順序被調用(上傳事件鏈):

附加調整圖片大小功能的上傳開始 uploadResizeStart
普通上傳開始 uploadStart
正在上傳中 uploadProgress (在上傳文件的過程中重復的被調用着)
上傳錯誤 uploadError (當出現某些錯誤時被調用, 上傳文件將被取消或停止)
上傳成功 uploadSuccess (成功的上傳了文件，服務器接受到了可用數據)
完成了上傳 uploadComplete (上傳完成，SWFUpload 准備開始上傳下一個)

flashReady()

該事件函數是內部事件，因此不能被重寫。加載的FLASH控件完成所有初始化操作時，將觸發此事件來通知SWFUpload它可以接受各種命令了。

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

【新增】 swfUploadPreload()

swfUploadPreload 事件是 SWFUpload 已確認各項可用特性之后，Flash Movie加載完畢之前的這段時間內觸發的事件.此事件的處理函數如果返回false，將停止加載swfupload。通常用在處理瀏覽器不支持某重要特性參數的情況。

在設置對象的 swfupload_preload_handler 屬性中可設置此事件處理函數

【新】swfUploadLoadFailed()

當頁面不能正常加載flash影片的時候。通常是因為沒有安裝Flash Player或者它的版本低於 9.0.28

在設置對象的 swfupload_load_failed_handler 屬性中可設置此事件處理函數

【新】swfUploadLoaded()

swfUploadLoaded 事件在flash加載並准備完畢后被觸發. 它是可設定的。 swfUploadLoaded 事件將會通知你flash加載完畢，能安全的執行各項方法了。

在設置對象的 swfupload_loaded_handler 屬性中可設置此事件處理函數

【新】mouseClick()

mouseClick事件在按鈕被單擊，（同時button_action setting的值為SWFUpload.BUTTON_ACTION.NONE，或者是flash按鈕被設置為disable時）才被觸發。如果button_action settings的值為其他，或者flash按鈕可用，這個事件都不被觸發

在設置對象的 mouse_click_handler 屬性中可設置此事件處理函數

【新】mouseOver()

mouseOver事件將在鼠標在flash影片的任何部分移動時被觸發

在設置對象的 mouse_over_handler 屬性中可設置此事件處理函數

【新】mouseOut()

mouseOut 事件再鼠標離開flash影片時被觸發

在設置對象的 mouse_out_handler 屬性中可設置此事件處理函數

fileDialogStart()

此事件在selectFile或者selectFiles調用后，文件選擇對話框顯示之前觸發。只能同時存在一個文件對話框。但是，這個事件處理函數將不被執行，直到文件選擇對話框被關閉

在設置對象的 file_dialog_start_handler 屬性中可設置此事件處理函數

fileQueued(file object)

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

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

【新增內容】fileQueueError(file object, error code, message)

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

文件入隊出錯的原因可能有：1.超過了上傳大小限制，2.文件為零字節，3.超過文件隊列數量限制，4.允許外的無效文件類型。

(yukon:經測試，message所含的內容如下：

1.超過了上傳大小限制：message=File size exceeds allowed limit.

2.文件為零字節：message=File is zero bytes and cannot be uploaded.

3.超過文件隊列數量限制：message=int（指你設定的隊列大小限制數）

4.允許外的無效文件類型：message=File is not an allowed file type.

如果你要改這些消息，請在開源包里的swfupload.as里改，然后重新編譯成swfupload.swf。

)

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

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

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

fileDialogComplete(number of files selected, number of files queued, total number of files in the queued)

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

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

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

【新】uploadResizeStart(file object, width, height, encoding, quality)

uploadResizeStart事件處理函數在一個圖片開始調整大小時被調用。調整期間不提供progress事件和處理方法。但是重新編碼圖片會花費一些時間。如果這期間出現錯誤的話 uploadError事件將會被觸發

當調整完成SWFUpload 繼續觸發 uploadStart事件，並且開始和普通上傳一樣的事件鏈.

uploadStart(file object)

在文件開始向服務端上傳之前觸發uploadStart事件，這個事件處理函數可以完成上傳前的最后驗證以及其他你需要的操作，例如添加、修改、刪除post數據等。

在完成最后的操作以后，如果函數返回false，那么這個上傳不會被啟動，如果返回true或者無返回，那么將正式啟動上傳。

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

uploadProgress(file object, bytes complete, total bytes)

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

注意: 在Linux下，Flash Player只在整個文件上傳完畢以后才觸發一次該事件，官方指出這是Linux Flash Player的一個bug，目前SWFpload庫無法解決。

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

uploadError(file object, error code, message)

無論什么時候，只要上傳被終止或者沒有成功完成，那么uploadError事件都將被觸發。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, received response)

當文件上傳的處理已經完成（這里的完成只是指向目標處理程序發送完了Files信息，只管發，不管是否成功接收），並且服務端返回了200的HTTP狀態時，觸發uploadSuccess事件。server data指的是服務器發出的一些數據（比如你自己echo出的）而received response是服務器自己發出的HTTP狀態碼

由於一些Flash Player的bug，HTTP狀態碼可能不會被獲取到，從而導致uploadSuccess事件不能被觸發。由於這個原因，2.50版在設置對象中增加了一個新屬性assume_success_timeout 用來設置是否超過了等待接收HTTP狀態碼的最長時間，超過即觸發 uploadSuccess。在這種情況下，（received response）參數會無效。

設置對象中的 http_success 允許設置在HTTP狀態碼為非200的其他值時也觸發uploadSuccess事件。In this case no server data is available from the Flash Player.

在

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

注意：

server data是服務端處理程序返回的數據。
此時文件上傳的周期還沒有結束，不能在這里開始下一個文件的上傳。
在window平台下，那么服務端的處理程序在處理完文件存儲以后，必須返回一個非空值，否則此事件不會被觸發，隨后的uploadComplete事件也無法執行。

uploadComplete(file object)

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

如果要下個文件自動上傳，那么在這個時候調用this.startUpload()來啟動下一個文件的上傳是不錯的選擇。不過要小心使用。參見注意

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

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

debug(message)

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

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

功能對象 SWFUpload Utility Objects

設置對象 Settings object

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

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

Example:

{ upload_url : "http://www.swfupload.org/upload.php", flash_url : "http://www.swfupload.org/swfupload.swf", flash9_url : "http://www.swfupload.org/swfupload_fp9.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, mouse_click_handler : mouse_click_function, mouse_over_handler : mouse_over_function, mouse_out_handler : mouse_out_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 Description

【新】upload_url

默認值：空字符串

upload_url設置接收的是一個絕對的或者相對於SWF文件的完整URL。推薦使用完整的絕對路徑，以避免由瀏覽器和FlashPlayer修改了基准路徑設置而造成的請求路徑錯誤。（yukon：這其實是相對的，如果你的swfupload和php上傳文件處理頁面始終是放在同一個網站文件夾里，我倒是推薦用相對路徑）

如果設置對象的屬性preserve_relative_urls為false，SWFUpload將會把相對路徑轉化成絕對路徑，來避免URL在不同系統的flash player中被解析成各種不同的格式。如果你禁用SWFUploads的這個轉換，應該使用相對路徑來設定swfupload.swf的位置

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

file_post_name

默認值：Filedata

file_post_name參數允許你設置POST信息中上傳文件的name值（類似傳統Form中設置了<input type="file" name="Filedata"/>的name屬性）。

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

【新】post_params

默認值：空的Object對象

post_params定義了一些鍵/值對，允許在上傳每個文件時候捎帶地post給服務器。這個屬性可以用一個js數組對象來賦值。鍵/值對必須是純字符串或者數字。（可用js的 typeof（）函數檢測）

注意: Flash Player 8 不支持捎帶發送post數據. SWFUpload 會自動的以一個query string的形式發送post_params。

use_query_string

默認值：false

該屬性可選值為true和false，設置post_params是否以GET方式發送。如果為false，那么則以POST形式發送。引進自v2.1.0

【新】preserve_relative_urls

默認值：false

preserve_relative_urls可選值為boolean變量。指示SWFUpload是否將相對URL轉換成絕對URL。如果設置為true，那么不會轉換。默認為false。即自動轉換。

requeue_on_error

默認值：false

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

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

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

http_success

默認值：[]

該數組可自定義觸發success事件的HTTP狀態值。200的狀態值始終會觸發success，並且只有200的狀態會提供serverData。

當接受一個200以外的HTTP狀態值時，服務端不需要返回內容。

【新】assume_success_timeout

默認值：0

assume_success_timeout設定SWFUpload將等待多少秒來檢測服務器響應，超時將強制觸發上傳成功（uploadSuccess）事件。這個屬性是為了在 Flash Player的bug下正常工作。避免長時間的等待服務器響應，同時解決flash player在mac操作系統下無法使服務器返回內容的bug。

flash在最后一個uploadProgress事件被觸發30秒后將忽略服務器的響應而強制觸發上傳成功事件。

如果assume_success_timeout被設置為0，將禁用這個特性。 SWFUpload將長時間等待 Flash Player來觸發 uploadSuccess事件.

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

設置文件上傳隊列中等待文件的最大數量限制。當一個文件被成功上傳，出錯，或者被退出上傳時，如果文件隊列中文件數量還沒有達到上限，那么可以繼續添加新的文件入隊，以頂替該文件在文件上傳隊列中的位置。如果允許上傳的文件上限（file_upload_limit）或者剩余的允許文件上傳數量小於文件隊列上限（file_queue_limit），那么該值將采用這個更小的值。

flash_url

默認值：空字符串

設置絕對或者相對於此上傳頁面的完整URL，一旦SWFupload實例化以后，此設置不能再被修改。

提醒：測試發現使用setUploadURL方法是可以修改此設置的。

【新】flash9_url

(v2.5.0新增) 支持 Flash Player 9的Flash 控件（swf）絕對或相對的URL

flash_width

(v2.1.0已刪除) Defines the width of the HTML element that contains the flash. Some browsers do not function correctly if this setting is less than 1 px. This setting is optional and has a default value of 1px.

flash_height

(v2.1.0已刪除) Defines the height of the HTML element that contains the flash. Some browsers do not function correctly if this setting is less than 1 px. This setting is optional and has a default value of 1px.

flash_color

（ v2.2.0已刪除） This setting sets the background color of the HTML element that contains the flash. The default value is '#FFFFFF'.

Note: This setting may not be effective in "skinning" 1px flash element in all browsers.

prevent_swf_caching

默認值：true

(v2.2.0新增)該布爾值設置是否在Flash URL后添加一個隨機值，用來防止瀏覽器緩存了該SWF影片。這是為了解決一些基於IE-engine的瀏覽器上的出現一個BUG。

提醒：SWFUpload是直接在flash_url后添加了一個swfuploadrnd的隨機參數。如果你給定的flash_url中已經存在了GET類型的參數，那么就會出現兩個問號連接符導致錯誤。

debug

默認值：false

該值是布爾類型，設置debug事件是否被觸發。

注意：SWFUpload代碼中是將此變量和字符串true做的恆等判斷，因此它只認定true為DEBUG模式開啟，如果設置為1，雖然JS認定是開啟模式，並且在初始化完畢后會有生成Debug Console，但后續操作中FLASH不會輸出調試信息。（因為我習慣用1和0代表布爾變量，因此一度疑惑為何Flash的debug信息無法輸出。）

button_placeholder_id

默認值：null

(v2.2.0新增) 該必要參數指定了swfupload.swf將要替換的頁面內的DOM元素的ID值。當對應的DOM元素被替換為SWF元素時，SWF的容器會被添加一個名稱為"swfupload"的樣式選擇器供CSS自定義使用。

button_image_url

默認值：空字符串

(v2.2.0新增) V2.2.0版最大的改變就是引入了一個按鈕到SWF中，利用該參數可以設置一個相對於該swf文件或者是絕對地址的圖片（或者是SWF），作為按鈕的UI展現。所有FLASH支持的圖片類型都可以使用（gif,jpg,png,或者是一個SWF）。

該按鈕圖片需要經過一定規則（CSS Sprite）的處理。按鈕圖片中需要包括按鈕的4個狀態，從上到下依次是normal, hover, down/click, disabled.(可以參照官方demo中的圖片)

button_width

默認值：1

(v2.2.0新增) 設置該SWF的寬度屬性。

button_height

默認值：1

(v2.2.0新增)設置該SWF的高度屬性（按鈕圖片高度的1/4）

button_text

默認值：空字符串

(v2.2.0新增) 該屬性設置Flash Button中顯示的文字，支持HTML。HTML文本的樣式可以通過CSS選擇器並配合button_text_style參數來設置。關於Flash文本對HTML的支持詳細可見 Adobe's Flash documentation。

button_text_style

默認值："color: #000000; font-size: 16pt;"

(v2.2.0新增)此參數配合button_text參數，可以通過CSS樣式來設置Flash Button中的文字樣式。關於Flash文本對CSS的支持詳細可見Adobe's Flash documentation

button_text_top_padding

默認值：0

(v2.2.0新增) 設置Flash Button上文字距離頂部的距離，可以使用負值。

button_text_left_padding

默認值：0

(v2.2.0新增) 設置Flash Button上文字距離左側的距離，可以使用負值。

button_action

默認值：SWFUpload.BUTTON_ACTION.SELECT_FILES(多文件上傳)

(v2.2.0新增) 設置Flash Button點擊以后的動作。默認為SWFUpload.BUTTON_ACTION.SELECT_FILES，點擊按鈕將會打開多文件上傳的對話框。如果設置為SWFUpload.BUTTON_ACTION.SELECT_FILE，則為單文件上傳。如果設置為SWFUpload.BUTTON_ACTION.START_UPLOAD，則啟動文件上傳。

button_disabled

默認值：false

(v2.2.0新增) 該布爾值設置Flash Button是否是禁用狀態。當它處於禁用狀態的時候，點擊不會執行任何操作。

button_cursor

默認值：SWFUpload.CURSOR.ARROW(箭頭光標)

(v2.2.0新增) 此參數可以設置鼠標划過Flash Button時的光標狀態。默認為SWFUpload.CURSOR.ARROW，如果設置為SWFUpload.CURSOR.HAND，則為手形

button_window_mode

默認值：SWFUpload.WINDOW_MODE.WINDOW

(v2.2.0新增) 此參數可以設置瀏覽器具體以哪種模式顯示該SWF影片。

custom_settings

默認值：空的Object對象

該屬性接收一個Object類型數據，可用於安全地存儲與SWFUpload實例關聯的自定義信息，例如屬性和方法，而不用擔心跟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

剩下的設置定義的是一系列事件處理的回調函數，在SWFUpload的操作過程中相應的事件會被觸發。如果你需要在這些回調中進行自定義操作，那么你應該在設置中定義對應的JavaScript函數。

【新】Support Object

SWFUpload實例的support屬性（其類型是一個對象）能確認SWFUpload的某些特性是否能被瀏覽器使用的某版本Flash Player支持

{ load : bool, // 標示SWFupload是否能在當前版本的 Flash Player中載入 imageResize : bool, // 標示當前時候安裝了Flash Player 10或更新版本的Flash Player，並且SWFUpload 是否支持客戶端調節上傳圖片的大小。 }

File Object

File對象包含了一組可用的文件屬性，很多處理事件都會傳遞一個File Object參數來訪問該文件的相關屬性。

{ id : string, // SWFUpload控制的文件的id,通過指定該id可啟動此文件的上傳、退出上傳等 index : number, // 文件在選定文件隊列（包括出錯、退出、排隊的文件）中的索引，getFile可使用此索引 name : string, // 文件名，不包括文件的路徑。 size : number, // 文件字節數 type : string, // 客戶端操作系統設置的文件類型 creationdate : Date, // 文件的創建時間 modificationdate : Date, // 文件的最后修改時間 filestatus : number // 文件的當前狀態，對應的狀態代碼可查看SWFUpload.FILE_STATUS }

Stats Object

該對象提供了上傳隊列的狀態信息，訪問實例的getStats方法可獲取此對象。

該對象包括下面屬性：

{ in_progress : number // 值為1或0，1表示當前有文件正在上傳，0表示當前沒有文件正在上傳 files_queued : number // 當前上傳隊列中存在的文件數量 successful_uploads : number // 已經上傳成功（uploadSuccess觸發）的文件數量 upload_errors : number // 已經上傳失敗的文件數量 (不包括退出上傳的文件) upload_cancelled : number // 退出上傳的文件數量 queue_errors : number // 入隊失敗（fileQueueError觸發）的文件數量

所有這些屬性的值都可以使用setStats方法來修改，除了in_progress 和 files_queued。

插件 SWFUpload Plug-ins

SWFUpload v2.0版本之后引入了幾個插件。它們幫助SWFUpload實現一些功能

大多數插件使用文檔在js插件（plugin）文件夾里

SWFObject

SWFObject插件使用 SWFObject library 來將 SWFUpload Flash組件（Component）插入頁面

這個插件也提供文檔結構載入完畢檢測功能（Document Ready loading）。（yukon：可能此功能像是jQery的$(document).ready()）和flash版本檢測功能。詳細使用方法以文檔的方式記錄在此插件文件夾內。你最好不要使用 SWFObject的文檔結構載入完畢檢測功能（ Document Ready loading）和其他庫的相似功能混搭共同使用。只用其中的一個就可以了。

Flash Player 10: 由於 Flash Player 10要求使用一個按鈕來觸發影片的相關操作，如果這個按鈕（設置對象里的button_placeholder_id屬性可標示它的id）被css之類的設置成hidden或者display：none，SWFUpload將加載失敗。

Cookies

為了解決Flash Cookie的 Bug，Cookies插件將自動獲取你瀏覽器的cookie，並隨上傳發送。cookie將以 POST or GET 形式隨上傳url發送。

此插件以POST或GET方式發送cookie的鍵/值對.在服務器端它們不會以cookie形式來解析。某些自動檢測cookie來確認session和身份授權的框架可能並不能獲取此插件傳遞的值。

Queue Handling

Queue Handling插件提供隊列處理功能。比如整個隊列的上傳，整個隊列的取消，入隊后自動開始上傳。

Speed

speed插件擴展了'file' 對象的幾個屬性用以描述當前上傳情況。此插件包含了當前速度（ current speed）,平均速度（ average speed）,已上傳時間（ elapsed time）,預計還需的時間（ remaining time）等值。

已知的問題 Known Issues

Flash Player以及許多瀏覽器的bug 困擾着SWFUpload. 但是我們一直在努力。

linux上的取消 Cancelling in Linux

使用Flash 9 Player以及更早版本，在linux操作系統上執行取消上傳功能將可能導致瀏覽器崩潰。不過新版本的Flash Player改善了這個問題。

linux上的上傳進度 Upload Progress in Linux

linux上的 Flash Player只在上傳完畢后發出一次上傳進度事件（uploadProgress），而不是像windows里那樣上傳過程中不斷發出。

這是由於一些linux分發版會在上傳過程中鎖定整個瀏覽器。

MAC上的上傳進度 Upload Progress in OS X

我們收到了一些關於MAC操作系統上Flash Player不能觸發uploadProgress事件的報告。詳細的情況還有待了解，但請注意其潛在的問題

MIME Type

無論文件的實際MIME格式是什么，Flash Player以 mime格式application/octet-stream 上傳所有的文件

文件最大可選擇數 Maximum number of selected files

Flash Player本身並沒有限制可選擇上傳文件數的最大值，但是限制了總文件名的最大長度。這個字符串是這樣組成的： "文件名"空格"文件名"...。能上傳文件的個數取決於操作系統對文件名總長度的限制。如果用戶選擇了過多的文件，將會收到flash player的警告消息，並且顯示在文件選擇對話框里（yukon：我在xp一次上傳了173個文件仍然沒警告。。）

代理 Proxies

Flash Player可能不能正常的使用代理。它在處理代理驗證時候有些問題，可能導致某些沖突。

有些殺毒軟件使用一個本地客戶端代理來接收上傳的文件並進行掃描，（貌似是截獲了上傳文件，並把它寫入一個代理服務器，掃描完畢后才會真正發送給目標服務器）這導致SWFUpload錯誤的以為整個文件被上傳了，它將的發出大量的uploadProgress事件，直到100%完畢。當代理真正地上傳給目標服務器的過程中，SWFUpload看起來像是被暫停了。

卡巴斯基殺毒軟件：卡巴斯基 （和其他一些殺軟）實現了一個用戶端的代理，用來截獲本地上傳出的數據。SWFUpload不能檢測這個代理系統的存在。這些代理服務器能非常快地接收上傳的文件，掃描后再發送給目標文件。

apache安全模塊 Apache mod_security

Apache的安全模塊 mod_security驗證服務器收到的 POST消息. Flash Player實現了一個邊緣化的方式（an edge case 翻成取巧的方式？） (有個參數可以決定是否驗證) POST 上傳文件，服務器也實現了。

安全套接層協議層 SSL

我們收到一些報告稱Flash Player 不能通過SSL來上傳. 這個問題的具體情況還沒被確認，但是看起來確實在ssl下上傳並不可靠。特別是使用公匙-自簽名證書（self-signed certificates）時會出現問題。

同樣，由不被信任的簽發機構CA發放的 SSL 證書不能被Flash接受。因為flash並沒有提供一個這樣的接收證書的方法。就像前面說的cookie bug，windows下的flash player只接收它所信任的名單中的CA發放的證書，而不管瀏覽器正在使用中的證書。

授權 Authentication

HTTP 的授權驗證機制不能被Flash Player良好的支持. 最新版本的 Flash Player會好一些，舊版本的可能會造成瀏覽器崩潰。

過早終止連接 Prematurely terminated connections

過早終止連接 Prematurely ending the response (比如ASP.NET中的Response.end()方法) 會導致原本上傳完畢，SWFUpload卻報告上傳失敗。

文件的POST名 Filedata POST name in Linux

改變文件接收名 (默認 “Filedata” ，設置對象中file_post_name屬性) 在Linux的 Flash Player中並不起作用.

Cookie bug

在Windows 下非IE瀏覽器 (FireFox, Opera, Safari, etc) flash插件將會發送IE的cookie . 這破壞了很多服務器的session和授權驗證機制

開發者必須自己手動解決傳遞 Session 和授權 cookie 信息的問題，還要自己手動修改在服務器上的session。如果他們想使用session。

不過SWFUpload軟件包里提供了一個PHP 或 ASP.Net里解決此bug的例子代碼。

ExternalInterface類的bug（ ExternalInterface bugs）

當和瀏覽器/js交互時，Flash Player不能正確使用escape方法編碼數據。SWFUpload為解決這個問題做了很大的努力。將來如果這個bug修復了，SWFUpload將會發送而外的escape編碼數據.

超長服務器數據bug （Server Data length bugs）

過長的服務器響應數據在MAC或Linux系統中的Flash Player下會導致錯誤。數據可能會被裁短，改變或者某些重復。我們建議服務器發回的數據盡量的短小簡明。

Avant Browser

一旦被緩存了，SWFUpload不能正確工作在Avant瀏覽器上.

SWFUpload v2.2.0版本后添加了 prevent_swf_caching 設置來試圖解決這個問題 .

文件選擇對話框與頁面改變 File Dialog & Page Changing

在出現文件選擇對話框時離開或者刷新頁面將會導致瀏覽器崩潰。（所有瀏覽器，所有操作系統下）

這種情況大多出現在你設定了一個超級鏈接<a>的“onclick”調用selectFile/selectFiles ，但又沒有禁止它默認的轉跳動作，點擊這個超鏈的同時會跳到其他頁面但同時又打開了文件選擇對話框。。

（yukon：還有種可能：程序使頁面強制刷新、重定向。比如HTML <meta>標簽里的refresh, ASP.NET的Response.Redirect（），php的header（）等）

服務器腳本執行時間過長 Long Running Upload Scripts

Flash上傳文件給web服務器后，上傳接收程序就會被執行。接收程序決定是否存儲它們，創建縮略圖，掃描病毒等等，如果接收程序30秒內不返回任何數據，Flash將斷開鏈接，並返回一個IO錯誤。

如果你不想這樣做，那么在處理的過程中，讓服務器返回幾個字符或者數據（如果你可以）。

比如PHP，雖然PHP腳本能在Flash斷開后繼續成功地完成操作，但斷開之后Flash將不會接收到任何返回數據。

窗口模式 WMODE / BUTTON_WINDOW_MODE

在某些瀏覽器中，如果flash控件沒有處於屏幕顯示區域，設定的WMODE（由BUTTON_WINDOW_MODE設定）會阻止flash控件的載入。，只有當你拉動滾動條，讓flash控件處於屏幕顯示區域，才會加載並呈現。

（yukon：這樣做是為了讓頁面盡快呈現，比如你打開一個存滿圖片的文件夾，查看方式調為縮略圖，猛的下拉，會看見下面的圖片文件逐漸顯示出內容來）

這種特性可能會對SWFObject插件有不利的影響。SWFUpload事件可能不會被觸發，按鈕的背景圖可能不會被載入除非控件呈現完畢。

某些操作系統中 (Linux ) 當 WMODE被設置為透明， Flash 打開的文件選擇對話框會在瀏覽器窗口之后。

內存泄露 Memory Leaks

一些瀏覽器 (特別是 IE)不能在flash player用 ExternalInterface類與js交互后回收內存，(比如 SWFUpload). 生成過多的SWFUpload實例並且刷新幾次頁面將導致瀏覽器占用內存過多，進而導致瀏覽器崩潰或者其他一些系統錯誤。

在 v2.2.0版本的 SWFUpload中，我們實現了一些預防內存泄露的機制。但是還是推薦您在頁面關閉時候調用destroy（）方法。如果你在一個頁面使用幾百個SWFUpload實例，你必須小心測試以防內存泄露。

有關MAC操作系統的一些問題 Other Mac Issues

服務器返回的數據或 Mac系統上的 Flash Player 可能並不會觸發 uploadSuccess 事件.我們添加了一個 assume_success_timeout 設置來幫助解決這個問題。但是通常情況下，在接收成功后返回一個簡短的字段是十分容易且可靠的。
有些用戶反映在Mac系統下上傳給含子域名的地址時有一些問題
有些用戶反映重定向(HTTP 狀態碼 302) 不能被 Mac Flash Player很好的處理. Windows 下似乎沒這個問題. 302 重定向經常用在一些授權模式和MVC設計框架中。
flash的開發文檔指出在早於 OS X 10.3版本的系統中， bytes loaded 一直會是 -1. SWFUpload把它改成了 0，但是 total bytes將不會被發送出來，進度永遠到不了100% 。因此請設定在上傳完畢，發出uploadSuccess 或 uploadComplete事件時更新UI讓其顯示100%。以此來讓UI在各系統統一。
有些用戶反映Mac Flash Player上傳路徑有空格字符時將出現問題. 請將它們替換成+或者%20
有些用戶反映Mac Flash Player 會在 HTTP HOST頭里加入端口號 (比如 http://www.example.com:80). 如果你檢查這個參數，要小心對付這個問題。
文件如果只包含一個資源分支（resource fork），將會被Flash Player以0字節文件對待，不能上傳(提示: Flash Player 10.1可能解決了這個問題)

免責聲明！

本站轉載的文章為個人學習借鑒使用，本站對版權不負任何法律責任。如果侵犯了您的隱私權益，請聯系本站郵箱yoyou2525@163.com刪除。

猜您在找 Bootstrap Table API 中文版說明文檔 Atomikos 中文說明文檔（周楓翻譯）禪道開源版安裝遷移說明文檔 SWFUpload V2.2.0 說明文檔 Phaser中文說明文檔 Django REST framework（官方說明文檔翻譯）（1快速開始） tcpdf開發文檔（中文翻譯版） Spark官方文檔 - 中文翻譯 Matlab最新的官方文檔中文翻譯 Spark SQL 官方文檔-中文翻譯