【uploader】表格化自整理vue-simple-uploader的文档（超详细）

轮子的github链接：两个项目的文档要结合着看才可以

# vue-simple-uploader
https://github.com/simple-uploader/vue-uploader/blob/master/README_zh-CN.md

# simple-uploader
https://github.com/simple-uploader/Uploader/blob/develop/README_zh-CN.md#%E9%85%8D%E7%BD%AE

具体使用建议看博客的另外两篇文章【uploader】

然后如果想要参考博主对该组件的使用的探索过程以及使用情况，可以查看主页中的uploader的几篇文章，那是简单记录自己对该组件的探索。

1.vue-simple-uploader介绍

超级强大的上传文件的前端vue组件，相比elementui的upload组件，其能满足绝大多数的文件上传需求。包括断续重传等常见业务。而elementui的upload组件很多功能都不能实现。但是两者可以相互兼容着使用。

• 支持文件、多文件、文件夹上传
• 支持拖拽文件、文件夹上传
• 可暂停、继续上传
• 支持断点续传、秒传
• 支持进度、预估剩余时间、出错自动重试、重传等操作
• 上传队列管理，支持最大并发上传，支持分块上传

为了方便查看，这里copy一下quickstart代码，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: {
      
      
          // https://github.com/simple-uploader/Uploader/tree/develop/samples/Node.js
          target: '//localhost:3000/upload',
          testChunks: false
        },
        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>

2.安装和配置

npm install vue-simple-uploader --save

# 在main.js中
import uploader from 'vue-simple-uploader'
Vue.use(uploader)

3. 组件标签的文档整理

一共有如下几个标签：

• uploader

• uploader-btn

• uploader-drop

• uploader-list

• uploader-file

3.1 uploader标签

根组件标签，可理解为一个上传器

Props属性：

参数	说明	类型	可选值	默认
options	最重要的配置项，读取配置项后建立上传器	Object	-	{}
autoStart	是否选择后就立即自动上传	boolean	true/false	true
fileStatusText	根据服务端返回的状态码做出反应，默认即可	Object	-	{ success: ‘success’, error: ‘error’, uploading: ‘uploading’, paused: ‘paused’, waiting: ‘waiting’ }

补充options的可配置项【常用的优先，△标记为重要，其他没写的都是默认为最优】：

参数	说明	类型	可选值	默认
△target	目标上传的url，必填	String	-	‘/’
△singleFile	单文件上传，如果设置了true，则选择多个文件的时候，只有最后一个会被上传	boolean	true/false	false
△chunkSize	分块，单个数据块的值大小，用于分块上传实现断续重传	number	-	1*1024*1024【1Mb】
forceChunkSize	是否强制所有的块都一定小于等于chunkSize	boolean	-	false
△simultaneousUploads	并发上传数	number	-	3
fileParameterName	上传文件的时候文件的参数名，默认是multipart上传，参数名默认是file	String	-	“file”
△query	请求url时候携带的其他参数	json	-	{}
headers	设置请求头信息	json	-	{}
△withCredentials	标准的CORS请求是不会带上cookie的，如果想要带上需要设置为true	boolean	true/false	false
method	当前上传文件使用的方式，默认与form表单一样multipart	String	multipart/octet	“multipart”
testMethod	测试接口的时候使用的HTTP方法	String	“GET”/“POST”	默认"GET"
△uploadMethod	真正上传的时候使用的 HTTP 方法	String	“GET”/“POST”	默认"POST"
prioritizeFirstAndLastChunk	对于文件而言是否高优先级发送第一个和最后一个块。一般用来发送到服务端，然后判断是否是合法文件；例如图片或者视频的 meta 数据一般放在文件第一部分，这样可以根据第一个块就能知道是否支持	boolean	true/false	false
△testChunks	是否测试每个块是否在服务端已经上传了，主要用来实现秒传、跨浏览器上传等【一般默认】	boolean	true/false	true
△checkChunkUploadedByResponse	值为一个函数，不可以直接编写函数。是服务器分片校验函数，与上方的testChunks共用，是秒传和断点续传的基础。根据结果返回的响应体参数判断，return true或者false	函数
maxChunkRetries	最大重试次数	number	-	0
chunkRetryInterval	重试间隔，null表示立即重试	number	-	null
△processParams	直接在options对象中编写名为processParams函数即可。自定义每一次分片传给后台的参数，params是该方法返回的形参，包含分片信息。实际情况根据接口约定调整，返回一个json对象	函数

Slot事件：

name	说明
file-added(file)	添加了一个文件的事件，一般用作文件校验
files-added(files, fileList)	添加了一批文件事件，一般用做一次选择的多个文件进行校验
file-success(rootFile, file, message, chunk)	文件成功上传，第一个参数rootFile是或包含File对象，file是File对象，message是服务端响应内容字符串，chunk是chunk实例，应该是本文件最后一个块实例。chunk.xhr.status就是这个文件上传的响应码
file-progress(rootFile, file, chunk)	一个文件正在上传事件
file-removed(file)	一个文件被移除
file-error(rootFile, file, message, chunk)	文件上传过程出错

methods方法：

需要得到uploader实例

# 我们先给uploader标签指定ref
<uploader :options="options" class="uploader-example" ref="uploader">
# 然后可以从当前vue组件的子组件refs列表里获取uploader组件，uploader组件有个uploader属性表示uploader组件本身
const uploaderInstance = this.$refs.uploader.uploader
# 然后实例.方法就可以使用了

方法	说明
upload()	开始或者继续上传
pause()	暂停上传
resume()	继续上传
progress()	返回一个0-1的浮点数，表示当前上传进度
isUploading()	返回一个布尔值标示是否还有文件正在上传中
cancel()	文件会被移除掉
addFile(file)	添加一个原生的文件对象到上传列表中
removeFile(file)	从上传列表中移除一个指定的 Uploader.File 实例对象
getSize()	上传文件的总大小
timeRemaining()	剩余时间，单位秒；这个是基于平均上传速度计算出来的，如果说上传速度为 0，那么这个值就是 Number.POSITIVE_INFINITY
on(event, callback)	监听各种事件

3.2 uploader-btn标签

点击后能够展示文件选择器的按钮。一般就只使用directory参数

props属性：

参数	说明	类型	可选值	默认
directory	表示当前上传是否是文件夹上传，如果true则只能选择文件夹	boolean	true/false	false
single	表示是否一次只能选择一个文件，如果false则可以多选	boolean	true/false	false
attrs	添加到input元素上的额外属性。因为文件上传的本质是一个input文档对象，比如input元素有的accept="image/*"表示只允许图片上传	json object	accept等	{}

3.3 uploader-drop标签

声明该区域允许拖动文件进来后上传

3.4 uploader-list标签

一个列表外标签，类似于form一样，仅仅是用来装载uploader-file组件的容器。
下面有使用演示

3.5 uploader-file标签

就是你拉取后的一个文件单位对象，可以展示，拥有自己的很多属性可以展示。

Props属性：

参数	说明	类型	可选值	默认
file	file实例本身	Uploader.File	-	-
list	如果在UploaderList使用，设置为true	boolean		false

slot插槽：就是通过file对象能直接的file信息

参数	说明	类型
file	文件实例	Uploader.File
list	是否在 UploaderList 组件中使用	boolean
status	当前状态【success，error，uploading，paused，waiting】	String
paused	是否暂停了	boolean
error	是否出错了	boolean
averageSpeed	平均上传速度，单位字节每秒	number
formatedAverageSpeed	格式化后的平均上传速度类似：3 KB / S	String
currentSpeed	当前上传速度	number
isComplete	是否已经上传完成	boolean
isUploading	是否在上传中	boolean
size	文件或者文件夹大小	number
formatedSize	格式化后文件或者文件夹大小，类似：10 KB	number
uploadedSize	已经上传大小，单位字节	number
progress	介于 0 到 1 之间的小数，上传进度	number
progressStyle	进度样式，transform 属性，类似：{transform: '-50%'}	String
progressingClass	正在上传中的时候值为：uploader-file-progressing	String
timeRemaining	预估剩余时间，单位秒	number
formatedTimeRemaining	格式化后剩余时间，类似：3 miniutes	String
type	文件类型	String
extension	文件名后缀，小写	String
fileCategory	文件分类，其中之一：folder, document, video, audio, image, unknown	String

简单演示一下list和file的使用，用于可视化文件上传进度

• uploader设置自动上传为false: `autoStart=“false”
• 在uploader内引入uploader-list
• 通过slot-scope绑定文件实例，选择文件后自动传递实例
• v-for展示uploader-file即可，file实例的属性、方法和事件看上方文档，自己设计可视化即可

<uploader 
	:options="this.options" 
	@file-added="this.fileAdded" 
	@file-error="this.fileError" 
	@file-success="this.fileSuccess" 
	:autoStart="false">
	<uploader-unsupport></uploader-unsupport>
	<uploader-btn class="uploader-btn">点击上传</uploader-btn>
	 
	<uploader-list>
		<!--通过slot-scope绑定文件实例-->
	     <div slot-scope="props">
	         <div v-for="(file,i) in props.fileList" :key="i">
	             <uploader-file :list="true" :file="file"></uploader-file>
	         </div>
	     </div>
	 </uploader-list>
</uploader>

原生的效果长这样。

3.6 uploader-unsopport标签

不支持 HTML5 File API 的时候会显示。

一般就写在uploader根组件里就行了，遇到低版本的浏览器不兼容组件的时候才会展示。

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

4.请求中的参数

可通过 query 参数配置扩充，也可以通过 processParams 自定义

• chunkNumber，当前分片
• chunkSize，分片上限大小
• currentChunkSize，当前分片的真实大小
• totalSize，文件总大小
• identifier，唯一标识，可自定义
• filename，文件名
• totalChunks，总分片数量
• 从totalChunks往下，是自己在options配置中配置的query参数，比如我配置了curUrl这个参数

然后如果想要参考博主对该组件的使用的探索过程以及使用情况，可以查看主页中的uploader的几篇文章，那是简单记录自己对该组件的探索。