特性一览

• md5（用于秒传）
• 分片上传
• html5-runtime，flash-runtime
• 多种收集器Collector（DndCollector、PasteCollector、PickerCollector）
• 拥抱es6

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'));

完全的功能仅在最新的Chrome浏览器中支持，对于不支持的浏览器，在保证上传功能可用的情况下，采用不支持或降低处理。

特性支持一览

如果要保证能在所有浏览器中运行，我们需要引入es5-shim相关ployfill脚本。

<script src="/path/to/es-shim.min.js"></script>
<script src="/path/to/es-sham.min.js"></script>

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'
};

静态变量，获得版本号。

修改已经初始化后的 Options，目前支持

['name', 'url', 'params', 'action', 'data', 'headers', 
'withCredentials', 'timeout', 'chunkEnable', 'chunkSize', 
'chunkRetries', 'chunkProcessThreads', 'autoPending', 
'auto', 'capcity', 'queueCapcity', 'sizeLimit', 
'fileSizeLimit']

添加约束。

constraint函数如下：

constraint = function () {
    return true;
}

constraint函数返回true时表示受到限制，否则不，函数闭包中this指向当前UploadCore。

运行通过UploadCore.addConstraint添加的约束，判断是否限制了添加更多的文件。

返回 bool，true表示受到约束。

添加文件过滤函数。

filter函数如下：

filter = function () {
   return 'error string';
}

filter函数返回error时，文件会被过滤，否则不；有几种方式返回error：

返回字符串

return 'error string';

返回Error

return new Error('some error');

抛出异常

throw new Error('some error');

是否多选。

返回 bool，true表示多选。

获得允许文件类型。

返回

[
    {
        title: 'Images',
        extensions: ['jpg','jpeg','png','gif','bmp','webp'],
        mimeTypes: 'image/*'
    },
    ....
]

判断队列是否已满。

判断队列是否为空。

获得文件统计。

返回 Stat

同Stat.getTotal。

同Stat.getFiles。

同Stat.stat。

设置flashpicker的url地址，用于不支持h5上传的浏览器。

获得PickerCollector单列。

获得DndCollector单列。

获得PasteCollector单列。

添加事件监听。

队列事件

正在进行时事件

正在进行时事件可以理解为普通事件的增强版，支持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。

我们定义了以下错误，方便错误发生时分辨。

• 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)
• DuplicateError 文件重复错误，继承自FilterError
  • file: File
  • name: DuplicateError
  • message: (message)
• FileExtensionError 文件扩展名错误，继承自FilterError
  • file: File
  • name: FileExtensionError
  • message: (message)
• FileSizeError 文件大小错误，继承自FilterError
  • file: File
  • name: FileSizeError
  • message: (message)

文件在上传过程中经历的状态值。

以下为更详细的抽象，均在运行时创建，不对外暴露。

创建一个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()

拖放上传支持。

初始化

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()

粘贴拾取器支持。

初始化

const paster = up.getPasterCollector();

添加响应区域

const area = paster.addArea($('textarea')[0]);

返回的结果area是一个Emitter，响应粘贴(paste)事件。

area.on('paste', (clipboardData) => {

});

当这个添加的area不需要时，可以销毁。

area.destroy()

队列文件的统计。

获得参与统计的文件个数。

获得状态为flag的文件集合。flag支持Status位操作：

flag = Status.ALL ^ Status.CANCELLED;
flag = Status.SUCCESS | Status.ERROR;

flag为null相当于Status.ALL

返回

[File, File, ...]

统计状态为flag的文件数目；flag赋值同上，例如：

stat(Status.SUCCESS | Status.ERROR)

返回

{
    32: 2,
    64: 1,
    sum: 3
}

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)

文件上传进度。

获取UploadCore。

判断是否是图像文件。mimetype为image/jpg, image/jpeg, image/gif, image/png, image/bmp其中一种，即为图像。

获取当前文件状态，参见Status。

获取当前文件状态标识。

获取源文件资源。

异步获取文件dataurl内容，返回jQuery-Promise。

异步计算文件MD5值，返回jQuery-Promise。

获取一个文件上传的会话，返回一个jQuery-Promise，让我们除了可以绑定事件外，还可以用session方式来绑定相关动作。

file.session().done(function (response) {
   // 上传成功了
}).fail(function (error) {
   // 上传失败了
}).progress(function (e) {
   // 上传进度中
});

为了某些场景的设计，session方式不需要、也不支持解除绑定，等当次上传会话结束后，会自动失效当前session-promise。

如果你绑定的操作需要解除绑定或者不希望会失效，请考虑使用绑定事件方式。

结束并完成上传会话，这个函数大多数由内部调用，其它情况如秒传时会直接调用。

让文件等待上传，一般用于手动上传、错误重传。

结束上传会话，退出文件上传队列。

添加事件监听。

文件上传进度对象。

total(int)

上传时总大小，上传时这个值总是大于size，因为包含一些请求头信息、formData数据。

loaded(int)

已经上传的数据大小。

percentage(int)

已经上传的百分比0-100。

文件上传请求参数控制，上传时由内部基于options.request创建，作为事件FILE_UPLOAD_PREPARING的唯一参数。

获得请求中的文件对象File。

返回 File

设置上传文件的字段名称，服务端用此字段接收文件。

获取上传文件的字段名称。

返回 string

设置上传服务器端响应url。

获得上传服务器端响应。

返回 string

获得参数Params。

返回 Params

获得字段为name的参数集合，同Params。

返回

[
	{name:'name', value:'value1'},
	{name:'name', value:'value2'},
	...
]

设置参数值，同Params。

获取文件上传时附带的请求头信息。

返回

[
	{name:'header1', value:'value1'},
	{name:'header2', value:'value2'},
	...
]

设置一个附带请求头信息。

设置是否上传时附带cookie等验证信息。

是否上传时附带cookie等验证信息。

返回 bool

设置上传超时时间。

获取上传超时时间。

返回 int，上传超时时间，单位ms。

设置分片大小。

获取分片大小。

返回 int，分片大小，单位byte。

设置分片上传网络出错重试次数。

获取分片上传网络出错重试次数。

返回 int，重试次数。

设置是否开启分片上传。

判断是否分片上传，需要同时满足开启了分片上传、分片大小大于256K及文件大小大于分片大小三个条件。

返回 bool

设置分片上传并发数，一个文件分为多块上传时，同时上传的数量。

获取分片上传并发数。

返回 int，并发数。

文件上传完成时由内部创建，作为事件FILE_UPLOAD_COMPLETING的唯一参数。

获得FileRequest。

返回 FileRequest

判断是否由多个分片上传完成后响应的数据并实例化而来；正常的分片上传，我们会把最后完成的分片响应数据ChunkResponse作为FileResponse的原始响应数据；以下俩种情况此返回值为否：

• 无论是否使用多个分片上传时，秒传完成-即直接调用complete(response)方式；
• 文件过小、或者未开启分片上传，上传过程没有多个分片。

获得原生响应数据。

返回 ChunkResponse | string | null

尝试返回JSON格式的响应数据。

返回 JSON | null

获得响应数据。

返回 string | *

设置响应数据，一般为JSON数据。

文件分片上传时由内部FileRequest派生创建，大多数能获取的数值采用改变时从FileRequest复制方式来使用，作为事件CHUNK_UPLOAD_PREPARING的唯一参数。

获取FileRequest。

返回 FileRequest

获取切片对象。

返回 Blob

获得切片索引。

返回 int，切片索引，从0开始。

是否是多分片上传。

返回 bool

获得请求中的文件对象File，同FileRequest.getFile。

获取上传文件的字段名称，同FileRequest.getName。

设置上传服务器端响应地址，同FileRequest.setUrl。

获得上传服务器端响应地址，同FileRequest.getUrl。

获得参数，同FileRequest.getParams。

获得字段为name的参数集合，同FileRequest.getParam。

设置参数值，同FileRequest.setParam。

获取文件上传时附带的请求头信息，同FileRequest.getHeaders。

设置一个附带请求头信息，同FileRequest.setHeaders。

是否上传时附带cookie等验证信息，同FileRequest.isWithCredentials。

获取上传超时，同FileRequest.getTimeout。

文件分片上传完成时由内部创建，作为事件CHUNK_UPLOAD_COMPLETING的唯一参数。

获取ChunkRequest。

返回 ChunkRequest

获得原生响应数据。

返回 string | null

获得响应数据。

返回 string | *

尝试返回JSON格式的响应数据。

返回 JSON | null

设置响应数据，一般为JSON数据。

用于发送的Form Data数据维护，内部由FileRequest基于options.params创建。

添加参数值。

删除键名为name的所有值设置。

获得字段name的值设置，single为true返回单个值，否则以数组形式返回多个。

返回

// 多值
[
	{name:'name', value:'value1'},
	{name:'name', value:'value2'},
	...
]

// 单个值
'value1'

设置参数值，删除键名为name的所有值设置，新添加一个值为value的设置。

基于当前实例创建新Params。

返回 Params

以Array格式导出数据。

返回

params = [
  {name: 'foo', value: 'bar'},
  {name: 'foo', value: 'bar1'}
]

以querystring格式返回。

返回

foo=bar&foo=bar1