jQuery リファレンス：animate( prop, option )

.animate( prop, option )オリジナルアニメーションの実行

構文

オリジナルアニメーションの実行返値：jQueryオブジェクト: jQo.animate( 属性 [,オプション] )ver1.0〜

上記構文のオプションはobjectオブジェクトで指定します。利用できるプロパティは以下の通りです。
・duration：目的の値までの期間をミリ秒で指定
・easing：アニメの加速度のタイプを指定
・queue：アニメをキューに追加するか以下かを指定
・step：アニメの期間に連続して実行するfunctionを指定
・complete：アニメの完了時に実行するfunctionを指定
・specialEasing：プロパティ（幅や高さなど）毎に個別のイージングを設定します。v1.4〜
以下はv1.8で追加されたDeferredに合わせて追加されました（functionの引数にpromiseオブジェクトがある）
・start：アニメが開始された時に実行するfunctionを指定
・progress：アニメの期間に連続して実行するfunctionを指定
・done：アニメが正常終了した時に実行するfunctionを指定
・fail：アニメが異常終了した時（stopされた時）に実行するfunctionを指定
・always：アニメの終了した時（正常/異常にかかわらず）に実行するfunctionを指定

機能

このanimate(prop, option)の構文はanimate(prop)の別構文です。ここではanimate(prop)と異なる機能をメインに説明するので、先にanimate(prop)を理解するようにして下さい。

animate(prop)との構文の違いは引数にあります。animate(prop)では属性の設定の後に引数をたくさん追加する形でしたが、animate(prop, option)では属性以外の設定についてもobjectオブジェクトにまとめて、第2引数に設定するようになっています。

また設定できる内容も大幅に増えました。ここでは利用頻度の高そうな2つのプロパティを簡単に紹介しておきます。1つはstepプロパティにfunctionを設定することで、アニメしている間に連続して実行できること。もう1つはqueueプロパティにfalseを設定して、アニメをキューに追加しないで直ちに実行できることです（デフォルトではjQueryのアニメは以下のキューという仕組みで順次再生されます）。

キュー（queue）: jQueryのアニメ処理は実行と同時に開始されるのではなく、キューと呼ばれる配列に格納されて順々に実行されます。つまり1つのアニメが完了してから次のアニメが開始されるのです。

アニメの間にfunctionを実行したり、キューに追加するなどをしない場合は、animate(prop)の方がシンプルに記述できるので、そちらを利用した方がよいでしょう。

解説

属性の設定はanimate(prop)の構文と同じです

属性の設定はanimate(prop)と同様に第1引数にobjectオブジェクトで設定します。
サンプル（animate2/01.html）を開いてbody内にdiv要素とbutton要素があることを確認してください。jQueryは以下の様に記述され、animateメソッドの引数にobjectオブジェクトが設定されています。

$("button").click(function(){
	$("div").animate({width:200, height:200});
});

結果として、buttonをクリックするとdiv要素の幅と高さがアニメで200pxになります。このようにoptionの設定をしなければanimate(prop)との構文と全く同じです。

属性以外の設定もobjectオブジェクトで

animate(prop)と異なるのは、属性以外の設定もobjectオブジェクトで行うという点です。このobjectは第2引数に設定します。サンプル（animate2/02.html）を開いてbody内の構成がanimate2/01.htmlと同じ事を確認してください。

jQueryでは、まず以下の様にオプションに設定するobjectオブジェクトが作成されているのを確認してください。以下ではdurationプロパティの値を1000にしています。これでアニメの期間が1秒（1000ミリ秒）になります。animate(prop)の構文と異なり、設定したいオプションの名称をきちんと覚えなければなりません。

var optionObj = new Object();
optionObj.duration = 1000;

objectオブジェクトを作成したら、以下の様にanimateメソッドの台に引数に設定するだけです。

$("button").click(function(){
	$("div").animate({width:200, height:200}, optionObj);
});

結果として、buttonをクリックするとdiv要素のアニメが1秒（1000ミリ秒）で実行されます。
objectオブジェクトは引数に直接設定することもできます。→サンプル（animate2/02b.html）

$("button").click(function(){
	$("div").animate({width:200, height:200}, {duration:1000});
});

animateメソッドではobjectオブジェクトを直接設定するのが一般的なのですが、それだと1行が長くなり見難くなるため、以降のサンプルではobjectオブジェクトを作成してから設定するようにしています。

イージングの設定

イージングの設定はオプションのobjectオブジェクトにeasingプロパティを追加します。ここでもjQueryが利用できるイージングは「swing」と「linear」の2種類しかありません。デフォルトは「swing」です。イージングの種類はプラグインを追加することで増やすことができます。

サンプル（animate2/03.html）を開いてbody内の構成がanimate2/02.htmlと同じ事を確認してください。jQueryもほとんどanimate2/02.htmlと同じで、異なるのは以下の様にオプションのobjectオブジェクトにeasingのプロパティが追加されているだけです。

var optionObj = new Object();
optionObj.duration = 1000;
optionObj.easing = "linear";

結果として、buttonをクリックすると「等速」でアニメが再生されます。違いが分かりにくいので、イージングの「swing」と「linear」を比較できるサンプルを作成しました。

サンプル（animate2/03b.html）ではbutton要素をクリックすると、id属性がswingと設定された方は「swing」のイージング、id属性がlinearと設定された方は「linear」のイージングで演出されます。あまり違いは分からないかもしれませんが、linearは等速で演出し、swingは徐々に加速後、徐々に減速します。

イージングについてはプラグイン（未完成）のページで紹介する予定です。

コールバックの設定

コールバックの設定はオプションのobjectオブジェクトにcompleteプロパティを追加し、その値に実行したいfunctionを設定します。サンプル（animate2/04.html）を開いてbody内の構成がanimate2/03.htmlと同じ事を確認してください。jQueryもほとんどanimate2/03.htmlと同じで、異なるのは以下の様にオプションのobjectオブジェクトにcompleteのプロパティが追加され、functionが代入されているだけです。

var optionObj = new Object();
optionObj.duration = 1000;
optionObj.easing = "linear";
optionObj.complete = function (){
	alert("Animation complete.")
}

結果として、buttonをクリックするとdiv要素が拡大し、アニメが完了するとアラートで「Animation complete.」と表示されます。

アニメ中の処理を設定

animate(prop,option)のメリットは、アニメの実行中に連続してfunctionを実行できることです。この設定はオプションのobjectオブジェクトにstepプロパティを追加し、その値に実行したいfunctionを設定します。

stepプロパティに設定できるfunctionは以下の様な構文になっており、2つの引数を利用できます。「fx」と記されたものは現在アニメしている属性のobjectオブジェクトで、要素や属性名の情報を持っています。

stepプロパティに設定するfunctionの構文: function (現在の属性の値, fx){
　※引数fxには要素名「elem」や属性名「prop」が含まれ、これらを利用することができます
　実行したい処理
}

サンプル（animate2/05.html）を開いてbody内の構成がanimate2/04.htmlと同じ事を確認してください。jQueryもほとんどanimate2/04.htmlと同じで、異なるのは以下の様にオプションのobjectオブジェクトにstepのプロパティが追加され、functionが代入されているだけです。

var optionObj = new Object();
optionObj.duration = 1000;
optionObj.easing = "linear";
optionObj.complete = function (){
	alert("Animation complete.")
}
optionObj.step = function (now, fx){
	var data = fx.prop + ": " + now + "<br />";
	$("body").append(data);
}

stepに設定したfunction内では引数fxのpropプロパティを利用し、アニメしている属性を取得しています。さらに引数nowを利用することで、操作している属性の現在の値を取得しています。

これらの値はappendメソッドを利用してbody内に追加していきます。このときwidthとheightの値が個別に追加されていることに注意して下さい。stepに設定されたfunctionは要素ごとにではなく「属性ごとに実行」されます。このサンプルではdiv要素は1つですが、widthとheightの2回分functionが実行されているのです。

キューへの追加設定

animateメソッドで設定したアニメはすぐに実行されるのではなく、キュー（queue）という仕組みに追加され管理されます。そのキューで1つずつ順にアニメが実行されていきます。

この仕組みが確認できるサンプル（animate2/06.html）を用意しました。開いてjQueryを確認してください。以下の様にbuttonをクリックしたら「左に移動するアニメ」と「下に移動するアニメ」を実行するようにしています。これだとbuttonをクリックすると「ナナメに移動して左下」に行きそうですが、実際は異なります。

$("button").click(function(){
	$("div").animate({left:200});
	$("div").animate({top:200});
});

buttonをクリックすると、最初「左に移動した」あとで「下に移動します」。これはanimateメソッドで作成したアニメがキューで管理され、１つずつ順に実行されるためです。

しかしanimate(prop,option)のqueueプロパティをfalseに設定することで、キューに追加せず「直ちにアニメを実行」することができます。サンプル（animate2/06b.html）を開いてjQueryを確認してください。2つ目のアニメの設定で、以下の様にqueueの値をfalseに設定しました。これで1つ目のアニメを待たずに2つ目のアニメが実行されます。

$("button").click(function(){
	$("div").animate({left:200});
	$("div").animate({top:200},{queue:false});
});

結果として、buttonをクリックするとdiv要素がナナメに移動します。しかし、ナナメに移動させたいのであればサンプル（animate2/06c.html）のように2つの属性をまとめてアニメするほうが分かりやすいでしょう。

$("button").click(function(){
	$("div").animate({top:200, left:200});
});

specialEasingとは

specialEasingを利用するとプロパティごとに個別のイージングを設定できます。これはanimate(prop)のメモ「属性ごとにイージングを設定する」で紹介したものの別構文と言えます。

サンプル（animate2/07.html）を開いてbody内の構成はanimate2/02.htmlと同じ事を確認してください。jQueryは以下の様にoptionObjにspecialEasingプロパティが追加されています。specialEasingプロパティにはobjectオブジェクトを設定し、イージングを設定したいプロパティ名（サンプルではwidthとheight）に対し、文字列でイージングの種類（サンプルではswingとlinear）を設定します。

var optionObj = new Object();
optionObj.duration = 1000;
optionObj.specialEasing = {width:"swing", height:"linear"};

結果として、buttonをクリックするとwidthにはswing、heightにはlinearのイージングでアニメします。デフォルトで利用できるswingとlinearでは違いが分かりにくいので、プラグイン「イージングの追加」で利用した「jQuery Easing Plugin」を利用して分かりやすいサンプルを作成しました。

サンプル（animate2/07b.html）を開いて以下の様にjquery.easingプラグインが追加されていることを確認してください。これで利用できるイージングが大幅に増えます。

<script type="text/javascript" src="css_js/jquery.easing.1.3.js"></script>

続いて以下の部分を確認してください。specialEasingプロパティのwidthの部分に「easeOutBounce」を設定しました。

var optionObj = new Object();
optionObj.duration = 1000;
optionObj.specialEasing = {width:"easeOutBounce", height:"linear"};

結果として、buttonをクリックするとwidthのアニメがバウンドするようなイージングで再生されます。

stopメソッドで停止された時の処理

animateメソッドを含む演出のメソッドにはv1.8でdeferred関連の機能が追加されました。これを利用すれば、stopメソッド等で停止させられた時の処理を設定できます。サンプル（animate2/08.html）を開いてbody内にstartとstop、2つのbuttonとdiv要素があることを確認してください。

<button id="start">start</button>
<button id="stop">stop</button>
<div></div>

jQueryでは、まず以下の部分を確認してください。stopボタンをクリックしたらstopメソッドを利用してdiv要素のアニメを停止します（1〜3行目）。startボタンをクリックしたらdiv要素をanimateメソッドで左から300pxの位置に移動します。そしてポイントなのは第2引数に設定されたanimeObjです。

$("#stop").click(function(){
	$("div").stop();
});
$("#start").click(function(){
	$("div").animate({left:300},animeObj)
});

animeObjの設定は以下の様になっています。ポイントなのはfailプロパティとdoneプロパティで、これらはdeferredオブジェクトのfailメソッドやdoneメソッドに関連したプロパティです。

var animeObj = new Object();
animeObj.duration = 3000;
animeObj.fail = function (){
	$("div").text("FAIL!")
}
animeObj.done = function (){
	$("div").text("DONE!")
}

failプロパティで設定した処理は、stopメソッドによって途中で停止されゴール地点に移動できなかった場合に実行されます。実際にstartボタンをクリックしてゴールに着く前にstopボタンをクリックしてください。div要素内に「FAIL!」と表示され、failプロパティで設定した処理が実行されるのが確認できます。

そしてdoneプロパティはで設定した処理は、ゴールにきちんと着いた時に実行されます。サンプルをリロードして再度startボタンをクリックしてください。今度はstopボタンをクリックせずに最後まで確認してください。ゴールに着いた時にdiv要素に「DONE!」と表示され、機能を確認できます。

stopメソッドを利用してもfailにならないケース

stopメソッドは第2引数にtrueを設定することで、アニメを停止して直ちにゴールに移動させることができます。この場合はstopメソッドを利用しても、きちんとゴールに到着するのでfailプロパティの処理は実行されません。サンプル（animate2/08b.html）を開いて、ほとんどanimate2/08.htmlと同じ事を確認してください。

異なるのは以下の様にstopメソッドに引数が設定されている点です。第2引数がtrueになっているためstopボタンをクリックするとアニメを停止してゴールに移動します。※第1引数は今回関係ありません

$("#stop").click(function(){
	$("div").stop(true,true);
});

実際にstartボタンをクリックした後で、stopボタンをクリックしください。div要素内には「DONE!」と表示され、failではなくdoneの処理が実行されるのが確認できます。つまりアニメにとってのfail（異常終了）とはゴールに到達しないことなのです。

promiseオブジェクトの利用

deferred関連のプロパティに設定するfunctionには引数としてpromiseオブジェクトが渡されます。あまり利用する機会は無いかもしれませんが、サンプルを作成しました。

サンプル（animate2/09.html）を開いてbody内の構成はanimate2/08.htmlと同じ事を確認してください。jQueryも殆ど同じなのですが、failプロパティやdoneプロパティの代わりにalwaysプロパティを利用しています。これはalwaysメソッドに関連したプロパティで処理の正常/異常のかかわらず、処理が終了したら実行される処理を設定します。

animeObj.always = function(myPromise){
	var chk = myPromise.state();
	$("div").text(chk)
};

そしてポイントはfunctionの引数に渡されるpromiseオブジェクト（サンプルでは変数myPromiseで受け取っています）です。今回はstateメソッドを利用して状態を取得し、結果をdiv要素内に表示するようにしました。

実際にstartボタンをクリックしてアニメの正常終了を待ってください。ゴールに着くとalwaysプロパティで設定した処理が実行され、stateメソッドによってpromiseオブジェクトの状態が表示されます。deferredオブジェクトの正常終了の値は「resolved」なので、この値がdiv要素に表示されます。

ページをリロードして、もう一度startボタンをクリックしてください。今度はアニメが終わる前にstopボタンをクリックしてアニメを停止させてください。この場合は異常終了となりdiv要素には「rejected」と表示されます。

Deferredオブジェクトの状態に関してはdeferredメソッドのページを確認してください。

アニメ前に実行する処理を設定

あとdeferredならではのプロパティとして「start」があります。これを利用すればアニメを開始する前に実行する処理を設定することができます。サンプル（animate2/10.html）を開いてbody内からstopボタンが削除されているのを確認してください（このサンプルではstopボタンを利用しません）。

jQueryではanimeObjが以下の様に設定されています。startプロパティに設定した処理でdiv要素の背景色をピンクに変更し、doneプロパティに設定下処理でdiv要素の背景色を青に戻しています。

var animeObj = new Object();
animeObj.duration = 1000;
animeObj.start = function(){
	$("div").css("background-color","#f9c")
};
animeObj.done = function(){
	$("div").css("background-color","#09C")
};

結果としてstartボタンをクリックすると、div要素の色がピンクになりゴールに着くと青に戻ります。

メモ

属性の設定についてはanimate(prop)の構文と同じテクニックが利用できます

animate(prop)のメモの部分で、属性の設定について色々なテクニックを紹介しています。例えばキーワードに「toggle」を利用したり、属性ごとに個別のイージングを設定したり等です。

animate(prop, option)の構文は、属性の設定についてはanimate(prop)と全く同じなので、同じテクニックが利用できます。重複になるので、ここでは「toggle」のキーワードで個別にイージングを設定するサンプルだけを紹介します。

サンプル（animate2/test01.html）では以下の様に、widthにはswingのイージング、heightにはlinearのイージングを設定しています。そして値に「toggle」を利用しているので、buttonをクリックする度にdiv要素が隠れたり表示したりします。

$("button").click(function(){
	$("div").animate({width:["toggle","swing"], height:["toggle","linear"]}

	, {duration:1000});
});

次のページ： stop()