HTML5文件上传器，纯脚本无插件的客户端文件上传器---Uploader 文件上传器类

概述

客户端完全基于JavaScript的浏览器文件上传器，不需要任何浏览器插件，但需要和jQuery框架协同工作，支持超大文件上传，其算法是将一个超大文件切片成N个数据块依次提交给服务端处理，由服务端存储断点信息实现断点续传的功能；支持文件拖拽上传，直接将文件拖拽到页面元素上方即可自动上传（默认元素是body）；服务端采用asp.net 4.0程序开发，包含有处理程序，提供程序和视图控件,当然也可以用java或者php实现服务端程序。

浏览器兼容：IE10+、火狐、谷歌、Opera、windows phone 8.1

js代码：包含开发版和发布版两个版本，开发版包含有帮助信息，文件大小11kb；而发布版移除了帮助信息，文件大小9kb；

风险提示

此控件通过将文件切片上传超大文件，绕过了ASP.NET内置的MaxRequestLength最大请求检查，建议在服务端进行有效的安全检查。

技术支持

Jackson.bruce@live.com 您对此控件有任何要求和疑问都可以给发邮件。

客户端JavaScript代码

window.Uploader 类

静态属性：

名称	类型	描述说明
Version	Object类型	{major:1 //主版本号 ,minor:0 //次版本号 ,revision:0//修订号 }
Support	布尔类型	当前浏览器是否支持此上传器
Sliced	枚举类型	切片上传的开启状态 { Auto: 0 //当文件超过数据块（blobSize）大小时，启用切片上传 , Enabled: 1//始终将文件分割为N个数据块上传 , Disabled: 2 //始终将整个文件上传 }
ErrorType	枚举类型	描述错误的类型 { InvalidType: 0 //当验证文件类型无效时得到此类异常，无效的文件类型， , UpperLimit: 1 //文件的大小超过指定的上限 , HttpType: 2 //传输过程中抛出的HTTP类型的错误 , ServerType: 3 //数据已成功送达服务器，但不是500错误，有服务端验证文件类型失败，或者验证用户身份与授权失败时由程序抛出的错误类型。 , UserAbort: 4 //用户手动终止上传的错误类型 , InvalidOperation: 5 //调用续传方法时，如果文件已经正在上传中，那么是为此操作无效。 };

静态方法

名称	返回类型	描述
SizeToString	返回string类型，它包含表示大小的数值和字节单位	两参数size：字节的总数，num：精确度

属性：

名称	类型	描述说明
version	Object类型	这个同静态属性
support	布尔值	这个同静态属性

方法

名称	返回类型	描述说明
settings	返回变体类型	读取传递给构造函数的settings设置的字段值，例如：o.settings("url") 读取当前服务端的处理路径
on	没有返回值	绑定事件,后面将会介绍事件，例如：o.on("error",function(file,args){}) 或者 o.on({error:function(file,args){},success:function(file,args){}});
upload	没有返回值	上传指定的文件列表，需要传递一个文件列表的参数

事件（所有事件都是可选的）

名称	参数	描述说明
selecting	function(file,args)	当开始选取文件时触发，参数args:{ cancel: false //是否取消上传 ,invalidType:false\|\|true //文件类型是否有效的 } this 是Uploader类型
validate	function(file,args)	在selecting事件前触发，验证选择文件的类型是否有效，参数 args : { invalid: true // 返回默认是true表示无效的，如果文件是有效的类型，那么返回false , accept: string //表示对应的settings设置，对话框里面接受的文件类型。 ,types: Arry //数组表示有效的文件类型列表，可以通过settings设置的 };
selected	function(file)	当已经选取要上传的文件时触发，this 是Uploader类型
upload	function(file,args)	当开始上传文件时触发，args.cancel 是否要取消上传，this 是Uploader类型
createProgress	function(file,args)	当创建进度视图时触发， args.view：返回已经创建的视图，如果为null 那么上传器将会智能创建简单的视图。this 是Uploader.Progress类型
getResumableInfoHandler	function(url,params,callback)	正在获取续传信息时触发 url：服务端处理程序，params：文件参数 {fileType:string,fileName:string,fileSize:number,blobSize: number,blobCount:number} callback:function(info) 需要传递续传信息给回调函数，传信息应包含 Info.key 文件唯一标识，可以是MD5或者是GUID等类型这个取决于服务端的提供程序 Info.index 上一次成功保存的数据块索引，如果是首次上传那么应该是0 this 是Uploader.Progress类型
progress	function(file,args)	当更新进度视图触发，args: {view:当前视图,cancel: false,size :文件大小,loaded:已经上传的大小,percent:0 ~ 100} args.cancel 是取消默认动作 this 是Uploader.Progress类型
complete	function(file,args)	当文件上传完成时触发参数args:{view:当前视图, req: XMLHttpRequest, status:XMLHttpRequest.status} this 是Uploader.Progress类型
success	function(file,args)	当文件上传成功时触发， args:{view:当前视图 , result:{…} //结果如果有错将包含 err 或者 error 属性 ,responseText: XMLHttpRequest.responseText // 服务端返回的数据 ,cancel: false , req: XMLHttpRequest对象 ,responseType: XMLHttpRequest.responseType , responseXML: XMLHttpRequest.responseXML} this 是Uploader.Progress类型
error	function(file,args)	当引发错误时触发 args:{ view: 当前视图 ,type:Uploader.ErrorType ,code:number ,message:string } this 是Uploader.Progress类型
pause	function(file,args)	当用户暂停上传时触发，args:{ view: view }
proceed	function(file,args)	当用户点击续传时触发，args:{ view: view,cancel:false }
cancel	function(file,args)	当用户点击取消动作并成功取消时触发，args:{ view: view }
drop	function(e)	启动拖拽上传时（dragable=true）在拖拽容器上拖拽时触发的事件
dragover	function(e)	启动拖拽上传时（dragable=true）在拖拽容器上拖拽时触发的事件
dragleave	function(e)	启动拖拽上传时（dragable=true）从拖拽容器上拽出时触发的事件

构造函数与settings配置

Uploader 构造函数

参数：settings 是object类型

属性

名称	类型	描述说明
placeholder	可选的类型：jQuery对象或者字符串类型的jQuery选择器	打开文件选择器的占位符，例如："#btnSelectFiles"
multiple	布尔值	文件选择器对话框是否支持多选,默认值true
accept	string类型	接受的文件类型，默认值是空的，即是接受全部类型，例如："image/,video/" 接受所有图片和视频文件
types	string类型	允许上传的的文件类型，在上传文件之前通过此类型类别验证文件的扩展名，这个类型应该与上面的accept尽量对应，例如：accept="image/jpeg,image/gif,image/png" 那么验证类型列表types应该是".jpg;.gif;.png" 这个是客户端验证的类型列表，但在服务端也要应该做同样的验证。
timeout	number类型	超时设置，默认是0,没有设置
maxQueue	number类型	最大的队列数，默认是2，即是同时上传2个文件，如果超过2个文件，那么其他文件将在队列中等候，例如：您上传4个文件，那么前2个文件开始上传，其余的两个文件将在队列中等候直到队列中有其他文件完成了才开始上传。
dragable	布尔值	是否可以拖拽文件上传，默认是未开启的
dragContainer	可选的类型：jQuery对象或者字符串类型的jQuery选择器	文件拖拽入的容器，默认是body，如："#container" 或者 $("#container" )
progress	可选的类型：jQuery对象或者字符串类型的jQuery选择器	文件上传进度列表容器，如："#progressList"
blobSize	number 类型	文件切片上传时，单个数据块的大小，单位是字节
sliced	枚举类型	是否支持切片上传可用值：Uploader.Sliced.Auto ,Uploader.Sliced.Enabled ,Uploader.Sliced.Disabled 默认值 Uploader.Sliced.Auto
limitSize	number 类型	上传文件大小限制，单位是字节，默认值0 表示没有限制，出于安全考虑建议设置一定的大小进行限制上传的文件，同时在服务端也要进行验证。
url	string类型	服务端的处理程序，默认值是当前浏览器的地址（location.href）如："/fileUpload/handler"
parseResult	function(serverData)	函数用来解析服务端返回的结果集并返回值是object，如果服务端有错误应该返回{err:true,msg:“错误描述”}的对象
params	{name:value[,name1:value1]…}	提交到服务端的自定义参数，object类型

参数events 是object类型包含绑定的事件，请参照事件绑定。

Uploader.Progress类

这个是一个封闭的类，在外部无法创建它的实例，从createProgress事件开始得到此类型的一个实例，它包含以下方法和属性：

属性

名称	类型	描述说明
owner	Uploader类型	创建者
size	number类型	文件的大小，只读的，单位是字节
blobSize	number类型	数据块的大小，只读的，单位是字节
sliced	布尔值	是否将文件分割上传，只读的
view	jQuery	由createProgress事件创建的进程视图
bar	jQuery	进度视图里的进度条
resumableKey	string	续传文件的唯一标识，由服务端返回，只读的
loaded	number类型	已经上传了的总大小，只读的
xhr	XMLHttpRequest类型	发送数据的请求对象，只读的
hasError	布尔值	是否发生了错误，只读的
count	number类型	文件切片的总数，只读的
index	number类型	当前正在上传的数据块索引，只读的
paused	布尔值	当前是否为停止状态，只读的

方法

名称	描述说明
pause	停止正在上传的文件，同时改变paused属性值，并抛出Uploader.ErrorType.UserAbort 类型的异常，将会触发pause事件
proceed	继续上传，如果当前已经正在上传，那么将得到 Uploader.ErrorType.InvalidOperation类型的异常信息，将会触发proceed事件
cancel	取消上传文件，如果sliced=true，那么将向服务端发送{ method: "deleteResumable", resumableKey: resumableKey } 信息，通知服务端上传已经上传的数据块，如果成功取消，将会触发cancel事件

例子：

<!DOCTYPE html>

<head>

<title>超大文件上传</title>

</head>

<body>

<br />

<a href="#" id="btn">select files</a><br />

<a href="javascript:" id="up">upload</a>

$("#up").click(function () {

$("#m").asyncUploadFiles({ url: "Handler1.ashx" }, { complete: function (f,e) { alert(f.name+"上传已经完成！") }});

});

var uploader = new Uploader({

placeholder: "#btn", url: "Handler1.ashx"//,limitSize:1024*1024*50

, dragable: true//,dragContainer:$("#kk")

});

</script>

</body>

</html>

ASP.NET 控件与提供程序

提供程序的主要类

FilesUploadHandler 类文件上传服务端处理程序

ResumableInfoProvider 类可续传信息提供程序抽象类，续传信息管理的基类

ResumableInfoXmlProvider类 XML续传信息提供程序，将可续传信息存储在XML文档中，是当前处理的默认提供程序。

FilesUploadHandler 类实现了IHttpHandler 和 IDisposable 接口

主要方法

名称	返回类型	描述说明
虚拟 CreateStorePath	返回表示一个可用路径的字符串	其重载版本要提供一个目录路径
虚拟 Init	没有返回值	其派生类可以重写此方法来绑定事件
IsValidation	布尔值	表示指定的上传文件是否合法，此方法将会触发Validate事件
虚拟 Save	IEnumerable<FileUploadComplete>	返回已经处理完成的文件列表信息，此列表将以JSON的格式响应到客户端。
虚拟 SaveFile	FileUploadComplete	保存指定的文件，并返回完成信息。
虚拟 SaveResumableInfo	没有返回值	保存指定的可续传信息
虚拟 RemoveResumableInfo	没有返回值	移除指定的可续传信息
虚拟DeleteResumable	没有返回值	接收到客户端的取消通知时将调用此方删除已经保存的数据块。

主要属性

名称	类型	描述说明
虚拟 Provider	ResumableInfoProvider	可续传信息管理的基类，默认是ResumableInfoXmlProvider，可以在派生类可以返回其他的提供程序，如：存储在SQL的提供程序等。
Sliced	布尔值	是否当前上传的文件是否为超大文件中的一个切片。
BlobIndex	long	当前数据块的索引
BlobSize	Long	超大文件已被分割的数据块总数
FileSize	Long	文件的总大小
ResumableKey	GUID	可续传信息的唯一标识
FileName	String	客户端提交的文件名称
FileType	String	文件的类型
ResumableInfo	ResumableInfo	可续传信息，如果文件是首次上传那么将会新建一个可续传信息。
HasFiles	Bool	客户端是否提交有文件
IsAuthenticated	Bool	当前用户是否已经授权。
Token	String	只读的，客户端提交的票据以防止CSRF攻击，但需要手动验证。

事件

名称	委托	描述说明
Error	Action<FilesUploadHandler, Exception>	抛出一个未处理的异常时触发。
Complete	Action<FilesUploadHandler, CompleteArguments>	当上传的文件处理完成时触发。
Validate	Action<FilesUploadHandler, ValidateArguments>	当验证一个文件是否有效时触发。

客户端控件类

Html5UploaderClient类输出脚本代码和html视图

公共属性

名称	类型	描述说明
ViewTemplate	ITemplate	视图模板，可以放置任何HTML元素或者ASP.NET控件，可选的
ClientEvents	ClientEventsCollection	客户端事件集合，例如： <cc1:Html5UploaderClient ID="Html5Uploader1" RegisterScript="false" runat="server"> <ClientEvents> <cc1:ClientEvent EventName="success" Handle="function(file,arg){ js coding... }" /> <cc1:ClientEvent EventName="complete" Handle="completeFunction" /> <cc1:ClientEvent EventName="progress" Handle="javascript: js coding... " /> </ClientEvents> </cc1:Html5UploaderClient> 注意Handle包含了三种格式，这三种格式都是合法的。
PostParameters	PostParametersCollection	提交到服务端处理程序的自定义参数集合，例如： <cc1:Html5UploaderClient ID="Html5Uploader1" RegisterScript="false" runat="server"> <PostParameters> <cc1:PostParameter Key="param1" Value="value1" /> <cc1:PostParameter Key="param2" Value="value2" /> </PostParameters> </cc1:Html5UploaderClient>
Token	String	读取或设置长度不超过50的动态票据，如果设置了该属性就需要在服务端手动验证以防止CSRF攻击。
Url	string	服务端处理程序的路径
Placeholder	string	打开文件选择器的占位符，例如： Placeholder="#btnSelectFiles" 或者 Placeholder="$:$('#btnSelectFiles')" 这两种格式都是合法的
Multiple	布尔值	文件选择器对话框是否支持多选,默认值true
Accept	string类型	接受的文件类型，默认值是空的，即是接受全部类型，例如："image/,video/" 接受所有图片和视频文件
Types	string类型	允许上传的的文件类型，在上传文件之前通过此类型类别验证文件的扩展名，这个类型应该与上面的accept尽量对应，例如：accept="image/jpeg,image/gif,image/png" 那么验证类型列表types应该是".jpg;.gif;.png" 这个是客户端验证的类型列表，但在服务端也要应该做同样的验证。
Timeout	string类型	超时设置，默认是0,没有设置，格式为：数字+（ms\|ss\|mm\|hh）,例如：1000ms 表示1000毫秒，10hh 表示10小时，默认单位是秒，如：Timeout="60" 表示60秒后超时。
MaxQueue	int	最大的队列数，默认是2，即是同时上传2个文件，如果超过2个文件，那么其他文件将在队列中等候，例如：您上传4个文件，那么前2个文件开始上传，其余的两个文件将在队列中等候直到队列中有其他文件完成了才开始上传。
Dragable	布尔值	是否可以拖拽文件上传，默认是未开启的
DragContainer	string	文件拖拽入的容器，默认是body，如： dragContainer="#container" 或者 dragContainer="$:$('#container' )"
Progress	string	文件上传进度列表容器，如： Progress="#progressList" ,Progress="$:$('#progressList' )"
BlobSize	string	文件切片上传时，单个数据块的大小，例如：BlobSize="4MB" 或者 "332KB" 或者 "1GB" 都是可以的
Sliced	UploaderSliceds枚举类型	是否支持切片上传可用值：Auto,Enabled,Disabled 默认值 Auto
LimitSize	string	上传文件大小限制，单位是字节，默认值0 表示没有限制，例如：LimitSize="4MB" 或者 "332KB" 或者 "23GB" 都是可以的
ParseResult	string	客户端函数用来解析服务端返回的结果集并返回值是object，如果服务端有错误应该返回{err:true,msg:“错误描述”}的对象
RegisterScript	bool	是否注册客户端脚本，默认是true，如果您在模板里面添加了脚本，那么您可以把它设为fase

例子：

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="WebForm1.aspx.cs" Inherits="WebApplication1.WebForm1" %>

<%@ Register assembly="Html5Uploader" namespace="Html5Uploader.Controls" tagprefix="cc1" %>

<!DOCTYPE html>

</head>

<body>

<cc1:Html5UploaderClient ID="Html5Uploader1" RegisterScript="false" Url="Handler1.ashx" Placeholder="#btnSeletor" Accept="image/*,video/*" runat="server">

<a href="javascript:" id="btnSeletor" >select files</a>

</ViewTemplate>

<cc1:ClientEvent EventName="complete" Handle="javascript:alert(file.name+'上传已经完成！')" />

</ClientEvents>

<cc1:PostParameter Key="param1" Value="value1" />

<cc1:PostParameter Key="param2" Value="value2" />

</PostParameters>

</cc1:Html5UploaderClient>

</body>

</html>

异常

当提交的数据包与可续传信息不匹配时，服务器端上传处理程序将此异常定性为POST攻击，并抛出InvalidDataBlobException异常，其他安全检查建议Validate事件中检查，如：最大上传限制、文件类型检查、动态票据Token验证等等。

客户端与服务端的合约

1.服务端应该返回json格式的字符串，服务端应该处理500错误，发生错误应该返回'{"err:true,"msg":"错误描述"}' 或者 '{"error":true,"message":"错误描述"}' 告诉客户端发生了什么。

2.客户端获取续传信息时提交{method:"getResumableInfo",fileType:string,fileName:string,fileSize:number,blobSize: number,blobCount:number} 数据，服务端要实现getResumableInfo方法根据提交的信息查找续传信息，并返回'{"key":"文件续传信息唯一标识","index":"最后一次上传的数据块索引"}'，当关闭可续传功能时可以忽略此合约，或者在客户端捕捉“getResumableInfoHandler”事件更改合约实现自定义合约，但事件的callback函数应该要返回{key:"文件续传信息唯一标识",index:number} 类型的JS对象，详情请参照getResumableInfoHandler事件。

关于开发版的一些小技巧

如果您使用的是开发版的脚本代码，而您又不太熟悉Uploader对象的使用方法，那么您可以通过以下方法获得帮助：

1.调用构造函数获取settings 配置说明的帮助，如：

Uploader(); //将会输出帮助信息到控制台，打开浏览器的控制台即可获得配置说明的帮助

</script>

2.调用on函数获取事件绑定帮助信息，如：

var instance= new Uploader();

instance.on();

//将会输出帮助信息到控制台，打开浏览器的控制台即可获得事件绑定帮助信息

</script>

演示下载

http://download.csdn.net/detail/j_honghai/7810289

posted @ 2014-08-24 13:47 Jackson.Bruce 阅读(2126) 评论(2) 编辑收藏举报

刷新页面返回顶部

Jackson.Bruce

HTML5文件上传器，纯脚本无插件的客户端文件上传器---Uploader 文件上传器类

公告