Big-upload NPM

big-upload

使用 TypeScript 实现大文件分片上传

使用

基本使用方法:

import upload from 'big-upload'

// upload(el: string | element, action: string, config?: object)
upload('#el', '/upload')

// 或者

// upload(config: object)
upload({
  el: '#el',
  action: '/upload'
})

如果你不需在选取文件后立即进行上传，而是点击按钮上传，你应当使用 .submit():

import upload from 'big-upload'

const ul = upload({
  el: '#el',
  action: '/upload',
  autoUpload: false
})

document.querySelector('#btn').onclick = () => {
  ul.submit()
}

API

config 配置

参数	说明	类型	默认值
`el`	必选参数，绑定元素	string / element	--
`action`	必选参数，上传的地址	string	--
`data`	上传时附带的额外参数	object	--
`params`	url地址参数	object / URLSearchParams	--
`name`	上传的文件字段名	string	`file`
`chunkSize`	设置每个文件分片大小	number	`1 * 1024 * 1024`
`multiple`	是否支持多选文件	boolean	`false`
`accept`	接受上传的文件类型	string	--
`autoUpload`	是否在选取文件后立即进行上传	boolean	`true`
`withCredentials`	支持发送 cookie 凭证信息	boolean	`false`
`headers`	设置上传的请求头部	object	--
`timeout`	设置超时时间	number	`0`
`httpRequest`	覆盖默认的上传行为，可以自定义上传的实现	function	--
`onChange`	选择文件后钩子	function(fileData[])	--
`onBeforeUpload`	上传文件之前的钩子，参数为上传的文件，若返回 false 或者返回 Promise.resolve(false)，则停止上传	function(fileData)	--
`onBeforeSliceFileUpload`	上传分片文件之前的钩子，参数为上传的分片文件，若返回 false 或者返回 Promise.resolve(false)，则停止上传（表示该分片文件已上传成过，无需再上传）	function(fileData)	--
`onProgress`	文件上传时的钩子	function(progressData)	--
`onSuccess`	单个文件上传成功时的钩子（表示该文件的所有分片文件已全部上传成功）	function(response[], fileData, file)	--
`onComplete`	所有文件上传成功时的钩子（表示所有文件的所有分片文件已全部上传成功）	function(responseList, fileData[], file[])	--
`onError`	分片文件上传失败时的钩子	function(err, sliceFile, file)	--
`isLocalRecord`	是否开启本地上传记录，开启后每上传完一个分片文件时，会在 `localStorage` 中记录，直到当前文件的所有分片文件全部上传完毕，删除当前记录	boolean	false
`localRecordTime`	开启本地上传记录后，设置保存每个文件的记录时长为多少天	number	15 天
`onLocalRecord`	开启本地上传记录后，当上传文件的分片文件时，命中本地上传记录，不需要再上传前调用该钩子，若返回 false 或者返回 Promise.resolve(false)，则停止上传（表示该分片文件已上传成过，无需再上传）	function(fileData)	--
`isAddUp`	是否开启叠加文件，当设置 `config.autoUpload` 为 `false` 并开启此选项时，选择的文件会进行叠加，并在 `onChange` 钩子中返回所有叠加文件（如果选择文件的文件名一样时，会保留第一个选择的文件，因为要以文件名和内容生成唯一的 md5 值）	boolean	false

requestData: object （上传分片文件时，默认请求入参）

字段	说明	类型
`name`	文件名称	string
`size`	文件大小	number
`hash`	文件生成唯一的 md5 值	string
`totalCount`	文件可分片个数	number
`index`	当前上传分片文件的索引值	number
`file`	当前上传的分片文件，可通过 `config.name` 设置上传的文件字段名	file / blob
`currentSize`	当前上传的分片文件大小	number
`currentHash`	当前上传的分片文件生成唯一的 md5 值	string

钩子参数说明

fileData: object

name	说明	类型
`name`	文件名称	string
`size`	文件大小	number
`file`	上传文件	file
`hash`	文件生成唯一的 md5 值	string
`totalCount`	文件可分片个数	number
`index`	当前上传分片文件的索引值	number
`currentFile`	当前上传的分片文件	file / blob
`currentSize`	当前上传的分片文件大小	number
`currentHash`	当前上传的分片文件生成唯一的 md5 值	string

import upload from 'big-upload'

upload({
  el: '#el'
  action: '/upload',
  onBeforeUpload(fileData) {
    console.log(fileData)
  }
})

/* `xx?` 参数是针对分片文件内容，所以在 `onChange`、`onBeforeUpload` 钩子中不会有此参数
fileData: {
  name: string,
  size: number,
  file: file,
  hash: string,
  totalCount: number,
  index?: number,
  currentFile?: file / blob,
  currentSize?: number,
  currentHash?: string
}
*/

progressData: object

name	说明	类型
`name`	文件名称	string
`size`	文件大小	number
`file`	上传文件	file
`hash`	文件生成唯一的 md5 值	string
`totalCount`	文件可分片个数	number
`index`	当前上传分片文件的索引值	number
`currentFile`	当前上传的分片文件	file / blob
`currentSize`	当前上传的分片文件大小	number
`currentHash`	当前上传的分片文件生成唯一的 md5 值	string
`loaded`	当前上传的分片文件，已上传的大小	number
`total`	当前上传的分片文件，需要上传的总共大小	number
`percent`	文件的上传进度	number

import upload from 'big-upload'

upload({
  el: '#el'
  action: '/upload',
  onProgress(progressData) {
    console.log(progressData)
  }
})

/*
progressData: {
  name: string,
  size: number,
  file: file,
  hash: string,
  totalCount: number,
  index: number,
  currentFile: file / blob,
  currentSize: number,
  currentHash: string,
  loaded: number,
  total: number,
  percent: number
}
*/

response: object

name	说明	类型
`data`	接口返回的响应数据	object / any
`status`	响应状态码	number
`statusText`	响应状态文字	string
`headers`	响应头	object
`config`	传入的 `config` 配置	object
`request`	XMLHttpRequest 请求	object

import upload from 'big-upload'

upload({
  el: '#el'
  action: '/upload',
  onSuccess(response, fileData, file) {
    console.log(response)
  }
})

/* 返回多个分片文件的响应报文集合(分片文件的上传个数是根据上传文件的大小，和设置 `config.chunkSize` 的大小计算而得出结果)
response: [
  {
    data: object / any,
    status: number,
    statusText: string,
    headers: object,
    config: object,
    request: object
  },
  ...
]
*/

Methods

方法	说明	参数
`submit`	上传已选中的文件	--
`abort`	取消文件上传请求	(val: 可以是 file 文件，或者是 hash 文件生成唯一的 md5 值)
`remove`	删除已选中的文件	(val: 可以是 file 文件，或者是 hash 文件生成唯一的 md5 值)
`disabled`	是否禁用	(val?: 不传值为禁用；传 true 为禁用；传 false 为不禁用)

import upload from 'big-upload'

let fileDataList

const ul = upload({
  el: '#el',
  action: '/upload',
  autoUpload: false,
  onChange(fileData) {
    fileDataList = fileData
  }
})

document.querySelector('#btnSubmit').onclick = () => {
  ul.submit()
}

document.querySelector('#btnAbort').onclick = () => {
  if(fileDataList && fileDataList.length) {
    ul.abort(fileDataList[0].hash)
    fileDataList.shift()
  }
}

document.querySelector('#btnRemove').onclick = () => {
  if(fileDataList && fileDataList.length) {
    ul.remove(fileDataList[0].hash)
    fileDataList.shift()
  }
}

document.querySelector('#btnDisabled').onclick = () => {
  ul.disabled()
}

@types/spark-md5 spark-md5

@everything-registry/sub-chunk-1233 @zalastax/nolb-big

0.1.0

4 years ago

0.0.1

4 years ago