SWFUpload使用指南

内容简介

​ 由于在最近的项目中需要完成多文件的上传功能需求，要求兼容ie6及其以上版本，这里使用SWFUpload插件，要注意此插件是基于flash的，本文主要介绍了SWFUpload的基本用法和注意事项还有工作中遇到的一些问题。

SWFUpload特点

• 允许一次上传多个文件，但会有一个上传队列，队列里文件的上传是逐个进行的，服务器端接收文件时跟普通的表单上传文件是一样的;
• 类似AJAX的无刷新上传；
• 可以显示上传进度；
• 良好的浏览器兼容性；
• 兼容其他JavaScript库 (例如:jQuery), Prototype等)；
• 可以在浏览器端就对要上传的文件进行限制;
• 提供了丰富的事件接口供开发者使用;

SWFUpload参数设置

这里使用的是V2.2.0版本，首先在页面引入相关js

<script src='/swfupload/swfupload.js'></script>
<script src='/swfupload/swfupload.queue.js'></script>
<script src='/swfupload/fileprogress.js'></script>
<script src='/swfupload/handlers.js'></script>

然后配置参数

<!-- Html Code-->
<div id="FileList"></div>
<div id="spanSWFUpload">
	<span id="spanSWFUploadButton"></span>
</div>
<button type="button" id="ubutton">上传</button>

var swfu;
var settings_object = {
	upload_url: "ServerURL",//服务器地址
	flash_url: "/swfupload/swfupload.swf",//swf文件路径
	button_placeholder_id: "spanSWFUploadButton",
	file_size_limit: "20MB", //设置文件选择对话框的文件大小过滤，该属性可接收一个带单位的数值，可用的单位有B,KB,MB,GB。如果忽略了单位，那么默认使用KB。特殊值0表示文件大小无限制。
	file_upload_limit: 12, //设置SWFUpload实例允许上传的最多文件数量
	file_queue_limit: 12, //设置文件上传队列中等待文件的最大数量限制
	button_width: "60",
	button_height: "18",
	button_text: '<span class="theFont">添加文件</span>',
	button_text_style: ".theFont { font-size: 12;}",
	button_text_left_padding: 5,// 设置Flash Button上文字距离左侧的距离，可以使用负值。
	button_text_top_padding: 0,//设置Flash Button上文字距离顶部的距离，可以使用负值。
	//button_action: SWFUpload.BUTTON_ACTION.SELECT_FILE, //设置每次只能选择1个文件
	post_params: {}, //选填，文件上传时附带的参数，也可以在后续动态添加
	use_query_string: false,//设置post_params是否以GET方式发送。如果为false，那么则以POST形式发送。
	requeue_on_error: false,//当文件对象发生uploadError时，文件的处理方式，如果为true,该文件对象会被重新插入到文件上传队列的前端，而不是被丢弃。
	file_types: "*.doc;*.docx;*.pdf;*.xls;*.xlsx",
	button_cursor: SWFUpload.CURSOR.HAND,//设置鼠标划过Flash Button时的光标状态。
    //下面为一系列的回调函数，在文章的后续部分会一一介绍
	file_queued_handler: fileQueued,
	file_queue_error_handler: fileQueueError,
	upload_start_handler: uploadStart,
	upload_error_handler: uploadError,
	upload_success_handler: uploadSuccess,
	upload_complete_handler: uploadComplete
	};
	swfu = new SWFUpload(settings_object);//创建一个SWFUpload对象，并将配置的参数设置进去
	//绑定上传按钮，点击开始上传
	document.getElementById("ubutton").onclick = function (ev) {
         swfu.startUpload();
    }

​ 写到这里，我们的上传就已经可以使用了，但是没有任何的提示，需要注意的是，默认情况下，你选择了文件并关闭了文件选择对话框文件并不会自动开始上传，你需要调用SWFUpload的startUpload()方法，该方法接收一个file_id作为参数，如果参数为空，则自动开始上传文件队列中的第一个文件。选择完文件后如果文件会自动开始上传，可以将 handles.js 中的 this.startUpload()注释掉即可。Swfupload虽支持批量上传，但本质仍是单个文件依次上传，也就是说，每次上传文件都是一次独立的请求。

回调函数

• **file_queued_handler:fileQueued(file object) ** 当文件选择对话框关闭消失时，如果选择的文件成功加入上传队列，那么针对每个成功加入的文件都会触发一次该事件（N个文件成功加入队列，就触发N次此事件，我们可以在这里完成已选择文件列表的展示功能。

	//File Object包含了一组可用的文件属性
	{
		id : string, // SWFUpload控制的文件的id,通过指定该id可启动此文件的上传、退出上传等
		index : number, // 文件在选定文件队列（包括出错、退出、排队的文件）中的索引，getFile可使用此索引
		name : string, // 文件名，不包括文件的路径。
		size : number, // 文件字节数
		type : string, // 客户端操作系统设置的文件类型
		creationdate : Date, // 文件的创建时间
		modificationdate : Date,	// 文件的最后修改时间
		filestatus : number // 文件的当前状态
	}
	

• file_queue_error_handler:fileQueueError(file object, error code, message) 当选择文件入队失败时触发，每个出错的文件都会触发一次该事件，文件添加队列出错的原因可能有:超过了上传大小限制(-110)，文件为零字节(-120)，超过文件队列数量限制(-100)，设置之外的无效文件类型(-130)。

• upload_start_handler:uploadStart(file object) ** 在文件往服务端上传之前触发此事件，可以在这里完成上传前的最后验证以及其他你需要的操作，例如添加、修改、删除post数据**等。在完成最后的操作以后，如果函数返回false，那么这个上传不会被启动，并且触发uploadError事件，如果返回true或者无返回，那么将正式启动上传。

• **upload_error_handler:uploadError(file object, error code, message) **只要上传被终止或者没有成功完成，那么该事件都将被触发。具体的错误代码如下:

     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
     };

• upload_success_handler:uploadSuccess(file object, server data) 当文件上传的处理已经完成（这里的完成只是指向目标处理程序发送了Files信息，只管发，不管是否成功接收），并且服务端返回了200的HTTP状态时，触发此事件。在window平台下，服务端的处理程序在处理完文件存储以后，必须返回一个非空值，否则此事件不会被触发

• upload_complete_handler:uploadComplete(file object) 当上传队列中的一个文件完成了一个上传周期，无论是成功(uoloadSuccess触发)还是失败(uploadError触发)，此事件都会被触发，这也标志着一个文件的上传完成，可以进行下一个文件的上传了。

• upload_progress_handler:uploadProgress(file object, bytes complete, total bytes) 该事件由flash定时触发，提供三个参数分别访问上传文件对象、已上传的字节数，总共的字节数。因此可以在这个事件中来定时更新页面中的UI元素，以达到及时显示上传进度的效果。注意:该事件在Linux版本的Flash Player中存在问题，目前还无法解决。

  这些回调函数可以帮助我们做很多事情，比如在文件加入队列之前做的一些校验，比如我们可以在文件fileQueued()方法中完成文件入队前的一些校验，并通过cancelUpload(fileId)（会触发uploadError事件）方法来将文件移除队列。

有关参数的传递

在SWFUpload的配置参数中的post_params参数是用来向后台传递参数的，如果无法传递，请尝试将另一个配置参数use_query_string设置为true之后就可以传递参数了。该参数接收一个JS对象:

post_params: {  
    param1: 'Hello',  
    param2: '你好'  
} 

但是如果参数值中含有中文的话，那么后台会报错，也取不到值，可以这样解决:

post_params: {  
    param1: encodeURI('你好',"utf-8")  
} 

然后在后台再decode回来，以Java为例:

URLDecoder.decode(request.getParameter("param1"), "utf-8");  

其他问题

• 文件上传完成后的页面跳转: 可以通过监听uploadSuccess(file object, server data)方法，通过JS控制挑转，该事件在每个文件上传成功均会触发如果同时在上传多个文件，那么第一个文件上传完成后页面就直接跳转了，后面的文件将不会上传，可以通过SWFUpload.getStats().files_queued是否为0来判断是否还有未上传的文件。
• 在非IE浏览器中Session不同的问题: 这是由于Flash Player在非IE浏览器下一个Bug引起的，导致用户登录的Session和文件上传产生的Session不同，也就是说文件上传另生成了一个新的Session。解决办法是手动将SessionID传到后台服务端，在上传路径URL里加上jsessionid变量即可。

upload_url: "ServerURL;jsessionid=<%=request.getSession().getId() %>"

常用方法

//指定file_id来启动该文件的上传，如果file_id被忽略了，那么默认开始上传第一个文件。
void startUpload(file_id) 
//指定file_id来退出文件的上传，从上传队列中删除该文件。
//如果忽略file_id，那么默认文件上传队列中的第一个文件将被退出上传。
//如果取消的文件是正在上传，那么会触发uploadError事件。
//如果将可选参数trigger_error_event设置为false,那么uploadError事件不会触发。
void cancelUpload(file_id, trigger_error_event) 
//如果当前有文件上传，那么停止上传，并且将文件还原到上传队列中。
//停止了正在上传的文件，uploadError事件会被触发。如果此时没有正在上传文件，那么不会发生任何操作，不会触发任何事件。
void stopUpload() 
//获取当前状态的统计对象,具体见Stats Object
object getStats() 
Stats Object:{
	in_progress : number // 值为1或0，1表示当前有文件正在上传，0表示当前没有文件正在上传
	files_queued : number // 当前上传队列中存在的文件数量
	successful_uploads : number	// 已经上传成功（uploadSuccess触发）的文件数量
	upload_errors : number // 已经上传失败的文件数量 (不包括退出上传的文件)
	upload_cancelled : number	// 退出上传的文件数量
	queue_errors : number // 入队失败（fileQueueError触发）的文件数量
}
//动态修改post_params，以前的属性全部被覆盖。param_object必须是一个JavaScript的基本对象，所有属性和值都必须是字符串类型。
void setPostParams(param_object)

更多详细的功能请参考SWFUpload V2.2.0 API 说明文档