使用 TypeScript 实现大文件分片上传
npm i big-upload -S
基本使用方法:
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()
}
参数 | 说明 | 类型 | 默认值 |
---|---|---|---|
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 |
字段 | 说明 | 类型 |
---|---|---|
name |
文件名称 | string |
size |
文件大小 | number |
hash |
文件生成唯一的 md5 值 | string |
totalCount |
文件可分片个数 | number |
index |
当前上传分片文件的索引值 | number |
file |
当前上传的分片文件,可通过 config.name 设置上传的文件字段名 |
file / blob |
currentSize |
当前上传的分片文件大小 | number |
currentHash |
当前上传的分片文件生成唯一的 md5 值 | string |
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
}
*/
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
}
*/
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
},
...
]
*/
方法 | 说明 | 参数 |
---|---|---|
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()
}