jQuery.when()
分类:核心 | Deferred对象
jQuery.when( deferreds )
描述:提供一个方法,用来基于一个或多个对象执行回调函数,Deferred对象通常代表异步事件。
如果向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 );