Web Uploader內部類的詳細説明，以下提及的功能類，都可以在WebUploader這個變量中訪問到。

As you know, Web Uploader的每個文件都是用過AMD規範中的define組織起來的, 每個Module都會有個module id. 默認module id為該文件的路徑，而此路徑將會轉化成名字空間存放在WebUploader中。如：

• module base：WebUploader.Base
• module file: WebUploader.File
• module lib/dnd: WebUploader.Lib.Dnd
• module runtime/html5/dnd: WebUploader.Runtime.Html5.Dnd

以下文檔中對類的使用可能省略掉了WebUploader前綴。

Uploader

• new Uploader( opts ) ⇒ Uploader

上傳入口類。

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

    // 開起分片上傳。
    chunked: true
});

參數説明

• 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 指定黑名單。

事件説明

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 alt="" 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}

在隊列中刪除文件。