とほほのjQuery入門

トップ > jQuery > Deferred

Deferred

◆ $.Deferred() (1.5)

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

JavaScript
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オブジェクトを返却するので、下記の様にも記述できます。

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

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

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

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

JavaScript
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.resolve([args]) (1.5)
deferred.resolveWith(context[, args]) (1.5)

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

JavaScript
df.resolve(arg1, arg2, arg3);
deferred.reject([args]) (1.5)
deferred.rejectWith(context[, args]) (1.5)

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

JavaScript
df.reject(arg1, arg2, arg3);
deferred.notify([args]) (1.5)
deferred.notifyWith(context[, args]) (1.5)

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

JavaScript
df.notify(arg1, arg2, arg3);
deferred.done(callback(data, textStatus, jqXHR)[, callback]) (1.5)
deferred.fail(callback(jqXHR, textStatus, errorThrowed)[, callback]) (1.5)
deferred.progress(callback(...args)[, callback]) (1.7)
deferred.always(callback(data_or_jqHXR, textStatus, jqXHR_or_errorThrowed)[, callback]) (1.6)

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

JavaScript
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!");
  });
deferred.then(doneCallback, failCallback) (1.5/廃止:1.8)
deferred.then(doneCallback, failCallback[, progressCallback]) (1.7/廃止:1.8)
deferred.then(doneCallback[, failCallback][, progressCallback]) (1.8)

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

JavaScript
var df = $.Deferred();
df.then(
    function() { console.log("Done!"); },
    function() { console.log("Fail!"); },
    function() { console.log("Progress!"); }
);
deferred.catch(callback(...args)) (3.0)

Deferredオブジェクトが棄却(rejected)状態になった時に呼び出すコールバック関数を指定します。fail() とほぼ同等のものですが、引数の形式、および、JavaScript の最新仕様に合わせて若干処理が異なります。

JavaScript
$.get('test.html')
.fail(jqXHR, textStatus, errorThrowed) {
  ...
})
.catch(function(...args) {
  const [jqXHR, textStatus, errorThrowed] = args;
  ...
});
deferred.isResolved() (1.5)
deferred.isRejected() (1.5)

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

JavaScript
if (df.isResolved()) { ... }
if (df.isRejected()) { ... }
deferred.state() (1.7)

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

JavaScript
console.log("status = " + df.state());
deferred.promise([target]) (1.5)

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

JavaScript
// キッチンタイマーを作成する
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();
obj.promise([queueName][, target]) (1.6)

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

JavaScript
$("#d1").fadeOut(3000).fadeIn(3000);
$("#d1").promise().done(function() {
    console.log("Complete!");
});
deferred.pipe([doneCallback][, failCallback]) (1.6/廃止:1.8)
deferred.pipe([doneCallback][, failCallback][, progressCallback]) (1.7/廃止:1.8)

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

◆ $.when(deferreds) (1.5)

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

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

Copyright (C) 2013-2019 杜甫々
初版:2013年2月3日、最終更新:2019年5月5日
http://www.tohoho-web.com/js/jquery/deferred.htm