-s pre syn detail rep tle esp aggregate multipl

地址：http://api.jquery.com/jQuery.when/

jQuery.when( deferreds )，returns Promise

正文

Description: Provides a way to execute callback functions based on zero or more Thenable objects, usually Deferred objects that represent asynchronous events.

描述：提供一個執行回調函數的方法，它是基於0或多個繼發對象的，這些對象通常是表示異步事件的deferred對象。

deferreds

Type: Deferred or Promise or Thenable Zero or more Thenable objects.

jQuery.when( deferreds )方法是 JQ1.5版本後添加的方法。傳入的參數deferreds類型為deferred，promise，thenable，0或多個繼發對象。

If no arguments are passed to jQuery.when(), it will return a resolved Promise.

如果不傳遞參數給when，該方法將返回一個已完成狀態的promise。關於Promise（參看：http://www.jianshu.com/p/063f7e490e9a）。

If a single Deferred is passed to jQuery.when(), its Promise object (a subset of the Deferred methods) is returned by the method. Additional methods of the Promise object can be called to attach callbacks, such as deferred.then. When the Deferred is resolved or rejected, usually by the code that created the Deferred originally, the appropriate callbacks will be called. For example, the jqXHR object returned by jQuery.ajax()

is a Promise-compatible object and can be used this way:

$.when( $.ajax( "test.aspx" ) ).then(function( data, textStatus, jqXHR ) { alert( jqXHR.status ); // Alerts 200 });

如果僅將一個deferred傳給jQuery.when()，一個Promise對象（deferred對象的子集）將被這個方法返回。promise對象的附加方法將可以附著到回調上被調用。跟deferred一樣。通常一個deferred被創建它的原始腳本完成或者失敗後，對應的回調將被調用。比如，被jQuery.ajax()返回的jqXHR對象是一個混合的promise對象，可以如下使用：例子見上，不贅述。

If a single argument is passed to jQuery.when() and it is not a Deferred or a Promise, it will be treated as a resolved Deferred and any doneCallbacks attached will be executed immediately. The doneCallbacks are passed the original argument. In this case any failCallbacks you might set are never called since the Deferred is never rejected. For example:

$.when( { testing: 123 } ).done(function( x ) { alert( x.testing ); // Alerts "123" });

如果僅將一個參數傳入jQuery.when()，並且它不是一個deferred或者promise對象，它將被當作一個已完成的deferred對象，任何done附著的done回調將立即被執行。done回調將被傳入原始參數。這樣的話，任何的fail回調都不能設置或者調用，因為deferred永遠不會失敗。舉例如下：例子見引用。

If you don‘t pass it any arguments at all, jQuery.when() will return a resolved promise.

$.when().then(function( x ) { alert( "I fired immediately" ); });

如果不傳遞任何參數，jQuery.when()將返回一個完成狀態的promise。

In the case where multiple Deferred objects are passed to jQuery.when(), the method returns the Promise from a new "master" Deferred object that tracks the aggregate state of all the Deferreds it has been passed. The method will resolve its master Deferred as soon as all the Deferreds resolve, or reject the master Deferred as soon as one of the Deferreds is rejected. If the master Deferred is resolved, the doneCallbacks for the master Deferred are executed. The arguments passed to the doneCallbacks provide the resolved values for each of the Deferreds, and matches the order the Deferreds were passed to jQuery.when(). For example: var d1 = $.Deferred(); var d2 = $.Deferred(); $.when( d1, d2 ).done(function ( v1, v2 ) { console.log( v1 ); // "Fish" console.log( v2 ); // "Pizza" }); d1.resolve( "Fish" ); d2.resolve( "Pizza" );

既然這樣，如果傳遞復合的deferred對象給jQuery.when()，方法將返回一個promise對象，它來自於一個新的主deferred對象，這個對象會跟蹤記錄下所有傳入的deferreds的全部軌跡。這個方法在所有defferreds完成後將立即完成它的主deferred，或者會在所有deferreds失敗的時候後立即置為失敗。如果主deferred已經完成，它的done回調會被執行。傳入到done回調的所有參數提供了所有deferreds的完成值，並且按照傳遞給jQuery.when()的所有deferred的順序，例如：例子見上。 再舉一個例子：

var dtd = $.Deferred();
var wait=function(dtd){
  setTimeout(task, 8000);
  function task(){
    console.log("i‘m jiangtian!");
    dtd.resolve();
  }
  return dtd;
}

$.when(wait(dtd)).done(function(){
  console.log("累死我了，終於執行完了。");
})

阮一峰這篇文章寫的相當詳細，推薦：《jQuery的deferred對象詳解 - 阮一峰的網絡日誌》

In the event a Deferred was resolved with no value, the corresponding doneCallback argument will be undefined. If a Deferred resolved to a single value, the corresponding argument will hold that value. In the case where a Deferred resolved to multiple values, the corresponding argument will be an array of those values. For example:

var d1 = $.Deferred(); var d2 = $.Deferred(); var d3 = $.Deferred(); $.when( d1, d2, d3 ).done(function ( v1, v2, v3 ) { console.log( v1 ); // v1 is undefined console.log( v2 ); // v2 is "abc" console.log( v3 ); // v3 is an array [ 1, 2, 3, 4, 5 ] }); d1.resolve(); d2.resolve( "abc" ); d3.resolve( 1, 2, 3, 4, 5 );

$.when()方法翻譯