WebUploader API 文件詳細解讀

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
}

// 初始狀態圖片上傳前不會壓縮
var uploader = new WebUploader.Uploader({
    compress: null;
});

// 修改後圖片上傳前，嘗試將圖片壓縮到1600 * 1600
uploader.option( 'compress', {
    width: 1600,
    height: 1600
});

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

});

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

reset

• reset() ⇒ undefined

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

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.unRegister

• Uploader.unRegister(name);

引數:

• name {string}元件名字

刪除外掛，只有在註冊時指定了名字的才能被刪除。

Uploader.register({
    name: 'custom',

    'make-thumb': function() {

    }
});

Uploader.unRegister('custom');

Base

基礎類，提供一些簡單常用的方法。

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

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

 aliasFn();    // => Object Name

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

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

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

var obj = {};

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

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

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

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