转SWFUpload 官方说明文档(2.5.0版)

Posted 2020-07-28 Just a tech

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了转SWFUpload 官方说明文档(2.5.0版)相关的知识，希望对你有一定的参考价值。

原文出自：http://www.runoob.com/w3cnote/swfupload-document.html

SWFUpload使用指南请查阅：http://www.w3cschool.cc/w3cnote/swfupload-guide.html

内容列表

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_idspan>, 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

以上是关于转SWFUpload 官方说明文档(2.5.0版)的主要内容，如果未能解决你的问题，请参考以下文章

转SWFUpload使用指南

TSC打印机使用教程终极版（转）

SWFUpload详细参数使用说明

Spring Boot 官方文档学习入门及使用[转]

OpenStack Newton部署官方指南

有关于OpenStack的Rocky版官方文档部署中的一些错误