詳細

.animate()は CSS プロパティの値を アニメーションさせる(連続で変更する)ことができます。 第一引数は必須で、アニメーションさせたい CSS プロパティと アニメーション完了後の値(目的値)からなるプレーンオブジェクトを 指定します。

// 要素 element の幅と高さをそれぞれ現在値から300px, 400px に
// 400ミリ秒でアニメーションさせる場合
$( element ).animate({ width: "300px",
                       height:"400px"  });

プロパティと値について

基本的には単純な数値を持つ CSS プロパティを指定します。 jQuery の基礎的な使い方では複雑な値を持つ CSS プロパティを アニメーションすることはできません。例えば、width, left などのプロパティはアニメーションできますが、 background-color などはそのままではアニメーションさせることは できません。 jQuery Color プラグインを使うなどの追加処置が必要になります。

省略形の CSS プロパティは一部サポートされています。 padding, margin, borderWidth はサポートされています( 1.7.2 から)が、font や background などは サポートされてないようです(1.9.1 時点)。

// 要素 element の padding をそれぞれ現在値から50px, 0, 0, 100px に、
// border-width をそれぞれ現在値から10px, 5px, 15px, 20px に
// 400ミリ秒でアニメーションさせる場合
// (※あらかじめ border-style をデフォルトの none 以外にする必要がある)
$( element ).animate({ padding: "50px 0 0 100px",
                       borderWidth:  "10px 5px 15px 20px" });

値には数値を指定します。 値の単位には、em や % 、px が指定できます。 指定しない場合はピクセル数(px)とみなされます。

数値の他に文字列"show","hide", "toggle"を指定できます。 "show"は対象の要素が非表示の時にだけ、 0(width, height の場合は1)から 現在の値へのアニメーションを、要素を表示してから行います。

// 要素 element の padding をそれぞれ 0 から現在値, 0, 0, 現在値 に、
// width を 1 から 現在値 に400ミリ秒でアニメーションさせる場合
// (※element を display:none などで非表示にしておく必要がある)
$( element ).animate({ padding: "show 0 0 show",
                       width:  "show"  });

"hide"は対象の要素が表示されている場合のみ、 現在の値から0へのアニメーションを行い、 完了後に要素を非表示にして、さらにプロパティの値を アニメーション前の状態に復元します。

// 要素 element の margin をそれぞれ 現在値 から 0 に、
// height を 現在値 から 0 に400ミリ秒でアニメーションして
// その後非表示となる
// (※element が display:node などで非表示でない場合に実行される)
$( element ).animate({ margin: "hide 0 0 hide",
                       height: "hide" });
// アニメーション後、margin, height の値は現在値に戻る

"toggle"は対象の要素が表示されている場合は "hide"に、非表示の場合は"show"に なります。開閉するアニメーションなどに役立つと思われます。

値に"+="や"-="で始まる文字列を 指定することで、 現在値からの相対指定をすることができます。

// 要素 element の padding をそれぞれ
// 現在値 から 現在値+10px, 0, 0, 現在値+20px に、
// width を 現在値 から 現在値-100px に400ミリ秒でアニメーションする
  $( element ).animate({ padding: "+=10px 0 0 +=20px",
                         width:  "-=100px"  });

※.slideDown()などのメソッドと異なり、 .animate()はその目的値に"show", "hide", "toggle"を指定しない限り、 要素の表示・非表示を変更することはありません (というより.slideDown()などの実体は "show","hide", "toggle"を使用した.animate()です)。

// 要素 element は非表示のまま
// width を 現在値 から 300px に400ミリ秒でアニメーションする
$( element ).hide().animate({ width: "300px" });

duration について

duration にはアニメーションが開始して完了するまでの時間を 設定します。ミリ秒単位です。大きい値を指定すると遅く、 小さい値を指定すると速くなります。 デフォルトは400(ミリ秒)です。 文字列"fast"は200、 "slow"は600と同じ意味になります。

complete 関数について

complete に指定した関数は、 アニメーション完了直後や、.stop()で 目的値まで飛ばして終了させた直後、もしくは .finish()(1.9 から)の直後に実行されます。 この関数のthisにはアニメーションした DOM 要素が入ります。
complete 関数は要素ごとに実行されるので注意してください。 つまり、複数の要素を持つ jQuery オブジェクトで .animate()を実行すると、指定した complete 関数は それらの要素の数だけ実行されます。

// 要素 element と element2 は width を 現在値 から 300px に、
// height を 現在値 から 400px に 800ミリ秒でアニメーションし、
// 完了後指定した関数が2回実行される
$( [element, element2] )
  .animate({ width: "300px", height: "400px" },  800,
           function(){
             // 2回実行する
           });

1.8 から、complete 関数にも 下の done コールバックと同じ引数が渡されるようになりました。

done, fail, always, progress 関数について

1.8 から、オプションとして done, fail, always, progress というコールバック関数が設定できます。 complete 関数と同じく、要素ごとに実行されます。 コンテキスト(this)はアニメーションさせる DOM 要素です。 done は complete 関数と同じタイミングで実行されます。 fail は.stop()でその場で アニメーションを停止した時に実行されます。 always は done, fail の両方の場合に実行されます。

done(complete), fail, always には第一引数に animation オブジェクト(アニメーションに関する情報を持った Promise オブジェクト)、第二引数にはアニメーションの終了状況を示す 値が渡されます。第二引数の値がundefinedの場合は アニメーションが自然終了したことを示し、trueの場合は .stop()で目的値まで飛ばして終了させたことを 示し、falseの場合は.stop()で目的値まで 飛ばさずその場で終了させたことを示します。

// 要素 element は width を 現在値 から 現在値-100px に
// 400ミリ秒でアニメーションし、途中で .stop() されない場合は
// done と always が実行される
$( element ).animate(
  { width:  "-=100px" },
  {
    done: function( animation, goToEnd ){
      // goToEnd は undefined か true
    },
    fail: function( animation, goToEnd ){
      // goToEnd は false
    },
    always: function( animation, goToEnd ){
      // goToEnd は undefined か true か false
    }
  });

animation オブジェクトは以下のようなプロパティを持っています。 (※animation オブジェクトについては現在のところ ドキュメント化されてません。 そのため告知なく変更される恐れがありますので 使用は自己責任でお願いします)

elem

DOM 要素。アニメーションする要素

props

Object。アニメーションするプロパティとそれぞれの目的値

opts

Object。アニメーションのオプション

originalProperties

Object。キャメライズ化や easing の処理が施される前の、 jQuery.Animation()に渡した時の オリジナルのプロパティオブジェクト

originalOptions

Object。prefilter の処理が施される前の、 jQuery.Animation()に渡した時の オリジナルのオプションオブジェクト

startTime

Number。アニメーションを開始した時刻。 new Date()した時に返される数値で表される

duration

Number。アニメーションする期間。ミリ秒単位

progress は step 関数と同じくステップごとに実行されますが、 プロパティごとではなく要素ごとに実行され、また CSS プロパティの 更新後(しかしまだ再描画はされていないだろうタイミング)に 実行されます。step 関数と同じく独自なアニメーションを 作成するのに利用できます。 第一引数に animation オブジェクト、第二引数に アニメーションの進捗状況を表す0から 1までの値(0が開始時点で 1が終了時点)、第三引数にアニメーション完了までの 残りミリ秒数が渡されます。

// 要素 element は width を 現在値 から 現在値-300px に
// 400ミリ秒でアニメーションしようとするが、
// progress コールバックにより、width を 0 から 100px に、
// height を 400px から 0 にアニメーションするよう上書きされる
$( element ).animate(
  { width:  "-=300px" },
  {
    progress: function( animation, percent, remaining ){
      $( this ).css({ width: (percent * 100) + "px",
                      height: remaining + "px"        });
    }
  });

step 関数について

jQuery のアニメーションは今のところ(1.9.1)は setInterval()を使って jQuery.fx.intervalで指定したミリ秒ごとに CSS プロパティを更新することで実現しています。

この CSS プロパティの更新をステップとここではいいます。 そして、オプション step に関数を指定すると、 その関数(step 関数)は アニメーションのステップごとに、 要素の CSS プロパティの値が更新される前のタイミングで 実行されます。

step 関数のコンテキスト(this)には アニメーションさせる DOM 要素が、引数には アニメーション中のプロパティの現在値と jQuery.Tween オブジェクト(1.8 未満では jQuery.fx オブジェクト)が渡されます。

jQuery.Tween オブジェクトにはアニメーションに関する情報が プロパティとして保持されていて、以下のようなプロパティが 含まれています。

elem

アニメーションさせる DOM 要素

prop

アニメーションさせるプロパティ名

easing

適用する easing 関数の名前

options

.animate()に指定したオプション(duration 等)を 保持するオブジェクト

start

アニメーションの開始値

end

アニメーションの目的値

unit

アニメーションさせる値に指定する単位

now

アニメーションさせる値の現在値

state

現在のアニメーションの進捗状況を表す0から 1までの値。0が開始時点で 1が終了時点。 1.8 以降で無くなってしまった。 代替として、下の pos を利用する方法がある。

pos

easing 関数を適用後の値。 easing を linear に指定すると上の state と同じになる。

第二引数の Tween オブジェクトの now プロパティの値を 変更することでアニメーションの挙動を変更することが できます。 (now プロパティなどの Tween オブジェクトの プロパティなどについては現在のところ ドキュメント化されてません。 そのため告知なく変更される恐れがありますので 使用は自己責任でお願いします)

// 要素 element は width を 現在値 から 現在値-300px に
// 400ミリ秒でアニメーションしようとするが、
// step 関数により、width を200px から 400px に、
// height を 100px から 200px にアニメーションする
$( element ).animate({ width:  "-=300px" }, {
    easing: "linear",  // tween.pos を進捗状況にするため
    step: function( now, tween ){
      tween.now = 200 + tween.pos * 200;
      $( this ).css({ height: (100 + tween.pos * 100) + "px" });
    }
  });

step 関数は要素ごと、プロパティごと(さらにいうと Tween オブジェクトごと)に実行されます。 例えば、2つの要素を持つ jQuery オブジェクトが .animate()で2つの CSS プロパティを アニメーションさせた場合、その.animate()で 指定した step 関数はステップごとに4回実行することになります。 どの要素の、どのプロパティを更新中かを判別するには、 例えば 第二引数に渡される Tween オブジェクトの elem プロパティと prop プロパティを利用します。

easing について

オプション easing には easing 関数の名前を文字列で指定します。 easing 関数は、アニメーションの開始地点から目的地点までの 進み方を定義します。

jQuery で実装されている easing 関数はデフォルトの swing と linear の2つです。 jQuery UI などのプラグインで easing 関数を追加することができます。 jQuery.easingオブジェクトに追加することで 自前で easing 関数を追加することもできます。

// 要素 element は marginLeft を 現在値 から 現在値+100px に
// 400ミリ秒でアニメーションしようとする。
// 独自の easing 関数を指定して、徐々に速度を上げるような
// 動きをするアニメーションにしている
$.easing["myEasing"] = function(p){
  return p * p * p;
};
$( element ).animate({ marginLeft:  "+=100px" },
                     { easing: "myEasing" }   );

プロパティごとの easing

1.4 から、プロパティごとに easing 関数を設定することが できるようになりました。

一番目の用法 (.animate( properties [, duration] [, easing] [, complete] )) でプロパティごとに指定するには、まず CSS プロパティの値に配列を指定し、そしてその配列の 先頭要素に CSS プロパティの目的値を、 次の要素に easing 関数名を指定します。

// 要素 element は marginLeft と marginTop を 現在値 から
// 現在値+100px に400ミリ秒でアニメーションしようとする。
// marginLeft は上で定義した独自の easing 関数を指定して、
// marginTop は linear を指定している
$( element ).animate({ marginLeft: ["+=100px", "myEasing"],
                       marginTop:  ["+=100px", "linear"]   });

二番目の用法(.animate( properties, options ))では、 第二引数の options オブジェクトの specialEasing プロパティで指定します。 specialEasing プロパティには CSS プロパティと 対応する easing 関数名からなるオブジェクトを指定します。

// 上と同じアニメーションの specialEasing を使った形式
$( element ).animate(
  { marginLeft: "+=100px", marginTop:  "+=100px" },
  { specialEasing: { marginLeft: "myEasing",
                     marginTop:  "linear"    } }    );

easing 設定の優先順位は、高い順に プロパティごとの設定、第三引数や easing プロパティでの指定、 デフォルト(swing) となります。

エフェクトキューについて

.animate()を実行すると、queue オプションを falseにしない限り、 アニメーションを実行する関数(doAnimation() とします)が エフェクトキューに格納されます。 このキューは要素ごとに作成されます。例えば要素１、要素２を 保持した jQuery オブジェクトで.animate()を 実行した場合、要素１と要素２のそれぞれのエフェクトキューに doAnimation() が格納されます。

1.7 から、queue オプションで格納先のキューを 指定できるようになりました。 queue オプションで格納先を指定しない場合は デフォルトのエフェクトキュー(デフォルトキュー)に格納されます。

エフェクトキューに doAnimation() が格納される際、 その要素で他のアニメーションが実行中でなければ、 キューに格納された直後にその doAnimation() が実行されます (※デフォルトキューのみの挙動です。デフォルト以外の エフェクトキューについてはこの場合.dequeue() する必要があります)。 その要素に対するアニメーションが他に実行中の場合は 即座に実行されずそのままキューに格納され、 先に定義したアニメーションが 順番に全て実行され完了するまで待ってから実行されます。

// 要素 element の4つのプロパティは同時にアニメーションせずに
// ひとつずつ順番にアニメーションする
$( element )
  .animate({ marginLeft: "+=100px" })
    .animate({ marginTop: "+=100px" })
      .animate({ paddingLeft: "+=100px" })
        .animate({ paddingTop: "+=100px" });
// 4つのプロパティを同時にアニメーションするには
// 同じ .animate() 内で定義する
$( element )
  .animate({ marginLeft:  "+=100px", marginTop:  "+=100px",
             paddingLeft: "+=100px", paddingTop: "+=100px" });

.clearQueue()を使うとエフェクトキューを空にして、 待機中のアニメーションを取り消すことができます(実行中の アニメーションに対しては.stop()を使います)。

$( element )
  .animate({ marginLeft: "+=100px" })
  // ↑キューは空なので即座に実行する
    .animate({ marginTop: "+=100px" })
    // ↑アニメーションが実行中なのでキューで待機
      .animate({ paddingLeft: "+=100px" })
      // ↑アニメーションが実行中なのでキューで待機
        .clearQueue()
        // ↑待機中のアニメーションをキューから削除。この時
        //   アニメーションの実行中を示す番兵も削除
          .animate({ paddingTop: "+=100px" });
          // ↑キューは空なので即座に実行する
// 結果、marginLeft, paddingTop が同時にアニメーションする

その他

jQuery.fx.off

jQuery.fx.offをtrueにすると、 .animate()を実行してもアニメーションせずに 一瞬で目的値に移動するようになります。 これは、duration を0に設定した時と 同じ動きになります。元に戻すには jQuery.fx.offをfalseにします。

jQuery.fx.interval

jQuery.fx.intervalには、jQuery の アニメーションで CSS プロパティを更新する間隔(ミリ秒単位)が 設定されています。 ブラウザの性能によりますが、少なくするとより滑らかに、 大きくするとカクカクに動くようになります。 デフォルトは13です。

このプロパティへの変更は、 一度エフェクトが何も走っていない状態にならないと 反映されません。また、 このプロパティは jQuery のエフェクト全般に影響を及ぼすので 変更する際は注意してください。

1.6.0 から 1.6.2 でアニメーションの実装に使用された requestAnimationFrameはブラウザ側で 不具合があったため、現在(1.9.1)のところ使用されていません。