jQuery.when()

jQuery.when( deferreds )返回类型:Promise

描述:提供一种方式来执行回调函数,基于零个或多个可延后的对象,通常是延迟对象,代表异步事件。

如果没有向jQuery.when()传递参数,它将返回一个已解决的延迟对象。

如果把一个延迟对象传递给jQuery.when(),通过此方法返回它的应答对象(延迟对象方法的子集)。可以调用应答对象的额外方法来附加回调函数,譬如deferred.then。当延迟对象被解决或被拒绝时(通常是被原来创建延迟对象的代码所执行),将调用相应的回调函数。例如,jQuery.ajax()方法返回的jqXHR对象,是一个应答兼容的对象,可以以这种方式使用它:

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

如果传递给jQuery.when()的参数既不是一个延迟对象也不是一个应答对象,它会被视为一个已解决的延迟对象,然后会立即执行已附加的doneCallback回调函数。doneCallback传入了原来的参数。在这种情况下,你可以设置任何failCallback,但是它们永远不会被调用,因为延迟对象永远不会被拒绝。例如:

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

如果你没有传递给它任何参数,jQuery.when()将返回一个已解决的延迟对象。

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

在这种情况下如果把多个延迟对象传递给jQuery.when,此方法返回来自新的“主”延迟对象的应答对象,跟踪所有传入的延迟对象的合计状态。一旦所有的延迟对象都被解决,此方法将解决它的主延迟对象;一旦其中一个延迟对象被拒绝,此方法将拒绝它的主延迟对象。如果主延迟对象已被解决,将执行针对主延迟对象的doneCallback。传递给doneCallback的参数提供了针对每个延迟对象的解决值,并匹配传递给jQuery.when()的延迟对象的顺序。例如:

1
2
3
4
5
6
7
8
9
10
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" );

在此事件中,不用值解决了一个延迟对象,对应的doneCallback参数将是undefined。如果一个延迟对象解决到一个值,对应的参数将占住这个值。如果一个延迟对象解决到多个值,对应的将是那些值的数组。例如:

1
2
3
4
5
6
7
8
9
10
11
12
13
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 );

在多个延迟对象的情况下,如果其中一个延迟对象被拒绝了,jQuery.when()会立即引发针对它的主延迟对象的failCallback。请注意,在此时,有一些延迟对象依然是未解决。传递给failCallback的参数匹配针对被拒绝的延迟对象的failCallback的签名。如果你需要实施针对这种情况的额外处理,譬如取消任何未完成的Ajax请求,你可以在闭包内保持对底层jqXHR对象的引用,并且在failCallback中检查、取消它们。

示例:

在两个Ajax请求成功之后执行一个函数。请参阅jQuery.ajax()文档以了解针对Ajax请求的success状况和error状况的描述。

1
2
3
4
5
6
7
8
$.when( $.ajax( "/page1.php" ), $.ajax( "/page2.php" ) ).done(function( a1, a2 ) {
// a1 and a2 are arguments resolved for the page1 and page2 ajax requests, respectively.
// Each argument is an array with the following structure: [ 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函数,否则,如果任一个Ajax请求出现错误,就执行myFailure函数。

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