hs-upload-plugin v1.0.0

hs-form-plugin 是一个上传库，支持多并发上传，文件夹、拖拽、可暂停继续、秒传、分块上传、出错自动重传、手工重传、进度、剩余时间、上传速度等特性；该上传库依赖 HTML5 File API。

Fork flow.js，但是进行了重构。

由于是分块上传，所以依赖文件的分块 API，所以受限于此浏览器支持程度为：Firefox 4+, Chrome 11+, Safari 6+ and Internet Explorer 10+。

安装

npm install hs-form-plugin --save

使用

创建一个 Uploader 实例：

var uploader = new uploadPlugin({
  target: '/api/photo/redeem-upload-token', 
  query: { 
      clientId: '123',
      secretKey: '123',
      tenantId: '002',
 }
})

如果想要选择文件或者拖拽文件的话，你可以通过如下两个 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: 文件被分成块的总数。
• fileSliceSize: 分块大小，根据 totalSize 和这个值你就可以计算出总共的块数。注意最后一块的大小可能会比这个要大。
• currentChunkSize: 当前块的大小，实际大小。
• totalSize: 文件总大小。
• identifier: 这个就是每个文件的唯一标示。
• filename: 文件名。
• relativePath: 文件夹上传的时候文件的相对路径属性。

一个分块可以被上传多次，当然这肯定不是标准行为，但是在实际上传过程中是可能发生这种事情的，这种重传也是本库的特性之一。

对于每个请求的响应码你都可以根据 successStatuses和permanentErrors 配置项是否是认为成功或失败的：

• 200, 201, 202: 当前块上传成功，不需要重传。
• 404, 415. 500, 501: 当前块上传失败，会取消整个文件上传。
• 其他状态码: 出错了，但是会自动重试上传。

API 文档

uploadPlugin

配置

实例化的时候可以传入配置项：

var r = new uploadPlugin({ 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。
• uploadMethod 真正上传的时候使用的 HTTP 方法，可以是字符串或者函数，如果是函数的话，则会传入 Uploader.File 实例、当前块 Uploader.Chunk，默认 POST。
• allowDuplicateUploads 如果说一个文件以及上传过了是否还允许再次上传。默认的话如果已经上传了，除非你移除了否则是不会再次重新上传的，所以也就是默认值为 false。
• preprocess 可选的函数，每个块在测试以及上传前会被调用，参数就是当前上传块实例 Uploader.Chunk，注意在这个函数中你需要调用当前上传块实例的 preprocessFinished 方法，默认 null。
• changeRawDataBeforeSend 在可以为每个块发送 XHR 请求之前更改原始数据的可选函数。对于函数，它将块和数据作为参数传递。返回将发送到 XHR 请求的数据，无需进一步修改。（默认：）null
• initFileFn 可选函数用于初始化文件对象，传入的参数就是 Uploader.File 实例。
• readFileFn 可选的函数用于原始文件的读取操作，传入的参数就是 Uploader.File 实例、文件类型、开始字节位置 startByte，结束字节位置 endByte、以及当前块 Uploader.Chunk 实例。并且当完成后应该调用当前块实例的readFinished 方法，且带参数-已读取的 bytes。
• generateUniqueIdentifier 可覆盖默认的生成文件唯一标示的函数，默认 null。
• maxChunkRetries 最大自动失败重试上传次数，值可以是任意正整数，如果是 undefined 则代表无限次，默认 0。
• chunkRetryInterval 重试间隔，值可以是任意正整数，如果是 null 则代表立即重试，默认 null。
• progressCallbacksInterval 进度回调间隔，默认是 500。
• speedSmoothingFactor 主要用于计算平均速度，值就是从 0 到 1，如果是 1 那么上传的平均速度就等于当前上传速度，如果说长时间上传的话，建议设置为 0.02，这样剩余时间预估会更精确，这个参数是需要和 progressCallbacksInterval 一起调整的，默认是 0.1。
• successStatuses 认为响应式成功的响应码，默认 [200, 201, 202,'0']。
• permanentErrors 认为是出错的响应码，默认 [404, 415, 500, 501,'1']。

属性

• .support 当前浏览器是否支持 File API 来上传。
• .supportDirectory 当前浏览器是否支持文件夹上传。
• .opts 实例的配置项对象。
• .files 由 Uploader.File 文件对象组成的数组，纯文件列表。

方法

• .assignBrowse(domNodes, isDirectory, singleFile, attributes) 指定 DOM 元素可以选择上传。

  • domNodes DOM 元素
  • 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。

事件

• .fileSuccess(rootFile, file, message, chunk) 一个文件上传成功事件，第一个参数 rootFile 就是成功上传的文件所属的根 Uploader.File 对象，它应该包含或者等于成功上传文件；第二个参数 file 就是当前成功的 Uploader.File 对象本身；第三个参数就是 message 就是服务端响应内容，永远都是字符串；第四个参数 chunk 就是 Uploader.Chunk 实例，它就是该文件的最后一个块实例，如果你想得到请求响应码的话，chunk.xhr.status 就是。
• .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() 上传完毕。
• .progress() 上传进度。
• .error(message, file, chunk) 发生错误，包括文件错误。
• .catchAll(event, ...) 所有的事件。

Uploader.File

属性

• .flowObj 对父 flowObj 实例的引用。
• .file 原生 HTML5 File 对象。
• .name 文件（夹）名字。
• .relativePath 文件相对路径。
• .size 文件大小，单位字节。
• .uniqueIdentifier 文件唯一标示。
• .averageSpeed 平均速度，单位字节每秒。
• .currentSpeed 当前速度，单位字节每秒。
• .chunks 由 Uploader.Chunk 实例组成数组，分成的块集合，一般场景下并不需要关心它。
• .paused 文件是否是暂停的。
• .error 文件上传是否出错了。

如果不是文件夹的话，那么还会有如下属性：

方法

• .progress() 返回一个 0 到 1 的数字，代表当前上传进度。
• .pause() 暂停上传文件。
• .resume() 继续上传文件。
• .cancel() 取消上传且从文件列表中移除。
• .retry() 重新上传文件。
• .bootstrap() 重新初始化 Uploader.File 对象的状态，包括重新分块，重新创建新的 XMLHttpRequest 实例。
• .isUploading() 文件是否扔在上传中。
• .isComplete() 文件是否已经上传完成。
• .sizeUploaded() 已经上传大小。
• .timeRemaining() 剩余时间，基于平均速度的，如果说平均速度为 0，那么值就是 Number.POSITIVE_INFINITY。
• .getExtension() 得到小写的后缀。
• .getType() 得到文件类型。

源

hs-form-plugin 是 FORK 自 https://github.com/flowjs/flow.js