jQuery.when()| jqueryAPI 2.2 中文手册- AspRain.cn 致力于Web开发技术翻译整理

jQuery API 2.2.0

jQuery.when()

分类:核心 | Deferred对象

返回: Promise

jQuery.when( deferreds )

描述:提供一个方法,用来基于一个或多个对象执行回调函数,Deferred对象通常代表异步事件。

加入于: 1.5
jQuery.when( deferreds )
  • deferreds
    类型:Deferred
    一个或更多的Deferred对象,或者纯JavaScript对象。

如果向jQuery.when()传递一个Deferred对象,它的Promise对象(一个Deferred对象的子集)会以这种方式返回。可以调用Promise对象的其它的方法,以附加回调函数,比如说deferred.then。当Deferred对象被解决或被拒绝时,通常是由创建Deferred对象的代码解决或拒绝,会调用适当的回调函数。举个例子,jQuery.ajax()返回的jqXHR对象是一个Promise兼容的对象,并可以以这种方式使用:

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

如果向jQuery.when()传递一个参数,而且它不是一个Deferred对象也不是一个Promise对象,它会被视为一个已解决的Deferred对象,而且附加上去的任何doneCallback回调函数会被立即执行。会向doneCallbacks传递了原始的参数。这样的话,你可能设置的任何failCakkbacks都永远不会被调用,因为这个Deferred对象不会被拒绝。举个例子:

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

如果你不向它传递任何参数,jQuery.when()将返回一个已经解决的Promise对象。

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

万一向jQuery.when()方法传递了多个Deferred对象,该方法会从一个新的“主”Deferred对象返回该Promise对象,跟踪了所有传入的Deferred对象的聚合状态。直到所有的Deferred对象都解决决时,该方法才会解决它的所有“主”Deferred对象,但是只要有一个Deferred对象被拒绝,则“主”Deferred对象就会被拒绝。传递给doneCallbacks的参数提供了针对每个Deferred对象的解决值,并匹配传递给jQuery.when()的Deferred对象的顺序。举个例子:

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对象,则对应的doneCallback参数将是undefined。如果只用一个值解决了一个Deferred对象,对象的参数将持有那个值。如果用多个值解决了一个Deferred对象,对应的将是那些值的数组。举个例子:

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

在多个Deferred对象的情况中,只有一个Deferred对象被拒绝,jQuery.when()会立即针对它的“主”Deferred对象引发failCallback。注意,在那时候有些Deferred对象可能依然处于未解决状态。传递给failCallbacks的参数匹配针对被拒绝的Deferred对象的failCallback的签名。如果你需要为这个案例实施额外的处理,比如说取消任何未完成的Ajax请求,你可以在闭包中保留对底层jqXHR对象的引用,并在failCallback中检查它们、取消它们。

示例

在一个Ajax请求成功时,执行一个函数。(请参阅jQuery.ajax()文档,以获得对Ajax请求的成功和失败情况的完整讲解。)

$.when( $.ajax( "/page1.php" ), $.ajax( "/page2.php" ) ).done(function( a1, a2 ) {
  // a1是解决page1的参数,a2是解决page2的参数。
  // 每个参数都是一个数组,带有下面的结构:[ data, statusText, jqXHR ]
  var data = a1[ 0 ] + a2[ 0 ]; // a1[ 0 ] = "Whip", a2[ 0 ] = " It"
  if ( /Whip It/.test( data ) ) {
    alert( "We got what we came for!" );
  }
});

在Ajax请求成功,执行函数myFunc,或在它失败时,执行函数myFailure

$.when( $.ajax( "/page1.php" ), $.ajax( "/page2.php" ) )
  .then( myFunc, myFailure );

如果网页上不能运行示例,请点击http://www.asprain.cn/jQueryAPI/jquery.when.htm查看示例。

如果你觉得本文档对你有用,欢迎给翻译作者支付宝打赏,支持翻译作者源源不断翻译更多有用的技术文档。