jQuery Deferred マニュアルの日本語翻訳

README.md

jQuery Deferred マニュアルの日本語翻訳

メモ書き程度
http://api.jquery.com/category/deferred-object/

目次

• deferred.always()
• deferred.done()
• deferred.fail()
• deferred.isRejected()
• deferred.isResolved()
• deferred.notify()
• deferred.notifyWith()
• deferred.pipe()
• deferred.progress()
• deferred.promise()
• deferred.reject()
• deferred.rejectWith()
• deferred.resolve()
• deferred.resolveWith()
• deferred.state()
• deferred.then()
• .promise()
• jQuery.when()

jQuery.Deferred() は、同期/非同期関数の成功/失敗コールバックをキューに登録し、実行するために version 1.5 で追加された、ユーティリティである。

JavaScript では、オプションでコールバック関数を引数として受け取るのが一般的である。

例えば jQuery 1.5 以前では、jQuery.ajax() のような非同期プロセスは、ajax リクエストが成功、失敗、完了した直後に渡されたコールバック関数が実行される。

jQuery.Deferred() は、このコールバック関数の管理と実行を拡張する。具体的に、jQuery.Deferred() は複数のコールバック関数を柔軟に管理する方法を提供し、これらのコールバック関数は、元のディスパッチが既に完了しているかどうかに関わらず呼び出す事ができる。jQuery Deferred は、CommonJS の Promises/A をベースに設計された。

Deferred は、関数のチェイン可能なラッパーとして捉える事もできる。deferred.then(), deferred.done(), deferred.fail() のメソッドは、deferred.resolve(args)、deferred.reject(args) メソッドによって任意のパラメータと共に実行される。一度、'resolved'、または 'rejected' になった Deferred は、その状態から変更されない。(二度目の deferred.resolve() は無視される) Deferred が 'resolved' になった後に deferred.then() で追加された関数は、指定された引数によって直ちに実行される。

ほとんどの場合、jQuery.ajax() や jQuery.when() のような、Deferred、または Deferred 互換のオブジェクトが返された後、deferred.then(), deferred.done(), deferred.fail() 等の、コーブバック関数をキューに追加する関数を呼び出すだけで良い。作成された Deferred APIの内部で、deferred.resolve()、deferred.reject() が実行された時点で、適切なコールバック関数が実行される。

jQuery.Deferred()

Constructor
Usage: jQuery.Deferred( [callback] )
Returns: Deferred
Version: 1.5

jQuery.Deferred() コンストラクタは新しい Deferred オブジェクトを返す。new 演算子は必須ではない。

jQuery.Deferred は引数として関数を受け取る事ができる。この関数はコンストラクタがオブジェクトを返す前に実行され、Deferred オブジェクトを this に指定し、同時に第一引数として渡されて実行される。この関数は deferred.then() で追加された様に作用する。

Deferred は、'pending' 状態として開始される。 deferred.then(), deferred.done(), deferred.fail() で追加された関数は、遅延して実行するためにキューに詰まれる。deferred.resolve()、deferred.resolveWith() 関数は、Deferredを 'resolved' へ変更し、設定された doneCallbacks 関数を実行する。deferred.reject()、deferred.rejectWith() 関数は Deferred を 'rejected' へ変更し failCallbacks に設定された関数を実行する。 一度、'resolved'、'rejected' へなった Deferred はそれ以上、状態を変更できない。 'resolved', 'rejected' の Deferred へ追加されたコールバック関数は直ちに実行される。

Deferred オブジェクトは jQuery オブジェクトのようにチェインできる。 作成した Deferred のメソッドは、生成から直接チェインするか、一度変数に保存してから実行する。

deferred.always()

resolved,rejected の両方で実行されるコールバック関数を Deferred オブジェクトに追加する。

Usage: deferred.always( alwaysCallbacks [, alwaysCallbacks] )

• alwaysCallbacks 関数、または関数の配列。
  Deferred オブジェクトが resolved、または rejected になった際に呼ばれる。
• alwaysCallbacks (Optional) 関数、または関数の配列。
  Deferred オブジェクトが resolved、または rejected になった際に呼ばれる。

Returns: Deferred
Version: 1.6

引数は、関数、または関数の配列を受け取る。 Deferred が resolved か rejected になった際に alwaysCallbacks は実行される。 deferred.always() は Deferred オブジェクトを返すので、 Deferred オブジェクトの他のメソッド (.always()を含め) をチェインできる。 Deferred が resolved、rejected になった際、コールバック関数は追加された順番で実行され、resolve、reject、resolveWith、rejectWith メソッドに指定されたパラメータを受け取る。 詳細については Deferred オブジェクトのドキュメントを参照。

Example:

jQuery.get() は Deferred オブジェクトの派生である jqXHR オブジェクトを返すので、success、error コールバックとして deferred.always() を使用できる。

$.get("test.php").always( function() { 
  alert("$.get completed with success or error callback arguments"); 
} );

deferred.done()

resolved で実行されるコールバック関数を Deferred オブジェクトに追加する。

Usage: deferred.done( doneCallbacks [, doneCallbacks] )

• doneCallbacks 関数、または関数の配列。
  Deferred オブジェクトが resolved になった際に呼ばれる。
• doneCallbacks (Optional) 関数、または関数の配列。
  Deferred オブジェクトが resolved になった際に呼ばれる。

Returns: Deferred
Version: 1.5

deferred.done() は一つ以上の引数を受け取り、それぞれが関数、または関数の配列を渡す事ができる。 Deferred が 'resolved' になった際、doneCallbacks が実行される。コールバック関数は、追加された順番に呼び出される。deferred.done() は Deferred オブジェクトを返すので、.done() を含む他の Deferred オブジェクトのメソッドをチェインする事ができる。 Deferred が 'resolved' になった際、 doneCallbacks は追加された順番で実行され、 resolve、resolveWith メソッドに指定されたパラメータを受け取る。詳細については Deferred オブジェクトのドキュメントを参照。

Examples:

jQuery.done() は Deferred オブジェクトの派生である jqXHR オブジェクトを返すので、success コールバックとして deferred.done() を使用できる。

$.get("test.php").done(function() { 
  alert("$.get succeeded"); 
});

( もう一個の例は省略 )

deferred.fail()

rejected で実行されるコールバック関数を、Deferred オブジェクトに追加する

Usage: deferred.fail( failCallbacks [, failCallbacks] )

• failCallbacks 関数、または関数の配列。
  Deferred オブジェクトが rejected になった際に呼ばれる。
• failCallbacks (Optional) 関数、または関数の配列。
  Deferred オブジェクトが rejected になった際に呼ばれる。

Returns: Deferred
Version: 1.5

deferred.fail() は一つ以上の引数を受け取り、それぞれが関数、または関数の配列を渡す事ができる。 Deferred が rejected failCallbacks が実行される。コールバック関数は、追加された順番に呼び出される。deferred.fail() は Deferred オブジェクトを返すので、.fail() を含む他の Deferred オブジェクトのメソッドをチェインする事ができる。 Deferred が resolved になった際、 failCallbacks は追加された順番で実行され、 reject、rejectWith メソッドに指定されたパラメータを受け取る。詳細については Deferred オブジェクトのドキュメントを参照。

Example:

jQuery.done() は Deferred オブジェクトの派生である jqXHR オブジェクトを返すので、failure コールバックとして deferred.fail() を使用できる。

$.get("test.php")
  .done(function(){ alert("$.get succeeded"); })
  .fail(function(){ alert("$.get failed!"); });

deferred.isRejected()

Deferred オブジェクトが rejected かどうかを返す。

Deprecated
Usage: deferred.isRejected()
Returns: Boolean
Version: 1.5

jQuery1.7から非推奨。今後は deferred.state() を使う事。

Deferred オブジェクトが rejected の場合 (deferred.reject()、 deferred.rejectWith() が呼び出され、failCallbacks　が実行された(または実行中の場合)) に true を返す。

Deferred オブジェクトは、'pending', 'resolved', 'rejected' のうちの一つの状態になる。deferred.isResolved() は、Deferred オブジェクトが 'resolved' かどうかを確認する。 これらのメソッドは、例えば 'resolved' を意図していたにも関わらず、Deferred がすでに 'reject' になっていた用な場合のデバックに使用する。

deferred.isResolved()

Deferred オブジェクトが 'resolved' かどうかを返す。

Deprecated
Usage: deferred.isResolved()
Returns: Boolean
Version: 1.5

jQuery1.7から非推奨。今後は deferred.state() を使う事。

Deferred オブジェクトが resolved の場合 (deferred.resolved()、 deferred.resolvedWith() が呼び出され、doneCallbacks　が実行された(または実行中の場合)) に true を返す。

Deferred オブジェクトは、'pending', 'resolved', 'rejected' のうちの一つの状態になる。deferred.isRejected() は、Deferred オブジェクトが 'rejected' かどうかを確認する。 これらのメソッドは、例えば 'rejected' を意図していたにも関わらず、Deferred がすでに 'resolved' になっていた用な場合のデバックに使用する。

deferred.notify()

与えられた引数を使い、Deferrd オブジェクトに登録された progressCallback 関数を呼び出す。

Usage: deferred.notify( [args] )

• args Optional progressCallbacksへ渡す引数

Returns: Deferred
Version: 1.7

通常、 Deferred オブジェクトの制作者のみが呼び出す。 deferred.promise() を使い、Promise オブジェクトを生成する事で、他のコードが Deferred の状態を変更したり、通知する事を制限する事ができる。

deferred.notify が呼ばれると、 deferred.then、 deferred.progress によって追加された progressCallbacks 関数が呼び出される。 コールバック関数は追加された順に実行される。 各コールバック関数には、 .notify() からの引数が渡される。 Deferred が 'resolved'、または 'rejected' になった後の .notify() の呼び出し (と progressCallbacks 関数の追加) は無視される。 詳細については Deferred オブジェクトのドキュメントを参照。

deferred.notifyWith()

与えられたコンテクスト(this)と引数を使い、Deferrd オブジェクトに登録された progressCallback 関数を呼び出す。

Usage: deferred.notifyWith( context [, args] )

• context progressCallbacks内のthisに渡されるオブジェクト
• args Optional progressCallbacks へ渡す引数

Returns: Deferred
Version: 1.7

通常、 Deferred オブジェクトの制作者のみが呼び出す。 deferred.promise() を使い、Promise オブジェクトを生成する事で、他のコードが Deferred の状態を変更したり、通知する事を制限する事ができます。

deferred.notifyWith が呼ばれると、 deferred.then、 deferred.progress によって追加された progressCallbacks 関数が呼び出される。 コールバック関数は追加された順に実行される。 各コールバック関数には、 .notifyWith() からの引数が渡される。 Deferred が 'resolved'、または 'rejected' になった後の .notifyWith() の呼び出し (と progressCallbacks 関数の追加) は無視される。 詳細については Deferred オブジェクトのドキュメントを参照。

deferred.pipe()

Deferred に and/or フィルターを追加するためのユーティリティ

Usage: deferred.pipe( [doneFilter] [, failFilter] [, progressFilter] )

• doneFilter optional Deferred オブジェクトが resolved になった際に呼ばれる関数。
• failFilter optional Deferred オブジェクトが rejected になった際に呼ばれる関数。
• progressFilter optional Deferred オブジェクトへ progress notifications が送信された時に呼ばれる関数。

Returns: Promise
Version: 1.6, 1.7

deferred.pipe() は渡された関数を通して、 deferred の値やステータスをフィルタリングする新しい Promise オブジェクトを返す。 doneFilter と failFilter は、元の deferred の resolved / rejected の状態と、値をフィルタリングする。 jQuery 1.7 では、このメソッドはさらに、 元の Deferred での notify、 notifyWith 呼び出しをフィルタリングするための、 progressFilter 関数を登録できる。 これらのフィルタ内の戻り値は、作成された Promise オブジェクトの done() 、 fail() コールバックへの引数として指定される。連結された Promise オブジェクトのコールバックにその resolved / rejected ステータスと値を渡す、別の監視オブジェクト（Deferred, Promise etc）を返すことができる。 フィルター関数に null を指定するか、何も指定しなかった場合、 作成された Promise 関数は元の resolved / rejected ステータスと同じ値が渡される。

Examples:

Example: Filter resolve value:

var defer = $.Deferred(),
    filtered = defer.pipe(function( value ) {
        return value * 2;
    });

defer.resolve( 5 );
filtered.done(function( value ) {
    alert( "Value is ( 2*5 = ) 10: " + value );
});

Example: Filter reject value:

var defer = $.Deferred(),
    filtered = defer.pipe( null, function( value ) {
      return value * 3;
    });

defer.reject( 6 );
filtered.fail(function( value ) {
  alert( "Value is ( 3*6 = ) 18: " + value );
});

Example: Chain tasks:

var request = $.ajax( url, { dataType: "json" } ),
    chained = request.pipe(function( data ) {
      return $.ajax( url2, { data: { user: data.userId } } );
    });

chained.done(function( data ) {
  // data retrieved from url2 as provided by the first request
});

deferred.progress()

notifications で実行されるコールバック関数を、Deferred オブジェクトに追加する

Usage: deferred.progress( progressCallbacks )

• progressCallbacks 関数、または関数の配列。
  Deferred オブジェクトへ progress notifications が送信された時に呼ばれる。

Returns: Deferred
Version: 1.7

引数には、関数、または関数の配列を渡す事ができる。 Deferred が notify、 notifyWith によって progress 通知を生成すると、progressCallbacks が呼び出される。 deferred.progress() は Deferred オブジェクトを返すので、 Deferred オブジェクトの他のメソッドをチェインできる。 Deferred が 'resolved', 'rejected' になった場合、 progressCallbacks はそれ以上呼び出されない。 詳細については Deferred オブジェクトのドキュメントを参照。

deferred.promise()

Deferred オブジェクトから Promise オブジェクトを生成する。

Usage: deferred.promise( [target] )

• target promise methods を追加するオブジェクト

Returns: Promise
Version: 1.5

deferred.promise() は非同期処理の関数が、他のコードが内部リクエストの進行やステータスと干渉する事を防止するための非同期関数です。 Promise は Deferred に必要な、追加のハンドラーや、状態を判定するメソッド(then, done, fail, always, pipe, progress, and state) のみ公開し、状態を決定するメソッド (resolve, reject, notify, resolveWith, rejectWith, and notifyWith) は公開しない。

ターゲットが指定されている場合、deferred.promise() は、新しいインスタンスを作成して返すのではなく、その上にメソッドを追加してから返す。 これは、すでに存在する Promise に新しい動作を追加するために使用する。

Deferred を制作者は、 任意の時点でで Deferred を 'rejected', 'resolved' にするための参照を保持する。 deferred.promise() を使い、 Promise オブジェクトのみを返す事によって、他のコードがはコールバック関数の登録と、状態を調べる事のみできるようになる。

詳細については Deferred オブジェクトのドキュメントを参照。

Examples:

Example:

Deferred と、ランダムな時間後に 'resolve', 'reject' のどちらかを返すタイマーベースの二つの関数を作成する。 最初に呼び出された方の処理のみが、一つのコールバックを呼び出す。 二つ目の timeout は、Deferred が一つ目の timeout によって既に解決 ( 'resolved', または 'rejected' へ) しているため、効果はない。 また、タイマーによる progress の通知処理により、 'working...'が body へ出力される。

function asyncEvent(){
    var dfd = new jQuery.Deferred();

    // Resolve after a random interval
    setTimeout(function(){
        dfd.resolve("hurray");
    }, Math.floor(400+Math.random()*2000));

    // Reject after a random interval
    setTimeout(function(){
        dfd.reject("sorry");
    }, Math.floor(400+Math.random()*2000));

    // Show a "working..." message every half-second
    setTimeout(function working(){
        if ( dfd.state() === "pending" ) {
            dfd.notify("working... ");
            setTimeout(working, 500);
        }
    }, 1);

    // Return the Promise so caller can't change the Deferred
    return dfd.promise();
}

// Attach a done, fail, and progress handler for the asyncEvent
$.when( asyncEvent() ).then(
    function(status){
        alert( status+', things are going well' );
    },
    function(status){
        alert( status+', you fail this time' );
    },
    function(status){
        $("body").append(status);
    }
);

####Example:

既存のオブジェクトを、 promise 関数への target 引数に指定し、 Promiseへ渡す。

// Existing object
var obj = {
  hello: function( name ) {
    alert( "Hello " + name );
  }
},
// Create a Deferred
defer = $.Deferred();

// Set object as a promise
defer.promise( obj );

// Resolve the deferred
defer.resolve( "John" );

// Use the object as a Promise
obj.done(function( name ) {
  obj.hello( name ); // will alert "Hello John"
}).hello( "Karl" ); // will alert "Hello Karl"

deferred.reject()

Deferred オブジェクトを reject し、与えられた引数を使い、Deferrd オブジェクトに登録された failCallback 関数を呼び出す。

Usage: deferred.reject( args )

• args Optional failCallbacks へ渡される引数。

Returns: Deferred
Version: 1.5

通常、 Deferred オブジェクトの制作者のみが呼び出す。 deferred.promise() を使い、Promise オブジェクトを生成する事で、他のコードが Deferred の状態を変更したり、通知する事を制限する事ができる。

deferred が 'reject' になると、 deferred.then、 deferred.fail によって追加された failCallbacks 関数が呼び出される。 コールバック関数は追加された順に実行される。 各コールバック関数には、 .reject() からの引数が渡される。 Deferred が 'rejected' 状態になった後に追加された failCallbacks 関数は、.reject() に渡されたパラメータを引数にして、即座に実行される。詳細については Deferred オブジェクトのドキュメントを参照。

deferred.rejectWith()

Deferred オブジェクトを reject し、与えられたコンテクスト(this)と引数を使い、Deferrd オブジェクトに登録された failCallback 関数を呼び出す。

Usage: deferred.rejectWith( context [, args] )

• context failCallbacks 内の this オブジェクトに渡されるオブジェクト
• args Optional failCallbacks へ渡す引数

Returns: Deferred
Version: 1.5

通常、 Deferred オブジェクトの制作者のみが呼び出す。 deferred.promise() を使い、Promise オブジェクトを生成する事で、他のコードが Deferred の状態を変更したり、通知する事を制限する事ができる。

deferred が 'reject' になると、 deferred.then、 deferred.fail によって追加された failCallbacks 関数が呼び出される。 コールバック関数は追加された順に実行される。 各コールバック関数には、 .reject() からの引数が渡される。 Deferred が 'rejected' 状態になった後に追加された failCallbacks 関数は、.reject() に渡されたパラメータを引数にして、即座に実行される。詳細については Deferred オブジェクトのドキュメントを参照。

deferred.resolve()

Deferred オブジェクトを resolve し、与えられた引数を使い、Deferrd オブジェクトに登録された doneCallback 関数を呼び出す。

Usage: deferred.resolve( args )

• args (Optional) doneCallbacks へ渡される引数。

Returns: Deferred
Version: 1.5

通常、 Deferred オブジェクトの制作者のみが呼び出す。 deferred.promise() を使い、Promise オブジェクトを生成する事で、他のコードが Deferred の状態を変更したり、通知する事を制限する事ができます。

deferred が 'resolved' になると、 deferred.then、 deferred.done によって追加された successCallbacks 関数が呼び出される。 コールバック関数は追加された順に実行される。 各コールバック関数には、 .resolve() からの引数が渡される。 Deferred が 'resolve' 状態になった後に追加された successCallbacks 関数は、.resolve() に渡されたパラメータを引数にして、即座に実行される。詳細については Deferred オブジェクトのドキュメントを参照。

deferred.resolveWith()

Deferred オブジェクトを resolve し、与えられたコンテクスト(this)と引数を使い、Deferrd オブジェクトに登録された doneCallback 関数を呼び出す。

Usage: deferred.resolveWith( context [, args] )

• context doneCallbacks 内の this に渡されるオブジェクト
• args Optional doneCallbacks へ渡す引数

Returns: Deferred
Version: 1.5

通常、 Deferred オブジェクトの制作者のみが呼び出す。 deferred.promise() を使い、Promise オブジェクトを生成する事で、他のコードが Deferred の状態を変更したり、通知する事を制限する事ができる。

deferred が 'resolved' になると、 deferred.then、 deferred.done によって追加された successCallbacks 関数が呼び出される。 コールバック関数は追加された順に実行される。 各コールバック関数には、 .resolve() からの引数が渡される。 Deferred が 'resolve' 状態になった後に追加された successCallbacks 関数は、.resolve() に渡されたパラメータを引数にして、即座に実行される。詳細については Deferred オブジェクトのドキュメントを参照。

deferred.state()

Deferred オブジェクトの現在の状態を返す。

Usage: deferred.state()
Returns: String
Version: 1.7

deferred.state() は Deferred オブジェクトの現在の状態を表す文字列を返す。返される文字列は以下の3つのうち一つ

• "pending": Deferredオブジェクトは終了していない ("rejected" でも "resolved"　でもない)
• "resolved": Deferredオブジェクトは deferred.resolve() か deferred.resolveWith() によって終了され、doneCallbacks が実行された。
• "rejected": Deferredオブジェクトは deferred.reject() か deferred.rejectWith() によって終了され、failCallbacks が実行された。

このメソッドは、例えば reject を意図していたにも関わらず、Deferred がすでに resolved になっていた用な場合のデバックに使用する。

deferred.then()

resolved, rejected, (または progress)状態へのコールバック関数を追加する。

Usage: deferred.then( doneCallbacks, failCallbacks [, progressCallbacks] )
Returns: Promise
Version: 1.5, 1.7

各引数 (progressCallbacks は jQuery1.7で追加された) は、関数か、関数の配列を受け取る。これらの引数は、コールバックを指定したくない場合は null を渡す事もできる。 コールバックを一つだけ指定したい場合は、代わりに .done(), .fail(), .progress() を使用する。

Deferred が resolved の場合に、 doneCallbacks、 rejected の場合、 failCallbacks が呼ばれる。 jQuery1.7 以降は、　Deferred が resolved, rejected になる前であれば deferred.notify()、 deferred.notifyWith() によって progressCallbacks を何度でも呼び出す事ができる。

コールバック関数は、登録した順番に呼び出される。deferred.then は Promise オブジェクトを返すので、then() メソッドを含む Promise オブジェクトのメソッドをチェインできる。

Example:

jQuery.get メソッドは、 Deferred オブジェクトの拡張である jqXHR メソッドを返すので、 .then メソッドを使い、ハンドラーを設定できる。

$.get("test.php").then(
    function(){ alert("$.get succeeded"); },
    function(){ alert("$.get failed!"); }
);

.promise()

jQuery 要素からのアクションを管理するための Promise オブジェクトを返す。

Usage: .promise( [type] [, target] )

• type 監視対象のキュータイプ
• targetObject promise methods を追加するオブジェクト

Returns: Promise
Version: 1.6

.promise() メソッドは、要素への特定のタイプの全てのアクションが完了したかを通知する Promise オブジェクトを返します。

デフォルトで、type は "fx" が指定されており、Promise オブジェクトが、要素のアニメーション全てが完了したかを判断する。

単独の引数で呼び出された場合、コンテキストは .promise() が呼ばれた要素セットになる。

target が指定されると、.promise() は、各メソッドを付加した新しいオブジェクトを生成する。これは、既に作成済みのオブジェクトに、新たな振る舞いを追加するために使用する。

Note: 返された Promise オブジェクトは、要素の .data() 内にある Deferred オブジェクトにリンクされる。 .remove() は要素だけではなく、要素内の data も削除するため、未解決の Promise オブジェクトが解決になる事を防ぐ。 Promise が解決される前に要素を削除したい場合は、代わりに .detach() を使用し、Promise の終了後に .removeData() を使用する。

Examples:

Example:

全てのアニメーション終了時に、Promise が解決される。
(アニメーション初期化後に追加された物や、コールバックも含めて)

<!DOCTYPE html>
<html>
<head>
  <style>
div {
  height: 50px; width: 50px;
  float: left; margin-right: 10px;
  display: none; background-color: #090;
}
</style>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
  
<button>Go</button>
<p>Ready...</p>
<div></div>
<div></div>
<div></div>
<div></div>


<script>
$("button").bind( "click", function() {
  $("p").append( "Started...");
  
  $("div").each(function( i ) {
    $( this ).fadeIn().fadeOut( 1000 * (i+1) );
  });

  $( "div" ).promise().done(function() {
    $( "p" ).append( " Finished! " );
  });
});
</script>

</body>
</html>

jQuery.when()

複数の非同期処理を汎用的に行うための Deferred オブジェクトに対してコールバック関数を実行する方法を提供する。

Usage: jQuery.when( deferreds )

• deferreds Deferred オブジェクト、または JavaScript オブジェクト。

Returns: Promise
Version: 1.5

jQuery.when に Deferred オブジェクトが一つ渡された場合、Deferred のサブセットである Promise オブジェクトが返される。 Promise オブジェクトに追加するメソッドは deferred.then のように、コールバック関数を呼び出す。 Deferred オブジェクトが 'resolved', または 'rejected' 状態の場合、作成元の Deferred オブジェクトのコールバック関数が直ちに実行される。 例としてk、 jQuery.ajax が 返す、 jqXHR オブジェクトは Deferred オブジェクトと同様、この用に使用できる

$.when( $.ajax("test.aspx") ).then(function(ajaxArgs){ 
     alert(ajaxArgs[1]); /* ajaxArgs is [ "success", statusText, jqXHR ] */
});

Deferred ではない引数が一つ、 jQuery.when に渡された場合、 'resolved' 状態の Deferred として扱われ、登録されている donneCallback が直ちに実行される。 この doneCallback関数には、元の引数が渡される。 この場合、Deferred が 'rejected' になる事は無いので、 failCallback が呼び出される事は無い。 例として

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

複数の Deferred オブジェクトが jQuery.when の引数に渡された場合、このメソッドは、全ての Deferred の状態を追跡する "マスター" Deferred からの Promise オブジェクトを返す。 マスターの Deferred が 'resolve' 状態になった際、可能な限り早く、すべの Deferred が 'resolve' になり、 'reject' の場合も可能な限り早く 'reject' に変更する。 マスターの Deferred が "resolved" になった際、 resolved への引数が全ての jQuery.when に追加された Deferred オブジェクトに渡される。 例えば、 Deferred が jQuery.ajax() リクエストで、引数が jqXHR オブジェクトである場合、引数は渡された順番になる。

複数の Deferred うちの一つが 'rejected' になった際、 jQuery.when は直ちにマスター Deferred のfailCallbacks を実行する。 Deferred のうちのいくつかは、その時点で未解決かもしれない事に注意すること。 この場合のように、未解決の ajax リクエストをキャンセルしたいような場合、 jqXHR オブジェクトへの参照をクロージャーで保持して、 failCallback　内からこれらの検査/キャンセル処理を行う。

Examples:

Example:

二つの ajax リクエストが成功した際に、関数を実行する。 (ajax リクエストの成功、失敗時については、 jQuery.ajax のマニュアルを参照)

$.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 */
   var jqXHR = a1[2]; /* arguments are [ "success", statusText, jqXHR ] */
   if ( /Whip It/.test(jqXHR.responseText) ) {
      alert("First page has 'Whip It' somewhere.");
   }
});

Example:

ajax がどちらも成功した際に myFunc を実行し、どちらかが失敗した場合に myFailure を実行する。

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