SWFUpload使用指南请查阅 /w3cnote/swfupload-guide.html
内容列表
js对象 SWFUpload JavaScript Object
addSetting 不推荐 deprecated)
getSetting 不推荐 deprecated)
retrieveSetting 已移除 removed in v2.1.0)
destroy 添加自2.1.0 added in v2.1.0)
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
默认值 []
该数组可自定义触发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自定义使用
尊贵的董事大人
英文标题不为空时 视为本栏投稿
需要关键字 描述 英文标题