Uploader 文件上传器类_.NET

您所在的位置：程序员俱乐部 > 编程开发 > .NET > Uploader 文件上传器类

Uploader 文件上传器类

2014/8/24 14:39:01 Jackson.Bruce 程序员俱乐部我要评论(0)

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

概述

客户端完全基于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") 读取当前服务端的处理路径

没有返回值

绑定事件,后面将会介绍事件，例如：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

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

可续传信息，如果文件是首次上传那么将会新建一个可续传信息。

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">

<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">

<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

string类型

接受的文件类型，默认值是空的，即是接受全部类型，例如："image/*,video/*" 接受所有图片和视频文件

Types

string类型

Timeout

string类型

超时设置，默认是0,没有设置，格式为：数字+（ms|ss|mm|hh）,例如：1000ms 表示1000毫秒，10hh 表示10小时，默认单位是秒，如：Timeout="60" 表示60秒后超时。

MaxQueue

int

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事件。