WebUploader API

Uploader

• new Uploader( opts ) ? Uploader

上传入口类。

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

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

option

• option( key ) ? *
• option( key, val ) ? self

获取或者设置Uploader配置项。

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

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

getStats

• getStats() ? Object

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

• successNum 上传成功的文件数
• progressNum 上传中的文件数
• cancelNum 被删除的文件数
• invalidNum 无效的文件数
• uploadFailNum 上传失败的文件数
• queueNum 还在队列中的文件数
• interruptNum 被暂停的文件数

destroy

• destroy() ? undefined

销毁 webuploader 实例

addButton

• addButton( pick ) ? Promise

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

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

makeThumb

• makeThumb( file, callback ) ? undefined
• makeThumb( file, callback, width, height ) ? undefined

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

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

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

• 第一个为error，如果生成缩略图有错误，此error将为真。
• 第二个为ret, 缩略图的Data URL值。

注意 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  src="‘ + ret + ‘" />‘);
        }
    });

});

md5File

• md5File( file[, start[, end]] ) ? promise

计算文件 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

• addFiles( file ) ? undefined
• addFiles( [file1, file2 ...] ) ? undefined

参数:

• files {Array of File or File} [可选]

  Files 对象 数组

添加文件到队列

removeFile

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

参数:

• file {File, id}

  File对象或这File对象的id

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

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

getFiles

• getFiles() ? Array
• getFiles( status1, status2, status... ) ? Array

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

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

retry

• retry() ? undefined
• retry( file ) ? undefined

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

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

sort

• sort( fn ) ? undefined

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

reset

• reset() ? undefined

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

uploader.reset();

predictRuntimeType

• predictRuntimeType() ? String

预测Uploader将采用哪个Runtime

upload

• upload() ? undefined
• upload( file | fileId) ? undefined

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

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

stop

• stop() ? undefined
• stop( true ) ? undefined
• stop( file ) ? undefined

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

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

cancelFile

• cancelFile( file ) ? undefined
• cancelFile( id ) ? undefined

参数:

• file {File, id}

  File对象或这File对象的id

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

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

isInProgress

• isInProgress() ? Boolean

判断Uplaoder是否正在上传中。

skipFile

• skipFile( file ) ? undefined

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

request

• request( command, args ) ? * | Promise
• request( command, args, callback ) ? Promise

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

Uploader.register

• Uploader.register(proto);
• Uploader.register(map, proto);

参数:

• responseMap {object}

  API 名称与函数实现的映射

• proto {object}

  组件原型，构造函数通过 constructor 属性定义

添加组件

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

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

    }
});

Uploader.unRegister

• Uploader.unRegister(name);

参数:

• name {string}

  组件名字

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

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}

在队列中删除文件。