# 简介

vue-simple-uploader 是基于 simple-uploader.js 和 Vue 结合做的一个上传组件，自带 UI，可覆盖、自定义。它支持文件、多文件、文件夹上传；支持拖拽文件、文件夹上传；可暂停、继续上传；支持秒传；上传队列管理，支持最大并发上传；分片上传；支持进度、预估剩余时间、出错自动重试、重传等操作。

# 配置

# 安装：

npm install vue-simple-uploader --save

# 初始化，在 main.js 中添加如下代码：

import Vue from 'vue'

import uploader from 'vue-simple-uploader'

import App from './App.vue'Vue.use(uploader)

# 使用

<template>

  <uploader :options="options" class="uploader-example">

    <uploader-unsupport></uploader-unsupport>

    <uploader-drop>

      <p>Drop files here to upload or</p>

      <uploader-btn>select files</uploader-btn>

      <uploader-btn :attrs="attrs">select images</uploader-btn>

      <uploader-btn :directory="true">select folder</uploader-btn>

    </uploader-drop>

    <uploader-list></uploader-list>

  </uploader>

</template>

<script>

  export default {

    data () {

      return {

        options: {

          target: 'http://localhost:9000/upload',

          testChunks: false,

          chunkSize: 1024*1024*2,  //1MB

          simultaneousUploads: 3, //并发上传数

          headers: {

                'access-token': 'abcd1234'

          },

          query ：{

                 code : 123

          }

        },

        attrs: {

          accept: 'image/*'

        }

      }

    }

  }

</script>

<style>

  .uploader-example {

    width: 880px;

    padding: 15px;

    margin: 40px auto 0;

    font-size: 12px;

    box-shadow: 0 0 10px rgba(0, 0, 0, .4);

  }

  .uploader-example .uploader-btn {

    margin-right: 4px;

  }

  .uploader-example .uploader-list {

    max-height: 440px;

    overflow: auto;

    overflow-x: hidden;

    overflow-y: auto;

  }

</style>

# 传递参数

插件使用时，上传请求都会包含如下分块信息：

• chunkNumber : 当前块的次序，第一个块是 1，注意不是从 0 开始的。
• totalChunks : 文件被分成块的总数。
• chunkSize : 分块大小，根据 totalSize 和这个值你就可以计算出总共的块数。注意最后一块的大小可能会比这个要大。
• currentChunkSize : 当前块的大小，实际大小。
• totalSize : 文件总大小。
• identifier : 这个就是每个文件的唯一标示。
• filename : 文件名。
• relativePath : 文件夹上传的时候文件的相对路径属性。

后端可根据传递的信息自由处理；一般是一个文件表一个文件夹表做关联。

# 状态码

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

# 配置项

由于是对原 simple-upload.js 做的封装，大多数的配置可以参考原生 js 文档，部分配置与原生有些许不同，请注意仔细查看相关参考文档。

• target ：目标上传地址 URL，默认值为 '/'。
• chunkSize ：分片时按照该值来分。最后一个上传分片的大小是可能是大于等于 1 倍的这个值但是小于两倍的这个值大小
• simultaneousUploads ：并发上传数，默认 3。
• fileParameterName ：上传文件时文件的参数名，默认 file。
• headers ：额外的一些请求头，例如有时我们需要在 header 中向后台传递 token，默认为对象: {}。
• maxChunkRetries ：最大自动失败重试上传次数，值可以是任意正整数，如果是 undefined 则代表无限次，默认 0。
• chunkRetryInterval ：重试间隔，值可以是任意正整数，如果是 null 则代表立即重试，默认 null。
• parseTimeRemaining(timeRemaining, parsedTimeRemaining) {Function} ：格式化剩余时间。以下代码把英文时间转成中文：

parseTimeRemaining: function (timeRemaining, parsedTimeRemaining) {

  return parsedTimeRemaining

    .replace(/\syears?/, '年')

    .replace(/\days?/, '天')

    .replace(/\shours?/, '小时')

    .replace(/\sminutes?/, '分钟')

    .replace(/\sseconds?/, '秒')

}

# 属性

• autoStart {Boolean} ：默认 true, 是否选择文件后自动开始上传。
• fileStatusText {Object} ：文件状态，文件在上传时会响应几种状态:

{

  success: 'success',

  error: 'error',

  uploading: 'uploading',

  paused: 'paused',

  waiting: 'waiting',

}

# 事件

• fileAdded(file) ：添加了一个文件事件，一般用做文件校验，比如要校验文件 md5 时，先触发该事件。 可以当作上传前的钩子，校验文件类型、大小或者数量限制等
• fileSuccess(rootFile, file, message, chunk) ：一个文件上传成功事件，第一个参数 rootFile 就是成功上传的文件所属的根 Uploader.File 对象，它应该包含或者等于成功上传文件；第二个参数 file 就是当前成功的 Uploader.File 对象本身；第三个参数就是 message 就是服务端响应内容，永远都是字符串；第四个参数 chunk 就是 Uploader.Chunk 实例，它就是该文件的最后一个块实例，如果你想得到请求响应码的话，chunk.xhr.status 就是。
• fileError(rootFile, file, message, chunk) ：上传出错。
• fileProgress(rootFile, file, chunk) ：一个文件在上传中，监听文件上传进度。
• fileRemoved(rootFile, file) ：从上传列表移除文件。

注意：所有的事件都会通过 lodash.kebabCase 做转换，例如 fileSuccess 就会变成 file-success 。

方法绑定的使用：

<uploader

   ref="uploader" 

   class="avatar-uploader"

   :options="options" 

   :file-status-text="statusText" 

   @file-added="onFileAdded" 

   @file-success="onFileSuccess" 

   @file-progress="onFileProgress" 

   @file-error="onFileError" 

   @file-removed="fileRemoved"

>

#

# Uploader.File 获取实例

mounted () {

       this.$nextTick(() => {

         window.uploader = this.$refs.uploader.uploader

       })

 }

// 实例的调用：

window.uploader.cancel()

• .assignBrowse(domNodes, isDirectory, singleFile, attributes) 指定 DOM 元素可以选择上传。（用于实现自定义上传文件 / 文件夹按钮，由于使用的框架自带主题颜色更换，如果使用默认按钮无法与框架主题色兼容，所以获取 dom 后调用此实例方法使自定义的按钮也具备上传能力，下方拖拽区域同理）

• domNodes DOM 元素

• isDirectory 如果传入的是 true 则代表是要选择文件夹上传的，你可以通过判断 supportDirectory 来决定是否设置

• singleFile 是否只能选择单个文件

• attributes 传入的其他属性值，例如你可以传入 accept 属性的值为 image/* ，这样就意味着点选的时候只能选择图片。

  • 注意：避免使用 a 或者 button 标签作为选择文件按钮。

• .assignDrop(domNodes) 指定 DOM 元素作为拖拽上传目标。

• .unAssignDrop(domNodes) 取消指定的 DOM 元素作为拖拽上传目标。

• .getRoot() 获取当前文件所属的根文件，这个根文件就是包含在 uploader.fileList 中的.

• .progress() 返回一个 0 到 1 的数字，代表当前上传进度。

• .pause() 暂停上传文件。

• .resume() 继续上传文件。

• .cancel() 取消上传且从文件列表中移除。

• .retry() 重新上传文件。

• .bootstrap( ) 重新初始化 Uploader.File 对象的状态，包括重新分块，重新创建新的 XMLHttpRequest 实例。

• .isUploading() 文件是否仍在上传中。

• .isComplete() 文件是否已经上传完成。

• .sizeUploaded() 已经上传大小。

• .timeRemaining() 剩余时间，基于平均速度的，如果说平均速度为 0，那么值就是 Number.POSITIVE_INFINITY 。

• .getExtension() 获取小写的后缀。

• .getType() 获取文件类型。

# 开发遇到的问题

1、上传文件夹的大致原理本质上还是上传的文件，只是文件被带上了文件夹相关的路径，空文件夹是无法发起请求的，如需完成新建空文件夹的操作需要单独调用新建文件夹接口完成一个对文件夹表的新增操作。

2、当上传文件夹时，若文件夹包含子文件夹的情况，由于上传是异步的，有可能导致上传的文件夹结构异常或上传失败，需要做同步处理，前端有一个并发上传数的配置应该是前端的同步配置，但是存在部分问题待解决，时间原因，拜托后端对这个上传做了同步处理解决的。

3、并发上传数问题，默认给了 3 个，并发数量改为 1 就会变成同步上传，一个一个上传，按理前端的同步处理就是对这个参数做设置。但是在上传列表中不会结束已完成的上传任务，导致一直卡在第一个任务，我是自己手动去移除已完成的任务来解决的这个问题。这个问题自己根据业务调整吧。

4、默认的上传列表会随着上传文件的增多自动撑高，影响了页面的其他内容，做了一套显隐处理：存在上传任务时会出现一个上传中的图标，需要点击图标才会出现这个脱标的上传进度框，任务完成后自动清除文件列表，解除上传中状态。

# API 文档具体配置项如下：

• 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)。

方法：

• .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 。

事件：

• .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, ...) 所有的事件。