HTML5文件上傳器，純腳本無插件的客戶端文件上傳器---Uploader 文件上傳器類

時間 2019-11-08

標籤 html5 html 文件上傳腳本插件客戶端 uploader 欄目 HTML5 简体版

原文原文鏈接

概述javascript

客戶端徹底基於JavaScript的瀏覽器文件上傳器，不須要任何瀏覽器插件，但須要和jQuery框架協同工做，支持超大文件上傳，其算法是將一個超大文件切片成N個數據塊依次提交給服務端處理，由服務端存儲斷點信息實現斷點續傳的功能；支持文件拖拽上傳，直接將文件拖拽到頁面元素上方便可自動上傳（默認元素是body）；服務端採用asp.net 4.0程序開發，包含有處理程序，提供程序和視圖控件,固然也能夠用java或者php實現服務端程序。html

瀏覽器兼容：IE10+、火狐、谷歌、Opera、windows phone 8.1java

js代碼：包含開發版和發佈版兩個版本，開發版包含有幫助信息，文件大小11kb；而發佈版移除了幫助信息，文件大小9kb；jquery

風險提示算法

此控件經過將文件切片上傳超大文件，繞過了ASP.NET內置的MaxRequestLength最大請求檢查，建議在服務端進行有效的安全檢查。json

技術支持windows

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