simple-uploader.js（也称 Uploader）是一个上传库，支持多并发上传，文件夹、拖拽、可暂停继续、秒传、分块上传、出错自动重传、手工重传、进度、剩余时间、上传速度等特性；该上传库依赖 HTML5 File API。由于是分块上传，所以依赖文件的分块 API，所以受限于此浏览器支持程度为：Firefox 4+, Chrome 11+, Safari 6+ and Internet Explorer 10+。
Fork flow.js，但是进行了重构。
默认提供了一个 Node.js 的示例，放在 samples/ 目录下。
相比 flow.js 的新特性
- 统一把文件和文件夹对待为
Uploader.File，统一管理 -
Uploader本身其实就是一个根文件夹 - 新增
fileList属性，用来存文件和文件夹合集，只包含根下的文件和文件夹。
特点
- 支持文件、多文件、文件夹上传
- 支持拖拽文件、文件夹上传
- 统一对待文件和文件夹，方便操作管理
- 可暂停、继续上传
- 错误处理
- 支持“快传”，通过文件判断服务端是否已存在从而实现“快传”
- 上传队列管理，支持最大并发上传
- 分块上传
- 支持进度、预估剩余时间、出错自动重试、重传等操作
安装
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)
})
服务端如何接受呢？
因为在前端做了一些分块啊等处理，所以也需要服务端做一些特殊处理，这个可以参考 samples/Node.js/ 实现。
每一个上传块都会包含如下分块信息：
-
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倍的这个值但是小于两倍的这个值大小，可见这个 Issue #51，默认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，参考 multipart vs octet。 -
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实例以及请求响应信息。这样就没必要上传（测试）所有的块了，具体细节原因参考 Issue #1，使用示例. -
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文件、文件夹对象组成的数组，文件和文件夹共存。
方法
-
.assignBrowse(domNodes, isDirectory, singleFile, attributes)指定 DOM 元素可以选择上传。-
domNodesDOM 元素 -
isDirectory如果传入的是true则代表是要选择文件夹上传的，你可以通过判断supportDirectory来决定是否设置 -
singleFile是否只能选择单个文件 -
attributes传入的其他属性值，例如你可以传入accept属性的值为image/*，这样就意味着点选的时候只能选择图片。全部属性列表：https://www.w3.org/wiki/HTML/Elements/input/file
Note: 避免使用
a或者button标签作为选择文件按钮。 -
-
.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原生 HTML5File对象。 -
.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 是 FORK 的 https://github.com/flowjs/flow.js 的，参考了 https://github.com/23/resumable.js。
网友评论