WebUploader參數

參數說明

  • dnd {Selector} [可選] [默認值:undefined]

    指定Drag And Drop拖拽的容器,若是不指定,則不啓動。javascript

  • disableGlobalDnd {Selector} [可選] [默認值:false]

    是否禁掉整個頁面的拖拽功能,若是不由用,圖片拖進來的時候會默認被瀏覽器打開。php

  • paste {Selector} [可選] [默認值:undefined]

    指定監聽paste事件的容器,若是不指定,不啓用此功能。此功能爲經過粘貼來添加截屏的圖片。建議設置爲document.body.html

  • pick {Selector, Object} [可選] [默認值:undefined]

    指定選擇文件的按鈕容器,不指定則不建立按鈕。html5

    • id {Seletor|dom} 指定選擇文件的按鈕容器,不指定則不建立按鈕。注意 這裏雖然寫的是 id, 可是不是隻支持 id, 還支持 class, 或者 dom 節點。
    • label {String} 請採用 innerHTML 代替
    • innerHTML {String} 指定按鈕文字。不指定時優先從指定的容器中看是否自帶文字。
    • multiple {Boolean} 是否開起同時選擇多個文件能力。
  • accept {Arroy} [可選] [默認值:null]

    指定接受哪些類型的文件。 因爲目前還有ext轉mimeType表,因此這裏須要分開指定。java

    • title {String} 文字描述
    • extensions {String} 容許的文件後綴,不帶點,多個用逗號分割。
    • mimeTypes {String} 多個用逗號分割。

    如:jquery

    {
        title: 'Images',
        extensions: 'gif,jpg,jpeg,bmp,png',
        mimeTypes: 'image/*'
    }
  • thumb {Object} [可選]

    配置生成縮略圖的選項。android

    默認爲:ios

    { width: 110, height: 110, // 圖片質量,只有type爲`image/jpeg`的時候纔有效。 quality: 70, // 是否容許放大,若是想要生成小圖的時候不失真,此選項應該設置爲false. allowMagnify: true, // 是否容許裁剪。 crop: true, // 爲空的話則保留原有圖片格式。 // 不然強制轉換成指定的類型。 type: 'image/jpeg' }
  • compress {Object} [可選]

    配置壓縮的圖片的選項。若是此選項爲false, 則圖片在上傳前不進行壓縮。web

    默認爲:chrome

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

事件說明

事件名 參數說明 描述
dndAccept
  • items {DataTransferItemList}

    DataTransferItem

阻止此事件能夠拒絕某些類型的文件拖入進來。目前只有 chrome 提供這樣的 API,且只能經過 mime-type 驗證。

beforeFileQueued
  • file {File}

    File對象

當文件被加入隊列以前觸發,此事件的handler返回值爲false,則此文件不會被添加進入隊列。

fileQueued
  • file {File}

    File對象

當文件被加入隊列之後觸發。

filesQueued
  • files {File}

    數組,內容爲原始File(lib/File)對象。

當一批文件添加進隊列之後觸發。

fileDequeued
  • file {File}

    File對象

當文件被移除隊列後觸發。

reset  

當 uploader 被重置的時候觸發。

startUpload  

當開始上傳流程時觸發。

stopUpload  

當開始上傳流程暫停時觸發。

uploadFinished  

當全部文件上傳結束時觸發。

uploadStart
  • file {File}

    File對象

某個文件開始上傳前觸發,一個文件只會觸發一次。

uploadBeforeSend
  • object {Object}
  • data {Object}

    默認的上傳參數,能夠擴展此對象來控制上傳參數。

  • headers {Object}

    能夠擴展此對象來控制上傳頭部。

當某個文件的分塊在發送前觸發,主要用來詢問是否要添加附帶參數,大文件在開起分片上傳的前提下此事件可能會觸發屢次。

uploadAccept
  • object {Object}
  • ret {Object}

    服務端的返回數據,json格式,若是服務端不是json格式,從ret._raw中取數據,自行解析。

當某個文件上傳到服務端響應後,會派送此事件來詢問服務端響應是否有效。若是此事件handler返回值爲false, 則此文件將派送server類型的uploadError事件。

uploadProgress
  • file {File}

    File對象

  • percentage {Number}

    上傳進度

上傳過程當中觸發,攜帶上傳進度。

uploadError
  • file {File}

    File對象

  • reason {String}

    出錯的code

當文件上傳出錯時觸發。

uploadSuccess
  • file {File}

    File對象

  • response {Object}

    服務端返回的數據

當文件上傳成功時觸發。

uploadComplete
  • file {File} [可選]

    File對象

無論成功或者失敗,文件上傳完成時觸發。

error
  • type {String}

    錯誤類型。

當validate不經過時,會以派送錯誤事件的形式通知調用者。經過upload.on('error', handler)能夠捕獲到此類錯誤,目前有如下錯誤會在特定的狀況下派送錯來。

  • Q_EXCEED_NUM_LIMIT 在設置了fileNumLimit且嘗試給uploader添加的文件數量超出這個值時派送。
  • Q_EXCEED_SIZE_LIMIT 在設置了Q_EXCEED_SIZE_LIMIT且嘗試給uploader添加的文件總大小超出這個值時派送。
  • Q_TYPE_DENIED 當文件類型不知足時觸發。。

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信息的。

構造函數

事件說明

事件名 參數說明 描述
statuschange  

文件狀態變化

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

參數:

返回值:

從隊列中取出一個指定狀態的文件。

sort

  • sort( fn ) ⇒ undefined

參數:

  • fn {Function}

    排序方法

對隊列進行排序,可以控制文件上傳順序。

getFiles

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

參數:

獲取指定類型的文件列表, 列表中每個成員爲File對象。

removeFile

  • removeFile( file ) ⇒ Array

參數:

  • 文件對象。 {File}

在隊列中刪除文件。

相關文章
相關標籤/搜索