Deferred(延期された)オブジェクトは、未解決(pending)、解決(resolved)、棄却(rejected) のいずれかの状態を持つオブジェクトです。生成時は未解決(pending)の状態で、解決(resolved)または棄却(rejected)された時に何らかのアクションを起こしたい場合に利用されます。

var df = $.Deferred();                            // Deferredオブジェクトを生成する
df.done(function() { console.log("Done!"); });          // 解決されたらDone!を表示する
df.fail(function() { console.log("Fail!"); });          // 棄却されたらFail!を表示する
setTimeout(function() { df.resolve(); }, 3000);   // Deferredオブジェクトを3秒後に解決状態にする

done() や fail() も Deferredオブジェクトを返却するので、下記の様にも記述できます。

var df = $.Deferred();
df.done(function() { console.log("Done!"); })
  .fail(function() { console.log("Fail!"); });

$.get(), $.load(), $.ajax() などの Ajax関数が返却する jqXHRオブジェクトも、Deferredオブジェクトとして扱うことができます。

var df = $.get("xx2.htm");
df.done(function() { console.log("Done!"); })
  .fail(function() { console.log("Fail!"); });

$.when() を用いて、複数の非同期処理がすべて完了するのを待って、次のアクションを実行することが可能となります。

var df1 = $.get("xx.htm", function(data) {   // 非同期処理1(Ajax)
    console.log("DF1");
});
var df2 = $.Deferred();                      // 非同期処理2(Animation)
$("#box").animate({ width:"100px", height:"100px" }, 3000, function() {
    console.log("DF2");
    df2.resolve();
});
var df3 = $.Deferred();                      // 非同期処理3(Timeout)
setTimeout(function() {
    console.log("DF3");
    df3.resolve();
}, 1000);
$.when(df1, df2, df3)   // 非同期処理1,2,3すべてが完了したら COMPLETE! を表示する
    .done(function() { console.log("COMPLETE!"); })
    .fail(function() { console.log("FAIL"); });

Deferredオブジェクトを解決(resolved)状態にします。args には、done() や then() で指定するコールバック関数への引数を指定します。context には、コールバック関数で $(this) として参照されるコンテキストを指定します。

df.resolve(arg1, arg2, arg3);

Deferredオブジェクトを棄却(rejected)状態にします。args には、fail() や then() で指定するコールバック関数への引数を指定します。context には、コールバック関数で $(this) として参照されるコンテキストを指定します。

df.reject(arg1, arg2, arg3);

Deferredオブジェクトの状態を通知します。通知した際、Deferredオブジェクトの状態がまだ未解決(pending)の状態であれば、progress()で設定したコールバックが呼ばれます。

df.notify(arg1, arg2, arg3);

done()には Deferredオブジェクトが解決(resolved)状態になった時、fail() は棄却(rejected)状態になった時、progress() はオブジェクトが未解決(pending)の状態であるとnotify()によって通知された時、always() は解決(resolved)/棄却(rejected)いずれかの状態になった時に呼び出すコールバック関数を指定します。

var df = $.Deferred();
df.done(function(data, textStatus, jqXHR) {
    console.log("Done!");
  })
  .fail(function(jqXHR, textStatus, errorThrowed) {
    console.log("Fail!");
  })
  .progress(function(...args) {
    console.log("Progress!");
  })
  .always(function(data_or_jqXHR, textStatus, jqXHR_or_errorThrowed) {
    console.log("Always!");
  });

done(), fail(), progress() のコールバックを一度に指定します。

var df = $.Deferred();
df.then(
    function() { console.log("Done!"); },
    function() { console.log("Fail!"); },
    function() { console.log("Progress!"); }
);

Deferredオブジェクトが解決(resolved)状態にあるか、棄却(rejected)状態にあるか確認します。

if (df.isResolved()) { ... }
if (df.isRejected()) { ... }

Deferredオブジェクトの状態を "pending", "resolved", "rejected" のいずれかで返します。

console.log("status = " + df.state());

Deferredオブジェクトを参照する Promiseオブジェクトを生成します。Promiseオブジェクトは Deferredオブジェクトとほぼ同様の動作をしますが、resolve(), resolveWith(), reject(), rejectWith(), notify(), notifyWith() メソッドを呼び出せない点のみが異なります。関数の戻り値に Deferredオブジェクトの代わりに Promiseオブジェクトを返すことで、Deferredオブジェクトの状態が外部から勝手に変更されないように隠蔽します。target を指定した場合、新規に Primiseオブジェクトを生成する代わりに、targetオブジェクトに Promiseオブジェクトの機能を付加します。

// キッチンタイマーを作成する
function KitchenTimer(sec) {
    this.timer = sec;
    this.intervalId = null;
    this.deferred = $.Deferred();

    // 100ms毎にカウントダウンする
    this.countdown = function() {
        this.timer -= 100;
        this.deferred.notify();   // 100ms毎に progress() のコールバックを呼び出す
        if (this.timer <= 0) {
            clearInterval(this.intervalId);
            this.deferred.resolve();  // 完了したら解決(resolved)状態にする
        }
    };

    // カウントダウンを開始する
    this.start = function() {
        this.intervalId = setInterval(this.countdown.bind(this), 100);
    };

    this.deferred.promise(this);
    return this;
}

var timer = new KitchenTimer(3000);
timer.done(function() { console.log("Done!"); });
timer.progress(function() { console.log("."); });
timer.start();

すべてのアクションが完了するのを監視するための Promiseオブジェクトを生成し、返します。queueName にはキュー名を指定します。省略するとアニメーション用のキュー fx が参照されます。

$("#d1").fadeOut(3000).fadeIn(3000);
$("#d1").promise().done(function() {
    console.log("Complete!");
});

then() と同様、完了時、エラー発生時のコールバック関数を指定しますが、jQuery 1.8 で廃止されました。代わりに then() を使用してください。

複数の Deferredオブジェクトを監視し、すべてが解決(resolved)状態になった場合に done() のコールバックを呼び出します。一つでも棄却状態になると fail() のコールバックを呼び出します。詳細は $.Deferred() を参照してください。

$.when(df1, df2, df3)   // 非同期処理1,2,3すべてが完了したら COMPLETE! を表示する
    .done(function() { console.log("COMPLETE!"); })
    .fail(function() { console.log("FAIL"); });