参数说明

• dnd {Selector} [可选] [默认值：undefined]

  指定Drag And Drop拖拽的容器，如果不指定，则不启动。

• disableGlobalDnd {Selector} [可选] [默认值：false]

  是否禁掉整个页面的拖拽功能，如果不禁用，图片拖进来的时候会默认被浏览器打开。

• paste {Selector} [可选] [默认值：undefined]

  指定监听paste事件的容器，如果不指定，不启用此功能。此功能为通过粘贴来添加截屏的图片。建议设置为document.body.

• pick {Selector, Object} [可选] [默认值：undefined]

  指定选择文件的按钮容器，不指定则不创建按钮。

  • id {Seletor|dom} 指定选择文件的按钮容器，不指定则不创建按钮。注意 这里虽然写的是 id, 但是不是只支持 id, 还支持 class, 或者 dom 节点。
  • label {String} 请采用 innerHTML 代替
  • innerHTML {String} 指定按钮文字。不指定时优先从指定的容器中看是否自带文字。
  • multiple {Boolean} 是否开起同时选择多个文件能力。
• accept {Arroy} [可选] [默认值：null]

  指定接受哪些类型的文件。 由于目前还有ext转mimeType表，所以这里需要分开指定。

  • title {String} 文字描述
  • extensions {String} 允许的文件后缀，不带点，多个用逗号分割。
  • mimeTypes {String} 多个用逗号分割。

  如：

  {
      title: ‘Images‘,
      extensions: ‘gif,jpg,jpeg,bmp,png‘,
      mimeTypes: ‘image/*‘
  }

• thumb {Object} [可选]

  配置生成缩略图的选项。

  默认为：

  {
      width: 110,
      height: 110,
  
      // 图片质量，只有type为`image/jpeg`的时候才有效。
      quality: 70,
  
      // 是否允许放大，如果想要生成小图的时候不失真，此选项应该设置为false.
      allowMagnify: true,
  
      // 是否允许裁剪。
      crop: true,
  
      // 为空的话则保留原有图片格式。
      // 否则强制转换成指定的类型。
      type: ‘image/jpeg‘
  }

• compress {Object} [可选]

  配置压缩的图片的选项。如果此选项为false, 则图片在上传前不进行压缩。

  默认为：

  {
      width: 1600,
      height: 1600,
  
      // 图片质量，只有type为`image/jpeg`的时候才有效。
      quality: 90,
  
      // 是否允许放大，如果想要生成小图的时候不失真，此选项应该设置为false.
      allowMagnify: false,
  
      // 是否允许裁剪。
      crop: false,
  
      // 是否保留头部meta信息。
      preserveHeaders: true,
  
      // 如果发现压缩后文件大小比原来还大，则使用原来图片
      // 此属性可能会影响图片自动纠正功能
      noCompressIfLarger: false,
  
      // 单位字节，如果图片大小小于此值，不会采用压缩。
      compressSize: 0
  }

• auto {Boolean} [可选] [默认值：false]

  设置为 true 后，不需要手动调用上传，有文件选择即开始上传。

• runtimeOrder {Object} [可选] [默认值：html5,flash]

  指定运行时启动顺序。默认会想尝试 html5 是否支持，如果支持则使用 html5, 否则则使用 flash.

  可以将此值设置成 flash，来强制使用 flash 运行时。

• prepareNextFile {Boolean} [可选] [默认值：false]

  是否允许在文件传输时提前把下一个文件准备好。 对于一个文件的准备工作比较耗时，比如图片压缩，md5序列化。 如果能提前在当前文件传输期处理，可以节省总体耗时。

• chunked {Boolean} [可选] [默认值：false]

  是否要分片处理大文件上传。

• chunkSize {Boolean} [可选] [默认值：5242880]

  如果要分片，分多大一片？ 默认大小为5M.

• chunkRetry {Boolean} [可选] [默认值：2]

  如果某个分片由于网络问题出错，允许自动重传多少次？

• threads {Boolean} [可选] [默认值：3]

  上传并发数。允许同时最大上传进程数。

• formData {Object} [可选] [默认值：{}]

  文件上传请求的参数表，每次发送都会发送此对象中的参数。

• fileVal {Object} [可选] [默认值：‘file‘]

  设置文件上传域的name。

• method {Object} [可选] [默认值：‘POST‘]

  文件上传方式，POST或者GET。

• sendAsBinary {Object} [可选] [默认值：false]

  是否已二进制的流的方式发送文件，这样整个上传内容php://input都为文件内容， 其他参数在$_GET数组中。

• fileNumLimit {int} [可选] [默认值：undefined]

  验证文件总数量, 超出则不允许加入队列。

• fileSizeLimit {int} [可选] [默认值：undefined]

  验证文件总大小是否超出限制, 超出则不允许加入队列。

• fileSingleSizeLimit {int} [可选] [默认值：undefined]

  验证单个文件大小是否超出限制, 超出则不允许加入队列。

• duplicate {Boolean} [可选] [默认值：undefined]

  去重， 根据文件名字、文件大小和最后修改时间来生成hash Key.

• disableWidgets {String, Array} [可选] [默认值：undefined]

  默认所有 Uploader.register 了的 widget 都会被加载，如果禁用某一部分，请通过此 option 指定黑名单。

事件说明

// 初始状态图片上传前不会压缩
var uploader = new WebUploader.Uploader({
    compress: null;
});

// 修改后图片上传前，尝试将图片压缩到1600 * 1600
uploader.option( ‘compress‘, {
    width: 1600,
    height: 1600
});

uploader.addButton({
    id: ‘#btnContainer‘,
    innerHTML: ‘选择文件‘
});

uploader.on( ‘fileQueued‘, function( file ) {
    var $li = ...;

    uploader.makeThumb( file, function( error, ret ) {
        if ( error ) {
            $li.text(‘预览错误‘);
        } else {
            $li.append(‘<img  src="http://www.mamicode.com/‘ + ret + ‘" />‘);
        }
    });

});

uploader.on( ‘fileQueued‘, function( file ) {
    var $li = ...;

    uploader.md5File( file )

        // 及时显示进度
        .progress(function(percentage) {
            console.log(‘Percentage:‘, percentage);
        })

        // 完成
        .then(function(val) {
            console.log(‘md5 result:‘, val);
        });

});

$li.on(‘click‘, ‘.remove-this‘, function() {
    uploader.removeFile( file );
})

console.log( uploader.getFiles() );    // => all files
console.log( uploader.getFiles(‘error‘) )    // => all error files.

function retry() {
    uploader.retry();
}

uploader.reset();

$li.on(‘click‘, ‘.remove-this‘, function() {
    uploader.cancelFile( file );
})

Uploader.register({
    ‘make-thumb‘: ‘makeThumb‘
}, {
    init: function( options ) {},
    makeThumb: function() {}
});

Uploader.register({
    ‘make-thumb‘: function() {

    }
});

Uploader.register({
    name: ‘custom‘,

    ‘make-thumb‘: function() {

    }
});

Uploader.unRegister(‘custom‘);

Base

基础类，提供一些简单常用的方法。

create

• Base.create( opts ) ? Uploader

创建Uploader实例，等同于new Uploader( opts );

version

当前版本号。

$

引用依赖的jQuery或者Zepto对象。

browser

简单的浏览器检查结果。

• webkit webkit版本号，如果浏览器为非webkit内核，此属性为undefined。
• chrome chrome浏览器版本号，如果浏览器为chrome，此属性为undefined。
• ie ie浏览器版本号，如果浏览器为非ie，此属性为undefined。暂不支持ie10+
• firefox firefox浏览器版本号，如果浏览器为非firefox，此属性为undefined。
• safari safari浏览器版本号，如果浏览器为非safari，此属性为undefined。
• opera opera浏览器版本号，如果浏览器为非opera，此属性为undefined。

os

操作系统检查结果。

• android 如果在android浏览器环境下，此值为对应的android版本号，否则为undefined。
• ios 如果在ios浏览器环境下，此值为对应的ios版本号，否则为undefined。

inherits

• Base.inherits( super ) ? child
• Base.inherits( super, protos ) ? child
• Base.inherits( super, protos, statics ) ? child

参数:

• super {Class}

  父类

• protos {Object, Function} [可选]

  子类或者对象。如果对象中包含constructor，子类将是用此属性值。

  • constructor {Function} [可选]

    子类构造器，不指定的话将创建个临时的直接执行父类构造器的方法。

• statics {Object} [可选]

  静态属性或方法。

返回值:

• {Class}

  返回子类。

实现类与类之间的继承。

function Person() {
    console.log( ‘Super‘ );
}
Person.prototype.hello = function() {
    console.log( ‘hello‘ );
};

var Manager = Base.inherits( Person, {
    world: function() {
        console.log( ‘World‘ );
    }
});

// 因为没有指定构造器，父类的构造器将会执行。
var instance = new Manager();    // => Super

// 继承子父类的方法
instance.hello();    // => hello
instance.world();    // => World

// 子类的__super__属性指向父类
console.log( Manager.__super__ === Person );    // => true

noop

一个不做任何事情的方法。可以用来赋值给默认的callback.

bindFn

• Base.bindFn( fn, context ) ? Function

返回一个新的方法，此方法将已指定的context来执行。

var doSomething = function() {
        console.log( this.name );
    },
    obj = {
        name: ‘Object Name‘
    },
    aliasFn = Base.bind( doSomething, obj );

 aliasFn();    // => Object Name

log

• Base.log( args... ) ? undefined

引用Console.log如果存在的话，否则引用一个空函数noop。

slice

• Base.slice( target, start[, end] ) ? Array

被uncurrythis的数组slice方法。 将用来将非数组对象转化成数组对象。

function doSomthing() {
    var args = Base.slice( arguments, 1 );
    console.log( args );
}

doSomthing( ‘ignored‘, ‘arg2‘, ‘arg3‘ );    // => Array ["arg2", "arg3"]

guid

• Base.guid() ? String
• Base.guid( prefx ) ? String

生成唯一的ID

formatSize

• Base.formatSize( size ) ? String
• Base.formatSize( size, pointLength ) ? String
• Base.formatSize( size, pointLength, units ) ? String

参数:

• size {Number}

  文件大小

• pointLength {Number} [可选] [默认值: 2]

  精确到的小数点数。

• [units=[ {Array}

  ‘B‘, ‘K‘, ‘M‘, ‘G‘, ‘TB‘ ]] 单位数组。从字节，到千字节，一直往上指定。如果单位数组里面只指定了到了K(千字节)，同时文件大小大于M, 此方法的输出将还是显示成多少K.

格式化文件大小, 输出成带单位的字符串

console.log( Base.formatSize( 100 ) );    // => 100B
console.log( Base.formatSize( 1024 ) );    // => 1.00K
console.log( Base.formatSize( 1024, 0 ) );    // => 1K
console.log( Base.formatSize( 1024 * 1024 ) );    // => 1.00M
console.log( Base.formatSize( 1024 * 1024 * 1024 ) );    // => 1.00G
console.log( Base.formatSize( 1024 * 1024 * 1024, 0, [‘B‘, ‘KB‘, ‘MB‘] ) );    // => 1024MB

Deferred

• Base.Deferred() ? Deferred

创建一个Deferred对象。 详细的Deferred用法说明，请参照jQuery的API文档。

Deferred对象在钩子回掉函数中经常要用到，用来处理需要等待的异步操作。

// 在文件开始发送前做些异步操作。
// WebUploader会等待此异步操作完成后，开始发送文件。
Uploader.register({
    ‘before-send-file‘: ‘doSomthingAsync‘
}, {

    doSomthingAsync: function() {
        var deferred = Base.Deferred();

        // 模拟一次异步操作。
        setTimeout(deferred.resolve, 2000);

        return deferred.promise();
    }
});

isPromise

• Base.isPromise( anything ) ? Boolean

参数:

• anything {*}

  检测对象。

返回值:

• {Boolean}

判断传入的参数是否为一个promise对象。

console.log( Base.isPromise() );    // => false
console.log( Base.isPromise({ key: ‘123‘ }) );    // => false
console.log( Base.isPromise( Base.Deferred().promise() ) );    // => true

// Deferred也是一个Promise
console.log( Base.isPromise( Base.Deferred() ) );    // => true

when

• Base.when( promise1[, promise2[, promise3...]] ) ? Promise

返回一个promise，此promise在所有传入的promise都完成了后完成。 详细请查看这里。

Mediator

中介者，它本身是个单例，但可以通过installTo方法，使任何对象具备事件行为。 主要目的是负责模块与模块之间的合作，降低耦合度。

on

• on( name, callback[, context] ) ? self

参数:

• name {String}

  事件名，支持多个事件用空格隔开

• callback {Function}

  事件处理器

• context {Object} [可选]

  事件处理器的上下文。

返回值:

• {self}

  返回自身，方便链式

绑定事件。

callback方法在执行时，arguments将会来源于trigger的时候携带的参数。如

var obj = {};

// 使得obj有事件行为
Mediator.installTo( obj );

obj.on( ‘testa‘, function( arg1, arg2 ) {
    console.log( arg1, arg2 ); // => ‘arg1‘, ‘arg2‘
});

obj.trigger( ‘testa‘, ‘arg1‘, ‘arg2‘ );

如果callback中，某一个方法return false了，则后续的其他callback都不会被执行到。 切会影响到trigger方法的返回值，为false。

on还可以用来添加一个特殊事件all, 这样所有的事件触发都会响应到。同时此类callback中的arguments有一个不同处， 就是第一个参数为type，记录当前是什么事件在触发。此类callback的优先级比脚低，会再正常callback执行完后触发。

obj.on( ‘all‘, function( type, arg1, arg2 ) {
    console.log( type, arg1, arg2 ); // => ‘testa‘, ‘arg1‘, ‘arg2‘
});

once

• once( name, callback[, context] ) ? self

参数:

• name {String}

  事件名

• callback {Function}

  事件处理器

• context {Object} [可选]

  事件处理器的上下文。

返回值:

• {self}

  返回自身，方便链式

绑定事件，且当handler执行完后，自动解除绑定。

off

• off( [name[, callback[, context] ] ] ) ? self

参数:

• name {String} [可选]

  事件名

• callback {Function} [可选]

  事件处理器

• context {Object} [可选]

  事件处理器的上下文。

返回值:

• {self}

  返回自身，方便链式

解除事件绑定

trigger

• trigger( name[, args...] ) ? self

参数:

• type {String}

  事件名

• ... {*} [可选]

  任意参数

返回值:

• {Boolean}

  如果handler中return false了，则返回false, 否则返回true

触发事件

installTo

参数:

• obj {Object}

  需要具备事件行为的对象。

返回值:

• {Object}

  返回obj.

可以通过这个接口，使任何对象具备事件功能。

File

• new File( source ) ? File

参数:

• source {Lib.File}

  lib.File实例, 此source对象是带有Runtime信息的。

构造函数

name

文件名，包括扩展名（后缀）

size

文件体积（字节）

type

文件MIMETYPE类型，与文件类型的对应关系请参考http://t.cn/z8ZnFny

lastModifiedDate

文件最后修改日期

id

文件ID，每个对象具有唯一ID，与文件名无关

ext

文件扩展名，通过文件名获取，例如test.png的扩展名为png

statusText

状态文字说明。在不同的status语境下有不同的用途。

setStatus

• setStatus( status[, statusText] );

参数:

• status {File.Status, String}

  文件状态值

• statusText {String} [可选] [默认值: ‘‘]

  状态说明，常在error时使用，用http, abort,server等来标记是由于什么原因导致文件错误。

设置状态，状态变化时会触发change事件。

File.Status

文件状态值，具体包括以下几种类型：

• inited 初始状态
• queued 已经进入队列, 等待上传
• progress 上传中
• complete 上传完成。
• error 上传出错，可重试
• interrupt 上传中断，可续传。
• invalid 文件不合格，不能重试上传。会自动从队列中移除。
• cancelled 文件被移除。

Queue

文件队列, 用来存储各个状态中的文件。

stats

统计文件数。

• numOfQueue 队列中的文件数。
• numOfSuccess 上传成功的文件数
• numOfCancel 被取消的文件数
• numOfProgress 正在上传中的文件数
• numOfUploadFailed 上传错误的文件数。
• numOfInvalid 无效的文件数。
• numofDeleted 被移除的文件数。

append

参数:

• file {File}

  文件对象

将新文件加入对队列尾部

prepend

参数:

• file {File}

  文件对象

将新文件加入对队列头部

getFile

参数:

• fileId {String}

  文件ID

返回值:

• {File}

获取文件对象

fetch

• fetch( status ) ? File

参数:

• status {String}

  文件状态值

返回值:

• {File}

  File

从队列中取出一个指定状态的文件。

sort

• sort( fn ) ? undefined

参数:

• fn {Function}

  排序方法

对队列进行排序，能够控制文件上传顺序。

getFiles

• getFiles( [status1[, status2 ...]] ) ? Array

参数:

• status {String} [可选]

  文件状态值

获取指定类型的文件列表, 列表中每一个成员为File对象。

removeFile

• removeFile( file ) ? Array

参数:

• 文件对象。 {File}

在队列中删除文件。