概述
客户端完全基于JavaScript的 浏览器文件上传器，不需要任何浏览器插件，但需要和jQuery框架协同工作，支持超大文件上传，其算法是将一个超大文件切片成N个数据块依次提交给服务 端处理，由服务端存储断点信息实现断点续传的功能；支持文件拖拽上传，直接将文件拖拽到页面元素上方即可自动上传（默认元素是body）；服务端采用asp.net 4.0程序开发，包含有处理程序，提供程序和视图控件,当然也可以用java或者php实现服务端程序。
浏览器兼容：IE10+、火狐、谷歌、Opera、windows phone 8.1
js代码：包含开发版和发布版两个版本，开发版包含有帮助信息，文件大小11kb；而发布版移除了帮助信息，文件大小9kb；
风险提示
此控件通过将文件切片上传超大文件，绕过了ASP.NET内置的MaxRequestLength最大请求检查，建议在服务端进行有效的安全检查。
技术支持
[email protected] 您对此控件有任何要求和疑问都可以给发邮件。
客户端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>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>超大文件上传</title>
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=1.0, user-scalable=no" />
<script src="Scripts/jquery-2.1.1.min.js"></script>
<script src="Scripts/Uploader.release.min.js"></script>
</head>
<body>
<br />
<a href="#" id="btn">select files</a><br />
<input id="m" type="file" />
<a href="javascript:" id="up">upload</a>
<script>
$("#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>
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title></title>
<script src="Scripts/jquery-2.1.1.min.js"></script>
<script src="Scripts/Uploader.js"></script>
</head>
<body>
<cc1:Html5UploaderClient ID="Html5Uploader1" RegisterScript="false" Url="Handler1.ashx" Placeholder="#btnSeletor" Accept="image/*,video/*" runat="server">
<ViewTemplate>
<a href="javascript:" id="btnSeletor" >select files</a>
</ViewTemplate>
<ClientEvents>
<cc1:ClientEvent EventName="complete" Handle="javascript:alert(file.name+‘上传已经完成！‘)" />
</ClientEvents>
<PostParameters>
<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 配置说明的帮助，如：
<script>
Uploader(); //将会输出帮助信息到控制台，打开浏览器的控制台即可获得配置说明的帮助
</script>
2.调用on函数获取事件绑定帮助信息，如：
<script>
var instance= new Uploader();
instance.on();
//将会输出帮助信息到控制台，打开浏览器的控制台即可获得事件绑定帮助信息
</script>