.promise()

http://api.jquery.com/promise/

Promiseオブジェクトを返します。このオブジェクトは要素に紐づけられているキューなどのアクションが全て終了するかどうかを監視します。

.promise( [type] [, target] ) 1.6追加

戻り値:Promise

引数	説明
type	監視に必要なキュータイプを指定します。
target	promiseメソッドを割り当てるオブジェクトを指定します。

.promise()メソッドは動的に生成されたPromiseを返し、これはコレクション(キューされたものもそうでないものも)へバインドされた特定のtypeの全アクションが終了されると解決されます。

デフォルトのtypeは"fx"であり、これは選択された要素の全てのアニメーションが完了した際に、返されたPromiseが解決されることを意味します。

コンテキストの解決でコールバック関数に渡される唯一の引数は、.promise()が呼び出されたコレクションになります。

targetが提供された場合、.promise()はそれにメソッドを割り当て、新しいものを作るのではなく、そのオブジェクトを返します。これは既に存在するオブジェクトへPromiseの挙動を割り当てるのに便利です。

注意: 返されたPromiseはDeferredオブジェクトにリンクされ、要素の.data()上に格納されます。そのため、.remove()メソッドは要素自身と同様に要素のdataも削除するため、未解決のPromiseの解決を妨げることになります。もし、Promiseが解決される前にDOMからその要素を削除する必要がある場合は、代わりに.detach()を使用し、解決後に.removeData()してください。

デモ

アクティブなアニメーションの無い(要素の)コレクション上で.promise()を使用すると、解決済みのPromiseが返されます。

var div = $( "<div />" );

div.promise().done(function( arg1 ) {
  // 即座に実行され、アラートダイアログで「true」と表示します。
  alert( this === div && arg1 === div );
});

全てのアニメーションが完了すると、返されていたPromiseが解決します。 (アニメーションのコールバックで開始されたもの、後から開始されたものも含みます)

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>promise demo</title>
  <style>
  div {
    height: 50px;
    width: 50px;
    float: left;
    margin-right: 10px;
    display: none;
    background-color: #090;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<button>Go</button>
<p>Ready...</p>
<div></div>
<div></div>
<div></div>
<div></div>
 
<script>
$( "button" ).on( "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>

$.when()式を使用して、返されたPromiseを解決しています。 (.promise()メソッドは、jQueryコレクションでこれを行うことを可能にします。)

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>promise demo</title>
  <style>
  div {
    height: 50px;
    width: 50px;
    float: left;
    margin-right: 10px;
    display: none;
    background-color: #090;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<button>Go</button>
<p>Ready...</p>
<div></div>
<div></div>
<div></div>
<div></div>
 
<script>
var effect = function() {
  return $( "div" ).fadeIn( 800 ).delay( 1200 ).fadeOut();
};
 
$( "button" ).on( "click", function() {
  $( "p" ).append( " Started... " );
 
  $.when( effect() ).done(function() {
    $( "p" ).append( " Finished! " );
  });
});
</script>
 
</body>
</html>