uploadcore
v2.3.3
Published
upload core
Downloads
103
Readme
UploadCore
特性一览
- md5(用于秒传)
- 分片上传
- html5-runtime,flash-runtime
- 多种收集器Collector(DndCollector、PasteCollector、PickerCollector)
- 拥抱es6
Usage 最佳实践
import {UploadCore, Events, Status, VERSION} from 'uploadcore';
console.log('UploadCore version %s', VERSION);
const up = new UploadCore({
name: 'file',
url: 'http://test.yanbingbing.com/upload.php'
});
up.on(Events.FILE_UPLOAD_COMPLETED, (file) => {
if (file.getStatus() === Status.SUCCESS) {
alert('上传成功');
console.info(file.response.getJson());
} else {
alert('上传失败');
}
});
const picker = up.getPickerCollector();
picker.addArea(document.getElementById('clickarea'));
Compatible 兼容处理
完全的功能仅在最新的Chrome浏览器中支持,对于不支持的浏览器,在保证上传功能可用的情况下,采用不支持或降低处理。
特性支持一览
Feature | Chrome | Firefox | Safari | Edage | IE11 | IE10 | IE9-
-------- | ------ | ------- | ------ | ----- | ---- | ---- | ----
基本上传 | html5 | html5 | html5 | html5 | html5 | html5 | flash
复制系统文件上传 | 支持
| 不支持
| 有问题
| 不支持
| 不支持
| 不支持
| 不支持
复制网页图像上传 | 支持
| 不支持
| 不支持
| 支持
| 不支持
| 不支持
| 不支持
截图上传 | 支持
| 不支持
| 不支持
| 支持
| 部分支持
| 不支持
| 不支持
拖拽上传 | 目录和文件
| 文件
| 文件
| 不支持
| 文件
| 文件
| 不支持
秒传 | 支持
| 支持
| 支持
| 支持
| 支持
| 支持
| 不支持
分片上传 | 支持
| 支持
| 支持
| 支持
| 支持
| 支持
| 不支持
如果要保证能在所有浏览器中运行,我们需要引入es5-shim相关ployfill脚本。
<script src="/path/to/es-shim.min.js"></script>
<script src="/path/to/es-sham.min.js"></script>
Options 配置
options = {
// 上传文件字段名称
name: 'file',
// 上传目标
url: 'http://demo.com/rest/1.0/file',
// 上传文件额外参数
params: {},
// 上传文件额外头, `flash下不支持`
headers: [],
// 上传文件是否自动附带cookie等信息, `flash下不支持`
withCredentials: false,
// 上传超时
timeout: 0,
// 是否允许分片上传, `flash下不支持`
chunkEnable: false,
// 文件分片大小, 默认单位b,0不分片
chunkSize: 0,
// 文件分片上传重试次数
chunkRetries: 0,
// 分片上传并发数
chunkProcessThreads: 2
// 文件上传并发数
processThreads: 2,
// 是否选择后自动等待上传
autoPending: true,
// 队列容量,0无限
queueCapcity: 0,
// 是否多选
multiple: true,
// 允许文件类型
accept: null,
// 文件大小限制
fileSizeLimit: 0,
// 是否防止文件重复
preventDuplicate: false,
// 过滤器
filters:[]
}
options.params
上传文件额外参数,支持俩种赋值方式
// 赋值一(Object)
params = {
foo: 'bar'
}
// 赋值二(Array)
params = [
{name:'foo', value:'bar'}
]
options.headers
上传文件请求头,格式如下:
headers = [
{name:'X-Requested-With', value:'XMLHttpRequest'}
]
options.chunkSize
文件分片大小,默认单位byte,默认0,小于256K时,不可分片。
允许b,k,m,g,t
为单位(大小写不敏感)结尾的string
或者int
。
size = 1; // 1字节
size = '1b'; // 1字节
size = '1k'; // 1千字节 = 1024b
size = '1m'; // 1兆字节 = 1024k
size = '1g'; // 1吉字节 = 1024m
size = '1t'; // 1太字节 = 1024g
options.fileSizeLimit
文件大小限制,默认单位byte,默认0,表示不限制,格式同options.chunkSize
。
options.accept
允许文件格式,推荐赋值方式如下:
accept = {
title: '图片',
extensions: 'jpg,jpeg,png,gif,webp,bmp'
};
如果你觉的有必要,也可以设置一下mimeTypes
accept = {
title: '图片',
extensions: 'jpg,jpeg,png,gif,webp,bmp',
mimeTypes: 'image/*' // or 'image/jpeg,image/png'
};
mimetypes设置后在不同浏览器中会表现不一致,谨慎使用
如果觉得不需要那么麻烦,accept也可以更简单
accept = 'jpg,jpeg,png,gif,webp,bmp';
甚至可以
accept = 'images';
accept = 'audios';
accept = 'videos';
accept = ['images', 'videos'];
images
,audios
,videos
为内置类型,定义如下:
images = {
title: 'Images',
extensions: 'jpg,jpeg,gif,png,bmp,svg,tiff,tif,ico,jpe,svgz,pct,psp,ai,psd,raw,webp'
};
audios = {
title: 'Audios',
extensions: 'aac,aif,flac,iff,m4a,m4b,mid,midi,mp3,mpa,mpc,oga,ogg,ra,ram,snd,wav,wma'
};
videos = {
title: 'Videos',
extensions: 'avi,divx,flv,m4v,mkv,mov,mp4,mpeg,mpg,ogm,ogv,ogx,rm,rmvb,smil,webm,wmv,xvid'
};
APIs 接口
UploadCore.VERSION
静态变量,获得版本号。
UploadCore.setOptions
修改已经初始化后的 Options,目前支持
['name', 'url', 'params', 'action', 'data', 'headers',
'withCredentials', 'timeout', 'chunkEnable', 'chunkSize',
'chunkRetries', 'chunkProcessThreads', 'autoPending',
'auto', 'capcity', 'queueCapcity', 'sizeLimit',
'fileSizeLimit']
参数 | 类型 | 描述
--- |----- | ------
options | object
| 传入参数,同初始化
UploadCore.addConstraint
添加约束。
参数 | 类型 | 描述
--- |----- | ------
constraint | function
| 约束函数
constraint函数如下:
constraint = function () {
return true;
}
constraint函数返回true时表示受到限制,否则不,函数闭包中this指向当前UploadCore
。
UploadCore.isLimit
运行通过UploadCore.addConstraint
添加的约束,判断是否限制了添加更多的文件。
返回 bool
,true
表示受到约束。
UploadCore.addFilter
添加文件过滤函数。
参数 | 类型 | 描述
--- |----- | ------
filter | function
| 过滤函数
filter函数如下:
filter = function () {
return 'error string';
}
filter函数返回error时,文件会被过滤,否则不;有几种方式返回error:
返回字符串
return 'error string';
返回Error
return new Error('some error');
抛出异常
throw new Error('some error');
UploadCore.isMultiple
是否多选。
返回 bool
,true
表示多选。
UploadCore.getAccept
获得允许文件类型。
返回
[
{
title: 'Images',
extensions: ['jpg','jpeg','png','gif','bmp','webp'],
mimeTypes: 'image/*'
},
....
]
UploadCore.isFull
判断队列是否已满。
UploadCore.isEmpty
判断队列是否为空。
UploadCore.getStat
获得文件统计。
返回 Stat
UploadCore.getTotal
同Stat.getTotal
。
UploadCore.getFiles
同Stat.getFiles
。
UploadCore.stat
同Stat.stat
。
UploadCore.setSWF (静态方法)
设置flashpicker的url地址,用于不支持h5上传的浏览器。
参数 | 类型 | 描述
--- |----- | ------
url | string
| flashpicker的url地址
UploadCore.getPickerCollector
获得PickerCollector
单列。
UploadCore.getDndCollector
获得DndCollector
单列。
UploadCore.getPasteCollector
获得PasteCollector
单列。
UploadCore.on
添加事件监听。
参数 | 类型 | 描述
--- |----- | ------
event | string
| 事件名称
fn | function
| 事件处理函数
Events 事件
队列事件
名称 | 触发对象 | 参数 | 描述
--- | --- | --- | ---
QUEUE_UPLOAD_START
| UploadCore
| 无 | 队列上传开始
QUEUE_UPLOAD_END
| UploadCore
| 无 | 队列上传结束
QUEUE_FILE_ADDED
| UploadCore
| File
| 队列添加了一个文件
QUEUE_FILE_FILTERED
| UploadCore
| File
, Error
| 队列过滤了一个文件
QUEUE_ERROR
| UploadCore
| Error
| 队列错误
QUEUE_STAT_CHANGE
| UploadCore
| Stat
| 文件统计发生变化
正在进行时事件
名称 | 触发对象 | 参数 | 描述
--- | --- | --- | ---
FILE_UPLOAD_PREPARING
| UploadCore
| FileRequest
| 文件上传准备时
CHUNK_UPLOAD_PREPARING
| UploadCore
| ChunkRequest
| 分块上传准备时
CHUNK_UPLOAD_COMPLETING
|UploadCore
| ChunkResponse
| 分块上传结束时
FILE_UPLOAD_COMPLETING
|UploadCore
| FileResponse
| 文件上传结束时
正在进行时事件可以理解为普通事件的增强版,支持Promise返回值,注册的事件监听严格按照顺序执行。
up.on(Events.FILE_UPLOAD_PREPARING, (request) => {
return new Promise((resolve) => {
jQuery.getJSON('http://test.yanbingbing.com/token.php').done((token) => {
request.setParam('token', token);
resolve();
});
});
}).on(Events.FILE_UPLOAD_PREPARING, (request) => {
console.info(request.getParam('token'));
});
文件事件
文件事件同时在UploadCore
与File
上触发,当在UploadCore
上触发时,函数第一参数均为File
。
名称 | 触发对象 | 参数 | 描述
--- | --- | --- | ---
FILE_UPLOAD_START
| UploadCore
, File
| [File
] | 文件上传开始
FILE_UPLOAD_PREPARED
| UploadCore
, File
| [File
], FileRequest
|文件上传准备好了
FILE_UPLOAD_PROGRESS
| UploadCore
, File
| [File
], Progress
| 文件上传进度中
FILE_UPLOAD_END
| UploadCore
, File
| [File
] | 文件上传结束
FILE_UPLOAD_SUCCESS
| UploadCore
, File
| [File
], FileResponse
| 文件上传成功
FILE_UPLOAD_ERROR
| UploadCore
, File
| [File
], Error
| 文件上传失败
FILE_UPLOAD_COMPLETED
| UploadCore
, File
| [File
], Status
| 文件上传完成了
FILE_CANCEL
| UploadCore
, File
| [File
] | 文件退出
FILE_STATUS_CHANGE
| UploadCore
, File
| [File
], Status
| 文件状态发生变化
Errors 错误
我们定义了以下错误,方便错误发生时分辨。
AbortError
中断错误- name: AbortError
- message: (message)
TimeoutError
超时错误- name: TimeoutError
- message: (message)
NetworkError
网络错误- status: http status
- name: NetworkError
- message: (message)
QueueLimitError
队列限制错误- name: QueueLimitError
- message: queue limit
FilterError
过滤错误- file:
File
- name: FilterError
- message: (message)
- file:
DuplicateError
文件重复错误,继承自FilterError
- file:
File
- name: DuplicateError
- message: (message)
- file:
FileExtensionError
文件扩展名错误,继承自FilterError
- file:
File
- name: FileExtensionError
- message: (message)
- file:
FileSizeError
文件大小错误,继承自FilterError
- file:
File
- name: FileSizeError
- message: (message)
- file:
Status 状态
文件在上传过程中经历的状态值。
名称 | 值 | 描述
--- | --- | ---
ALL | 255 | 所有状态
PROCESS | 31 | 包含状态 INITED
至 END
INITED | 1 | 初始状态
QUEUED | 2 | 进入队列
PENDING | 4 | 队列中等待
PROGRESS | 8 | 上传中
END | 16 | 上传完成, 等待后续处理
SUCCESS | 32 | 上传成功
ERROR | 64 | 上传出错
CANCELLED | 128 | 上传取消 和 QUEUED
相反, 退出队列
以下为更详细的抽象,均在运行时创建,不对外暴露。
Collector 收集器
PickerCollector
创建一个input[type=file]
或者flash
拾取器,当浏览器支持DataTransfer&FileList
特性时,会优先使用input
,拾取器会覆盖在触发区域上方,点击弹出系统对话框以选择文件。
初始化
const picker = up.getPickerCollector();
在不支持Html5上传时,需要预先提供flashpicker.swf
的url地址。
UploadCore.setSWF(url);
添加触发区域
const area = picker.addArea(document.getElementById('upload-button'));
我们再添加一个触发区域,或者更多。
const area2 = picker.addArea(document.getElementById('upload-button2'));
返回的结果area是一个Emitter
,在flash
环境下会响应鼠标悬停(rollOver)
、鼠标移出(rollOut)
事件。
area.on('rollOver', () => {
}).on('rollOut', () => {
});
当这个添加的area不需要时,可以销毁。
area.destroy()
DndCollector
拖放上传支持。
初始化
const dnd = up.getDndCollector();
添加响应区域
const area = dnd.addArea(document.getElementById('droparea'));
返回的结果area是一个Emitter
,响应开始拖拽(start)
, 响应拖拽(response)
, 拖拽结束(end)
事件。
area.on('start', (e) => {
}).on('response', (e) => {
// 返回false值表示:拖拽的项目没有匹配或者未拖进响应区域
return false;
}).on('end', (e) => {
});
当这个添加的area不需要时,可以销毁。
area.destroy()
PasteCollector
粘贴拾取器支持。
初始化
const paster = up.getPasterCollector();
添加响应区域
const area = paster.addArea($('textarea')[0]);
返回的结果area是一个Emitter
,响应粘贴(paste)
事件。
area.on('paste', (clipboardData) => {
});
当这个添加的area不需要时,可以销毁。
area.destroy()
Stat 统计
队列文件的统计。
Stat.getTotal
获得参与统计的文件个数。
Stat.getFiles
参数 | 类型 | 描述
--- |----- | ------
flag | Status
| 状态mask
获得状态为flag的文件集合。flag支持Status
位操作:
flag = Status.ALL ^ Status.CANCELLED;
flag = Status.SUCCESS | Status.ERROR;
flag
为null
相当于Status.ALL
返回
[File, File, ...]
Stat.stat
参数 | 类型 | 描述
--- |----- | ------
flag | Status
| 状态mask
统计状态为flag的文件数目;flag赋值同上,例如:
stat(Status.SUCCESS | Status.ERROR)
返回
{
32: 2,
64: 1,
sum: 3
}
File 文件
Properties
id(string)
文件唯一id。
name(string)
文件名称。对于从粘贴进来的文件资源,有些情况没有文件名,取用id.ext
作为文件名。
ext(string)
文件扩展名。eg. jpg
。
type(string)
文件mimetypes类型。 eg. image/jpg
。
lastModified(int)
文件最后修改时间,精确到毫秒。eg. 1432866554681
。
size(int)
文件大小,单位byte。eg. 1024
。
progress(Progress)
文件上传进度。
File.getCore
获取UploadCore
。
File.isImage
判断是否是图像文件。mimetype
为image/jpg, image/jpeg, image/gif, image/png, image/bmp
其中一种,即为图像。
File.getStatus
获取当前文件状态,参见Status
。
File.getStatusName
获取当前文件状态标识。
File.getSource
获取源文件资源。
File.getAsDataUrl
参数 | 类型 | 描述
--- |----- | ------
timeout | int
| 超时时间
异步获取文件dataurl内容,返回jQuery-Promise
。
File.md5
异步计算文件MD5值,返回jQuery-Promise
。
File.session
获取一个文件上传的会话,返回一个jQuery-Promise
,让我们除了可以绑定事件外,还可以用session方式来绑定相关动作。
file.session().done(function (response) {
// 上传成功了
}).fail(function (error) {
// 上传失败了
}).progress(function (e) {
// 上传进度中
});
为了某些场景的设计,session
方式不需要、也不支持解除绑定,等当次上传会话结束后,会自动失效当前session-promise
。
如果你绑定的操作需要解除绑定或者不希望会失效,请考虑使用绑定事件方式。
File.complete
参数 | 类型 | 描述
--- |----- | ------
response | ChunkResponse
or *
| 用于构造FileResponse
的原始数据
结束并完成上传会话,这个函数大多数由内部调用,其它情况如秒传时会直接调用。
File.pending
让文件等待上传,一般用于手动上传、错误重传。
File.cancel
参数 | 类型 | 描述
--- |----- | ------
silent | bool
| 静默行为,为 true 时不触发相应的事件
结束上传会话,退出文件上传队列。
File.on
添加事件监听。
参数 | 类型 | 描述
--- |----- | ------
event | string
| 事件名称
fn | function
| 事件处理函数
Progress 进度
文件上传进度对象。
total(int)
上传时总大小,上传时这个值总是大于size
,因为包含一些请求头信息、formData数据。
loaded(int)
已经上传的数据大小。
percentage(int)
已经上传的百分比0-100
。
FileRequest 文件请求
文件上传请求参数控制,上传时由内部基于options.request
创建,作为事件FILE_UPLOAD_PREPARING
的唯一参数。
FileRequest.getFile
获得请求中的文件对象File
。
返回 File
FileRequest.setName
设置上传文件的字段名称,服务端用此字段接收文件。
参数 | 类型 | 描述
--- |----- | ------
name | string
| 上传文件的字段名称
FileRequest.getName
获取上传文件的字段名称。
返回 string
FileRequest.setUrl
设置上传服务器端响应url。
参数 | 类型 | 描述
--- |----- | ------
url | string
| 服务器端响应地址
FileRequest.getUrl
获得上传服务器端响应。
返回 string
FileRequest.getParams
获得参数Params
。
返回 Params
FileRequest.getParam
获得字段为name的参数集合,同Params
。
参数 | 类型 | 描述
--- |----- | ------
name | string
| 字段名称
返回
[
{name:'name', value:'value1'},
{name:'name', value:'value2'},
...
]
FileRequest.setParam
设置参数值,同Params
。
参数 | 类型 | 描述
--- |----- | ------
name | string
| 字段名称
value | *
| 字段值
FileRequest.getHeaders
获取文件上传时附带的请求头信息。
返回
[
{name:'header1', value:'value1'},
{name:'header2', value:'value2'},
...
]
FileRequest.setHeader(name, value)
设置一个附带请求头信息。
参数 | 类型 | 描述
--- |----- | ------
name | string
| 字段名称
value | *
| 字段值
FileRequest.setWithCredentials
设置是否上传时附带cookie等验证信息。
参数 | 类型 | 描述
--- |----- | ------
flag | bool
| 开关
FileRequest.isWithCredentials
是否上传时附带cookie等验证信息。
返回 bool
FileRequest.setTimeout
设置上传超时时间。
参数 | 类型 | 描述
--- |----- | ------
timeout | int
| 超时时间,单位ms
FileRequest.getTimeout
获取上传超时时间。
返回 int
,上传超时时间,单位ms。
FileRequest.setChunkSize
设置分片大小。
参数 | 类型 | 描述
--- |----- | ------
size | string
or int
| 分片大小,单位byte,格式见options.chunkSize
FileRequest.getChunkSize
获取分片大小。
返回 int
,分片大小,单位byte。
FileRequest.setChunkRetries
设置分片上传网络出错重试次数。
参数 | 类型 | 描述
--- |----- | ------
retries | int
| 重试次数
FileRequest.getChunkRetries
获取分片上传网络出错重试次数。
返回 int
,重试次数。
FileRequest.setChunkEnable
设置是否开启分片上传。
参数 | 类型 | 描述
--- |----- | ------
flag | bool
| 开关
FileRequest.isChunkEnable
判断是否分片上传,需要同时满足开启了分片上传
、分片大小大于256K
及文件大小大于分片大小
三个条件。
返回 bool
FileRequest.setChunkProcessThreads
设置分片上传并发数,一个文件分为多块上传时,同时上传的数量。
参数 | 类型 | 描述
--- |----- | ------
threads | int
| 并发数
FileRequest.getChunkProcessThreads
获取分片上传并发数。
返回 int
,并发数。
FileResponse 文件响应
文件上传完成时由内部创建,作为事件FILE_UPLOAD_COMPLETING
的唯一参数。
FileResponse.getFileRequest
获得FileRequest
。
返回 FileRequest
FileResponse.isFromMultiChunkResponse
判断是否由多个分片上传完成后响应的数据并实例化而来;正常的分片上传,我们会把最后完成的分片响应数据ChunkResponse
作为FileResponse
的原始响应数据;以下俩种情况此返回值为否:
- 无论是否使用多个分片上传时,秒传完成-即直接调用
complete(response)
方式; - 文件过小、或者未开启分片上传,上传过程没有多个分片。
FileResponse.getRawResponse
获得原生响应数据。
返回 ChunkResponse
| string
| null
FileResponse.getJson
尝试返回JSON格式的响应数据。
返回 JSON
| null
FileResponse.getResponse
获得响应数据。
返回 string
| *
FileResponse.setResponse
设置响应数据,一般为JSON数据。
参数 | 类型 | 描述
--- |----- | ------
response | JSON
or *
| 响应数据
ChunkRequest 文件块请求
文件分片上传时由内部FileRequest
派生创建,大多数能获取的数值采用改变时从FileRequest
复制方式来使用,作为事件CHUNK_UPLOAD_PREPARING
的唯一参数。
ChunkRequest.getFileRequest
获取FileRequest
。
返回 FileRequest
ChunkRequest.getBlob
获取切片对象。
返回 Blob
ChunkRequest.getIndex
获得切片索引。
返回 int
,切片索引,从0开始。
ChunkRequest.isMultiChunk
是否是多分片上传。
返回 bool
ChunkRequest.getFile
获得请求中的文件对象File
,同FileRequest.getFile
。
ChunkRequest.getName
获取上传文件的字段名称,同FileRequest.getName
。
ChunkRequest.setUrl
设置上传服务器端响应地址,同FileRequest.setUrl
。
ChunkRequest.getUrl
获得上传服务器端响应地址,同FileRequest.getUrl
。
ChunkRequest.getParams
获得参数,同FileRequest.getParams
。
ChunkRequest.getParam
获得字段为name的参数集合,同FileRequest.getParam
。
ChunkRequest.setParam
设置参数值,同FileRequest.setParam
。
ChunkRequest.getHeaders
获取文件上传时附带的请求头信息,同FileRequest.getHeaders
。
ChunkRequest.setHeader
设置一个附带请求头信息,同FileRequest.setHeaders
。
ChunkRequest.isWithCredentials
是否上传时附带cookie等验证信息,同FileRequest.isWithCredentials
。
ChunkRequest.getTimeout()
获取上传超时,同FileRequest.getTimeout
。
ChunkResponse 文件块响应
文件分片上传完成时由内部创建,作为事件CHUNK_UPLOAD_COMPLETING
的唯一参数。
ChunkResponse.getChunkRequest
获取ChunkRequest
。
返回 ChunkRequest
ChunkResponse.getRawResponse
获得原生响应数据。
返回 string
| null
ChunkResponse.getResponse
获得响应数据。
返回 string
| *
ChunkResponse.getJson
尝试返回JSON格式的响应数据。
返回 JSON
| null
ChunkResponse.setResponse
设置响应数据,一般为JSON数据。
参数 | 类型 | 描述
--- |----- | ------
response | JSON
or *
| 响应数据
Params 请求参数
用于发送的Form Data数据维护,内部由FileRequest
基于options.params
创建。
Params.addParam(name, value)
添加参数值。
参数 | 类型 | 描述
--- |----- | ------
name | string
| 字段名称
value | *
| 字段值
Params.removeParam
删除键名为name
的所有值设置。
参数 | 类型 | 描述
--- |----- | ------
name | string
| 字段名称
Params.getParam
获得字段name的值设置,single
为true返回单个值,否则以数组形式返回多个。
参数 | 类型 | 描述
--- |----- | ------
name | string
| 字段名称
single | bool
可选
| 是否返回单个值
返回
// 多值
[
{name:'name', value:'value1'},
{name:'name', value:'value2'},
...
]
// 单个值
'value1'
Params.setParam
设置参数值,删除键名为name
的所有值设置,新添加一个值为value
的设置。
参数 | 类型 | 描述
--- |----- | ------
name | string
| 字段名称
value | *
| 字段值
Params.clone
基于当前实例创建新Params
。
返回 Params
Params.toArray
以Array格式导出数据。
返回
params = [
{name: 'foo', value: 'bar'},
{name: 'foo', value: 'bar1'}
]
Params.toString
以querystring格式返回。
返回
foo=bar&foo=bar1