WebUploader API 文档详细解读

var uploader = WebUploader.Uploader({
    swf: 'path_of_swf/Uploader.swf',

    // 开起分片上传。
    chunked: true
});

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

{
    width: 110,
    height: 110,

    // 图片质量，只有type为`image/jpeg`的时候才有效。
    quality: 70,

    // 是否允许放大，假如想要生成小图的时候不失真，此选项应该设置为false.
    allowMagnify: true,

    // 是否允许裁剪。
    crop: true,

    // 为空的话则保留原有图片格式。
    // 否则强制转换成指定的类型。
    type: 'image/jpeg'
}

{
    width: 1600,
    height: 1600,

    // 图片质量，只有type为`image/jpeg`的时候才有效。
    quality: 90,

    // 是否允许放大，假如想要生成小图的时候不失真，此选项应该设置为false.
    allowMagnify: false,

    // 是否允许裁剪。
    crop: false,

    // 是否保留头部meta信息。
    preserveHeaders: true,

    // 假如发现压缩后文件大小比原来还大，则使用原来图片
    // 此属性可能会影响图片自动纠正功能
    noCompressIfLarger: false,

    // 单位字节，假如图片大小小于此值，不会采用压缩。
    compressSize: 0
}

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

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

getStats

获取文件统计信息。返回一个包含一下信息的对象。

destroy

销毁 webuploader 实例

addButton

添加文件选择按钮，假如一个按钮不够，需要调用此方法来添加。参数跟options.pick一致。

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

makeThumb

生成缩略图，此过程为异步，所以需要传入callback。 通常情况在图片加入队里后调用此方法来生成预览图以增强交互效果。

当 width 或者 height 的值介于 0 – 1 时，被当成百分比使用。

callback中可以接收到两个参数。

注意 Date URL在IE6/7中不支持，所以不用调用此方法了，直接显示一张暂不支持预览图片好了。 也可以借助服务端，将 base64 数据传给服务端，生成一个临时文件供预览。

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

    uploader.makeThumb( file, function( error, ret ) {
        if ( error ) {
            $li.text('预览错误');
        } else {
            $li.append('<img alt="" src="' + ret + '" />');
        }
    });

});

md5File

计算文件 md5 值，返回一个 promise 对象，可以监听 progress 进度。

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

});

addFiles

参数:

添加文件到队列

removeFile

removeFile( file ) undefined
removeFile( id ) undefined
removeFile( file, true ) undefined
removeFile( id, true ) undefined

参数:

移除某一文件, 默认只会标记文件状态为已取消，假如第二个参数为 true 则会从 queue 中移除。

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

getFiles

返回指定状态的文件集合，不传参数将返回所有状态的文件。

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

retry

重试上传，重试指定文件，或者从出错的文件开始重新上传。

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

sort

排序队列中的文件，在上传之前调整可以控制上传顺序。

reset

重置uploader。目前只重置了队列。

uploader.reset();

predictRuntimeType

预测Uploader将采用哪个Runtime

upload

开始上传。此方法可以从初始状态调用开始上传流程，也可以从暂停状态调用，继续上传流程。

可以指定开始某一个文件。

stop

暂停上传。第一个参数为是否中断上传当前正在上传的文件。

假如第一个参数是文件，则只暂停指定文件。

cancelFile

参数:

标记文件状态为已取消, 同时将中断文件传输。

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

sInProgress

判断Uplaoder是否正在上传中。

skipFile

掉过一个文件上传，直接标记指定文件为已上传状态。

request

发送命令。当传入callback或者handler中返回promise时。返回一个当所有handler中的promise都完成后完成的新promise。

Uploader.register

参数:

添加组件

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

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

    }
});

Uploader.unRegister

参数:

删除插件，只有在注册时指定了名字的才能被删除。

Uploader.register({
    name: 'custom',

    'make-thumb': function() {

    }
});

Uploader.unRegister('custom');

Base

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

create

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

version

当前版本号。

$

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

browser

简单的浏览器检查结果。

os

操作系统检查结果。

inherits

参数:

返回值:

实现类与类之间的继承。

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

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

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

 aliasFn();    // => Object Name

log

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

slice

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

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

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

guid

生成唯一的ID

formatSize

参数:

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

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

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

参数:

返回值:

判断传入的参数是否为一个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

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

Mediator

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

on

参数:

返回值:

绑定事件。

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

参数:

返回值:

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

off

参数:

返回值:

解除事件绑定

trigger

参数:

返回值:

触发事件

installTo

参数:

返回值:

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

File

参数:

构造函数

事件说明

name

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

size

文件体积（字节）

type

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

lastModifiedDate

文件最后修改日期

id

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

ext

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

statusText

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

setStatus

参数:

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

File.Status

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

Queue

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

stats

统计文件数。

append

参数:

将新文件加入对队列尾部

prepend

参数:

将新文件加入对队列头部

getFile

参数:

返回值:

获取文件对象

fetch

参数:

返回值:

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

sort

参数:

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

getFiles

参数:

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

removeFile

参数:

在队列中删除文件。