myfileupload 文件上传
myfileupload是一个简单的兼容node与web的现代文件上传库。两套运行时,同样的调用方式,可供用户任意选用。node端通过 支持分片多并发上传,可暂停继续、分块上传、出错手传、同步进度、等特性;该上传库web端依赖 HTML5 File API。所以受限于此浏览器支持程度为:Firefox 4+, Chrome 6+, Safari 6+ and Internet Explorer 10+。
安装
可使用 npm:
npm install myfileupload.js
或者直接 git clone:
git clone git@gitlab.gz.cvte.cn:wangxin1420/fileupload.git
特性
分片、并发
分片与并发结合,将一个大文件分割成多块,并发上传,极大地提高大文件的上传速度。
自动识别兼容web与node
接口一致,实现了两套运行时支持,用户无需关心内部。
断点续传
当网络问题导致传输错误时,只需要重传出错分片,而不是整个文件。另外分片传输能够更加实时的跟踪上传进度。
队列控制
支持多文件并发上传,控制优先上传顺序
使用
- 引入fileUpload库
import fileUpload from 'myfileupload'
- 创建一个
fileUpload
实例:
files为原生html5传入的file对象数组
var uploader= files action:'https://airdisk-cvte-test.test.maxhub.vip/api/client/files'
- 实例化后你还可以选择监听一些事件:
// 文件上传中uploader// 单个文件上传成功uploader// 某个文件上传失败了uploader
demo
- 下载本模块,
npm install
配置下载链接和头部信息,然后npm start
,进行文件上传demo - 考虑都此模块是配合electron+react使用,
./example/reactDemo.js
为一个文件上传的demo,可直接复制此文件到你的react项目中使用
API 文档
Uploader
配置
实例化的时候可以传入配置项:
var r = opt1: 'val' ...
支持的配置项:
见 lib
文件下的config.js
-
action
目标上传 URL,字符串。 -
method
上传文件的请求方法 -
largeFileSize
判定上传文件属于大文件的大小,开启分片上传,默认为5 *1024 * 1024
, -
chunked
是否要分片处理大文件上传,默认`true -
chunkSize
分块时按照该值来分。最后一个上传块的大小是可能是大于等于1倍的这个值但是小于两倍的这个值大小,默认2*1024*1024
(2M)。 -
threads
,上传并发数。允许同时最大上传进程数,默认为3
-
timeout
请求超时时间,默认为10000(10s) -
webUpload
,强制选择web端处理大文件分片上传。默认为false
,支持node端时默认使用node处理文件 -
download
,文件上传成功需要返回下载信息的话,两个必需参数action
:下载链接action跟下载请求的method
。默认为download:{ action:'', method:'get' }
-
statusText
文件上传状态对应的文字说明,默认为,如果要修改,文件全部
状态都要配置,不能单独配置某个状态statusText = { inited:'初始化', queued:'等待上传', uploading:'上传中', error:'出错了', complete:'已发送完分片', cancelled:'已取消', success:'上传成功', interrupt:'已暂停', }
属性
.fileList
文件对象组成的数组。.options
实例的配置项对象._events
实例订阅的事件
方法
-
.on(event, callback)
监听事件。`onProcess`uploader监听文件上传进度,返回file与percentage(0-100)在这里可以更新文件状态,因为对应file属性percentage已经改变`onSuccess`uploader监听文件上传成功,当有文件上传成功就返回file文件信息,res成功上传的分片信息,如果配置有下载链接,就有download下载信息`onError`uploader监听文件上传失败,当有文件上传失败就返回失败的file文件信息,res成功失败的信息 -
.off([event, [callback]])
:
.off(event)
移除指定事件的所有事件回调
.off(event, callback)
移除指定事件的指定回调。callback
是一个函数
.upload()
开始上传。.addFiles(files,index)
添加原生的文件对象一个或多个到上传列表中。后面参数即插入列表的位置,不写,则默认为插入队列末尾
Uploader.File
属性
原生 HTML5 File
对象属性和添加的属性。
-
.name
文件(夹)名字。 -
.percentage
文件的上传进度(0-100)。 -
.status
文件的状态。INITED: "inited", // 初始状态 QUEUED: "queued", // 已经进入队列, 等待上传 UPLOADING: "uploading", // 上传中 ERROR: "error", // 上传出错,可重试 COMPLETE: "complete", // 上传完成(大文件的分片数据都已发送,还没全部成功返回)。 CANCELLED: "cancelled", // 上传取消。 SUCCESS: "success",//上传成功 INTERRUPT: "interrupt" // 上传中断,可续传。
-
.size
文件大小,单位字节。 -
.uid
文件唯一标示。 -
.uploadedChunk
大文件的上传成功的分片集合,例如大文件分成5片,成功上传了[0,1,2]片 -
.showProgress
用于是否显示文件上传进度,当取消,成功,失败为false
方法
-
.pause(file)
控制某个文件暂停上传 -
.resume(file)
继续某个文件上传 -
.cancel(file)
取消上传文件 -
.retry(file)
控制某个文件重新上传
.remove(file)
删除某个文件,并移出文件列表
接口文档
服务端
经过ApiProxy
的 资源系统
通用header
Authorization: "Basic " + Buffer.from("maxhub:maxhub@123").toString("base64"),
x-company-id: companyId,
x-access-token: userToken,
X-APM-TraceId: traceId,
分大文件和小文件,
文件分俩 | 大小 | 分块大小 |
---|---|---|
大文件 | 5M以上 | 2M |
小文件 | 5M以下 包括5M | 不分块 |
小文件
上传接口:${apiproxy}/${namepsace}/api/client/files
body参数
name: name, // 文件名
file: fileStream // 文件流,文件二进制
contentType: FileExt // 文件尾缀,eg: jpg
totalTransactionSize: size // 文件大小
response (直接返回小文件的信息)
{
id: string;
name: string;
size: number;
contentType: string;
downloadUrl: string;
mhb: boolean;
createdDate: number;
isTransient: boolean;
}
大文件
- 启动大文件上传接口:
${apiproxy}/${namepsace}/api/client/files
body参数
name: fileName // 文件名
bigFile: true // 启动大文件
contentType: fileExt // 文件类型
totalTransactionSize: size // 文件大小
autoCommit: false // 不自动提交,固定参数
response
{
id: 'fileId' // 文件ID
xxx // 额外信息
}
- 上传文件分块 :
${apiproxy}/${namepsace}/api/client/files/${fileId}
额外headers
"Content-Type": "application/octet-stream" // 固定header
"x-chunks": chunkNum, // 文件分块数量
"x-chunk": index, // 第几个文件分块,从 1开始
"x-chunk-md5": md5, // 文件分块md5
"x-total-length": size, // 文件总大小
"x-part-length": partSize // 文件分块大小
body 参数
// 就是文件buffer 或者stream,或者binary
response
// 忽略
- 获取大文件信息
请求接口:${apiproxy}/${namepsace}/api/pub/files/${fileId}
response
{
itemId: string;
name: string;
createdDate: number;
contentType: string;
duration: number;
text: null | string;
size: number;
downloadUrl: string;
viewCounter: number;
indexOf: number;
author: null | string;
deviceName: null | string;
favorite: boolean;
parentId: null | string;
parentName: null | string;
thumbnail: null | string;
items: any[];
storeKey: string;
isDirectory: boolean;
}
错误信息返回
{code: 4031000, message: "file has upload done!"}
这个表示分片信息已经上传成功,然后重复上传报的错
备注
项目目录的post文件夹下有web(浏览器主线程处理分片上传请求)与web2
(在worker发分片上传请求)两种方案,用户只需在post/node更改对应方案的项目文件夹就行