simple-uploader.js 文档
simple-uploader.js
(也称 Uploader) 是一个上传库,支持多并发上传,文件夹、拖拽、可暂停继续、秒传、分块上传、出错自动重传、手工重传、进度、剩余时间、上传速度等特性;该上传库依赖 HTML5 File API。
由于是分块上传,所以依赖文件的分块 API,所以受限于此浏览器支持程度为:Firefox 4+
, Chrome 11+
, Safari 6+
and Internet Explorer 10+
。
安装
npm install simple-uploader.js
使用
创建一个 Uploader 实例:
var uploader = new Uploader({target: '/api/photo/redeem-upload-token', query: { upload_token: 'my_token' }
})
// 如果不支持 需要降级的地方
if (!uploader.support) location.href = '/some-old-crappy-uploader'
如果想要选择文件或者拖拽文件的话,你可以通过如下两个 API 来指定哪些 DOM 节点:
uploader.assignBrowse(document.getElementById('browseButton'))
uploader.assignDrop(document.getElementById('dropTarget'))
实例化后你还可以选择监听一些事件:
// 文件添加 单个文件
uploader.on('fileAdded', function (file, event) {console.log(file, event)
})
// 单个文件上传成功
uploader.on('fileSuccess', function (rootFile, file, message) {console.log(rootFile, file, message)
})
// 根下的单个文件(文件夹)上传完成
uploader.on('fileComplete', function (rootFile) {console.log(rootFile)
})
// 某个文件上传失败了
uploader.on('fileError', function (rootFile, file, message) {console.log(rootFile, file, message)
})
服务端如何接受呢?
因为在前端做了一些分块啊等处理,所以也需要服务端做一些特殊处理
每一个上传块都会包含如下分块信息:
chunkNumber:
当前块的次序,第一个块是 1,注意不是从 0 开始的。totalChunks:
文件被分成块的总数。chunkSize:
分块大小,根据 totalSize 和这个值你就可以计算出总共的块数。注意最后一块的大小可能会比这个要大。currentChunkSize:
当前块的大小,实际大小。totalSize:
文件总大小。identifier:
这个就是每个文件的唯一标示。filename:
文件名。relativePath:
文件夹上传的时候文件的相对路径属性。
一个分块可以被上传多次,当然这肯定不是标准行为,但是在实际上传过程中是可能发生这种事情的,这种重传也是本库的特性之一。
对于每个请求的响应码你都可以根据 successStatuses
和permanentErrors
配置项是否是认为成功或失败的:
200
, 201
, 202
: 当前块上传成功,不需要重传。
404
, 415
, 500
, 501
: 当前块上传失败,会取消整个文件上传。
其他状态码: 出错了,但是会自动重试上传。
处理 GET (或者 test() 请求)
如果说 testChunks
配置项是 true
的话,就可以实现秒传、或者刷新页面后、或者重启浏览器、甚至是跨浏览器还可以继续上传的效果,所有的上传必备的参数数据都会被一并发出:
如果请求返回了 successStatuses
配置的状态码,那么假定此块已经上传成功了。
如果返回的是 permanentErrors
中的状态码,那么就认为此块上传失败。
如果是其他状态吗,那么就认为服务端还没有这个块,需要按照标准模式上传。
所以有了以上的支持,服务端就可以根据预先发的这个请求来决定是否需要上传这个块内容,所以也就实现了秒传或者跨浏览器上传特性。
API 文档
Uploader
配置
实例化的时候可以传入配置项:
var r = new Uploader({ opt1: 'val', ...})
支持的配置项:
target
目标上传URL
,可以是字符串也可以是函数,如果是函数的话,则会传入Uploader.File
实例、当前块Uploader.Chunk
以及是否是测试模式,默认值为'/'
。singleFile
单文件上传。覆盖式,如果选择了多个会把之前的取消掉。默认false
。chunkSize
分块时按照该值来分。最后一个上传块的大小是可能是大于等于1倍的这个值但是小于两倍的这个值大小,默认1*1024*1024
。forceChunkSize
是否强制所有的块都是小于等于chunkSize
的值。默认是false
。simultaneousUploads
并发上传数,默认3
。fileParameterName
上传文件时文件的参数名,默认file
。query
其他额外的参数,这个可以是一个对象或者是一个函数,如果是函数的话,则会传入Uploader.File
实例、当前块Uploader.Chunk
以及是否是测试模式,默认为{}
。headers
额外的一些请求头,如果是函数的话,则会传入Uploader.File
实例、当前块Uploader.Chunk
以及是否是测试模式,默认{}
。withCredentials
标准的CORS
请求是不会带上cookie
的,如果想要带的话需要设置withCredentials
为true
,默认false
。method
当上传的时候所使用的是方式,可选multipart、octet
,默认multipart
。testMethod
测试的时候使用的HTTP
方法,可以是字符串或者函数,如果是函数的话,则会传入Uploader.File
实例、当前块Uploader.Chunk
,默认GET
。uploadMethod
真正上传的时候使用的HTTP
方法,可以是字符串或者函数,如果是函数的话,则会传入Uploader.File
实例、当前块Uploader.Chunk
,默认POST
。allowDuplicateUploads
如果说一个文件以及上传过了是否还允许再次上传。默认的话如果已经上传了,除非你移除了否则是不会再次重新上传的,所以也就是默认值为false
。prioritizeFirstAndLastChunk
对于文件而言是否高优先级发送第一个和最后一个块。一般用来发送到服务端,然后判断是否是合法文件;例如图片或者视频的meta
数据一般放在文件第一部分,这样可以根据第一个块就能知道是否支持;默认false
。testChunks
是否测试每个块是否在服务端已经上传了,主要用来实现秒传、跨浏览器上传等,默认true
。preprocess
可选的函数,每个块在测试以及上传前会被调用,参数就是当前上传块实例Uploader.Chunk
,注意在这个函数中你需要调用当前上传块实例的preprocessFinished
方法,默认null
。initFileFn
可选函数用于初始化文件对象,传入的参数就是Uploader.File
实例。readFileFn
可选的函数用于原始文件的读取操作,传入的参数就是Uploader.File
实例、文件类型、开始字节位置startByte
,结束字节位置endByte
、以及当前块Uploader.Chunk
实例。并且当完成后应该调用当前块实例的readFinished
方法,且带参数-已读取的bytes
。checkChunkUploadedByResponse
可选的函数用于根据XHR
响应内容检测每个块是否上传成功了,传入的参数是:Uploader.Chunk
实例以及请求响应信息。generateUniqueIdentifier
可覆盖默认的生成文件唯一标示的函数,默认null
。maxChunkRetries
最大自动失败重试上传次数,值可以是任意正整数,如果是undefined
则代表无限次,默认0
。chunkRetryInterval
重试间隔,值可以是任意正整数,如果是null
则代表立即重试,默认null
。progressCallbacksInterval
进度回调间隔,默认是500
。speedSmoothingFactor
主要用于计算平均速度,值就是从0
到1
,如果是1
那么上传的平均速度就等于当前上传速度,如果说长时间上传的话,建议设置为0.02
,这样剩余时间预估会更精确,这个参数是需要和progressCallbacksInterval
一起调整的,默认是0.1
。successStatuses
认为响应式成功的响应码,默认[200, 201, 202]
。permanentErrors
认为是出错的响应码,默认[404, 415, 500, 501]
。initialPaused
初始文件paused
状态,默认false
。processResponse
处理请求结果,默认function (response, cb) { cb(null, response) }
。 0.5.2版本后,processResponse
会传入更多参数:(response, cb, Uploader.File, Uploader.Chunk)
。processParams
处理请求参数,默认function (params) {return params}
,一般用于修改参数名字或者删除参数。0.5.2版本后,processParams
会有更多参数:(params, Uploader.File, Uploader.Chunk, isTest)
。
属性- support
当前浏览器是否支持 File API
来上传。
supportDirectory
当前浏览器是否支持文件夹上传。opts
实例的配置项对象。files
由Uploader.File
文件对象组成的数组,纯文件列表。fileList
由Uploader.File
文件、文件夹对象组成的数组,文件和文件夹共存。
方法
assignDrop(domNodes)
指定DOM
元素作为拖拽上传目标。unAssignDrop(domNodes)
取消指定的DOM
元素作为拖拽上传目标。on(event, callback)
监听事件。off([event, [callback]])
:off(event)
移除指定事件的所有事件回调off(event, callback)
移除指定事件的指定回调。callback
是一个函数
upload()
开始或者继续上传。pause()
暂停上传。resume()
继续上传。cancel()
取消所有上传文件,文件会被移除掉。progress()
返回一个0-1
的浮点数,当前上传进度。isUploading()
返回一个布尔值标示是否还有文件正在上传中。addFile(file)
添加一个原生的文件对象到上传列表中。removeFile(file)
从上传列表中移除一个指定的Uploader.File
实例对象。getFromUniqueIdentifier(uniqueIdentifier)
根据唯一标识找到Uploader.File
实例。getSize()
上传文件的总大小。sizeUploaded()
所有已经成功上传文件大小。timeRemaining()
剩余时间,单位秒;这个是基于平均上传速度计算出来的,如果说上传速度为0
,那么这个值就是Number.POSITIVE_INFINITY
。
事件
change(event)
input 的change
事件。dragover(event)
拖拽区域的dragover
事件。dragenter(event)
拖拽区域的dragenter
事件。dragleave(event)
拖拽区域的dragleave
事件。fileSuccess(rootFile, file, message, chunk)
一个文件上传成功事件,第一个参数rootFile
就是成功上传的文件所属的根Uploader.File
对象,它应该包含或者等于成功上传文件;第二个参数 file 就是当前成功的Uploader.File
对象本身;第三个参数就是message
就是服务端响应内容,永远都是字符串;第四个参数chunk
就是Uploader.Chunk
实例,它就是该文件的最后一个块实例,如果你想得到请求响应码的话,chunk.xhr.status
就是。fileComplete(rootFile)
一个根文件(文件夹)成功上传完成。fileProgress(rootFile, file, chunk)
一个文件在上传中。fileAdded(file, event)
这个事件一般用作文件校验,如果说返回了false
,那么这个文件就会被忽略,不会添加到文件上传列表中。filesAdded(files, fileList, event)
和fileAdded
一样,但是一般用作多个文件的校验。filesSubmitted(files
, fileList, event) 和filesAdded
类似,但是是文件已经加入到上传列表中,一般用来开始整个的上传。fileRemoved(file)
一个文件(文件夹)被移除。fileRetry(rootFile, file, chunk)
文件重试上传事件。fileError(rootFile, file, message, chunk)
上传过程中出错了。uploadStart()
已经开始上传了。complete()
上传完毕。catchAll(event, ...)
所有的事件。
Uploader.File
属性
uploader
对Uploader
实例的引用。name
文件(夹)名字。averageSpeed
平均速度,单位字节每秒。currentSpeed
当前速度,单位字节每秒。paused
文件是否是暂停的。error
文件上传是否出错了。isFolder
是否是文件夹。
如果不是文件夹的话,那么还会有如下属性:
file
原生HTML5 File
对象。relativePath
文件相对路径。size
文件大小,单位字节。uniqueIdentifier
文件唯一标示。chunks
由Uploader.Chunk
实例组成数组,分成的块集合,一般场景下并不需要关心它。
方法
getRoot()
得到当前文件所属的根文件,这个根文件就是包含在uploader.fileList
中的.progress()
返回一个0
到1
的数字,代表当前上传进度。pause()
暂停上传文件。resume()
继续上传文件。cancel()
取消上传且从文件列表中移除。retry()
重新上传文件。bootstrap()
重新初始化 Uploader.File 对象的状态,包括重新分块,重新创建新的XMLHttpRequest
实例。isUploading()
文件是否扔在上传中。isComplete()
文件是否已经上传完成。sizeUploaded()
已经上传大小。timeRemaining()
剩余时间,基于平均速度的,如果说平均速度为0
,那么值就是Number.POSITIVE_INFINITY
。getExtension()
得到小写的后缀。getType()
得到文件类型。
simple-uploader.js 文档相关推荐
- simple css 汉化,Simple CSS(CSS文档生成器)
Simple CSS(CSS文档生成器)简介 Simple CSS(CSS文档生成器)简介一:Simple CSS是一款CSS文档生成器,帮助网页开发人员快速生成CSS样式,Simple CSS使用非 ...
- Node.js 文档(目录)
Node.js 文档 Node.js®是基于Chrome的V8 JavaScript引擎构建的JavaScript运行时. 提供以下几种类型的文档: API参考文档 ES6功能 指南 API参考文档 ...
- pusher之JS文档阅读
特点介绍文档 https://pusher.com/features Flexible Pub/Sub Messaging 灵活的发布和订阅消息 即时更新浏览器,手机和物联网设备,简单的事件API L ...
- 基于draft.js 和 braft-editor.js文档,自己总结的内容
我还没有整理,但是应该能帮助到你 * 包含一些文章 * 包含自己的总结 * 包含一些自己的实例,自定义块,自定义行内,删除元素等 分割线 1.一篇文档足矣(无数个文章综合体) https://www. ...
- babylon.js文档笔记
babylon 一 基本使用 引入 <script src="https://preview.babylonjs.com/babylon.js"></script ...
- JSDoc入门使用指南 -- 手摸手教你用JSDoc(超好用的js文档生成工具)
安装 准备 Node.js 8.15.0+ 通过npm安装 全局安装:npm install -g jsdoc 若出现权限问题,如 EACCES报错,最佳实践为用node版本管理器(nvm等)重装np ...
- swipe.js文档及用法
最近的一个项目中使用到了swipe.js这个插件 感觉非常的好用的 官方网站 http://swipejs.com/ https://github.com/bradbirdsall/Swipe 简介 ...
- Node.js文档和教程
七天学会NodeJS:https://nqdeng.github.io/7-days-nodejs/ Node入门:http://www.nodebeginner.org/index-zh-cn.ht ...
- js监听iframe关闭_Node.js文档NET[翻译]
Node.js v12.0.0 Documentationnodejs.org Net模块提供一个异步的网络API,这个API可以创建基于流的TCP,或者IPC服务器(net.createServe ...
最新文章
- [Spring入门学习笔记][静态资源]
- YOLOv5-Lite 使用笔记
- c语言常用绘图软件,大佬们,小菜鸟想问一问用vc编译器做简易画图软件
- 00075_BigInteger
- 【NLP】NER数据标注中的标签一致性验证
- ROS安装过程和配置过程(可能出现的问题及解决方法)
- micronaut pk spring boot
- Golang闭包的典型应用
- oppo手机快速截屏的方法
- uefi 懒人版黑苹果_clover+懒人版黑苹果安装(e3+970)
- 后台 事务SqlTransaction
- 2021-2027全球与中国铂金芯片温度传感器市场现状及未来发展趋势
- 2018北京网络赛B题 Tomb Raider
- USB-SC-09(假冒PL2303HXA芯片)WIN7-64位驱动之终极大法
- Unity 实现 角色的换装
- 计算机考试登记表是准考证嘛
- 性能测试线上培训班怎么选 3点教你在线选好培训班
- iceberg Flink操作
- 关于ubuntu无法播放土豆视频的解决方法
- html怎么实现蓝色垂直的直线,css实例教程 一款纯css实现的垂直时间线效果
热门文章
- Java基础项目实战--大学生求职招聘信息网站系统
- 【数据库】Navicat编写MySQL自定义函数详解
- CodeBlocks监视窗口(Watchs)进行调试(引用类型与指针)
- 【mysql的设计与优化专题(5)】慢查询详解
- python提取Excel某几列数据
- 微信小程序的登录界面实现
- java开发的游戏测试_用java编写。模拟一个简单的测试打字速度的游戏
- BR/EDR控制器: 基带规范(Baseband Specification)
- 强化学习(Reinforcement Learning)
- 信息熵:什么是信息熵?