キーフレームの形式

構文

キーフレームの形式には、2 つの異なる方法があります。

1. 反復処理するプロパティと値からなるオブジェクト（キーフレーム）の配列 (array) です。これは getKeyframes() メソッドが返す正規の形式です。

   js

   element.animate(
     [
       {
         // from
         opacity: 0,
         color: "white",
       },
       {
         // to
         opacity: 1,
         color: "black",
       },
     ],
     2000,
   );
   

   各キーフレームのオフセットは offset 値を提供することで指定します。

   js

   element.animate(
     [{ opacity: 1 }, { opacity: 0.1, offset: 0.7 }, { opacity: 0 }],
     2000,
   );
   

   メモ: offset 値は指定された場合、0.0 から 1.0 の間で昇順に並んでいなければなりません。

   すべてのキーフレームにオフセットを指定する必要はありません。オフセットを指定しないキーフレームは、隣接するキーフレーム間で等間隔に配置されます。

   キーフレーム間に適用するイージングは、下記で示すように easing 値を提供することで指定します。

   js

   element.animate(
     [
       { opacity: 1, easing: "ease-out" },
       { opacity: 0.1, easing: "ease-in" },
       { opacity: 0 },
     ],
     2000,
   );
   

   この例では、指定したイージングは指定したキーフレームから次のキーフレームまでしか適用されません。しかし、引数 options で指定した easing 値は、アニメーションの単一の反復、つまり再生時間全体に適用されます。

2. オブジェクト (object) で、アニメーションさせるプロパティと、反復する値の配列 (array) からなるキーと値のペアを格納します。

   js

   element.animate(
     {
       opacity: [0, 1], // [ from, to ]
       color: ["white", "black"], // [ from, to ]
     },
     2000,
   );
   

   この形式を使用した場合、配列のそれぞれの要素数は同じである必要はありません。指定された値はそれぞれ独立した空間となります。

   js

   element.animate(
     {
       opacity: [0, 1], // offset: 0, 1
       backgroundColor: ["red", "yellow", "green"], // offset: 0, 0.5, 1
     },
     2000,
   );
   

   特別なキーである offset、easing、composite（下記で記述）をプロパティ値の横に並べて指定することができます。

   js

   element.animate(
     {
       opacity: [0, 0.9, 1],
       offset: [0, 0.8], // Shorthand for [ 0, 0.8, 1 ]
       easing: ["ease-in", "ease-out"],
     },
     2000,
   );
   

   プロパティ値のリストから適切なキーフレームの集合を生成した後、指定されたオフセットがそれぞれ対応するキーフレームに適用されます。値が足りない場合、またはリストに null 値が格納されている場合、オフセットを指定していないキーフレームは、記述されている配列形式と同様に等間隔に配置されます。

   もし easing や composite の値がいくつかある場合、対応するリストは必要に応じて繰り返されます。

暗黙の to/from キーフレーム

ブラウザーは、現在の状態に基づいてアニメーションの開始状態または終了状態を推測することができます。デフォルトで、単一のキーフレームが指定された場合、それは終了状態として扱われ、開始状態は要素の現在の計算済みスタイルから推測されます。ただし、offset を指定することで、指定されたキーフレームをアニメーションのタイムライン上のどの位置に配置するかを指定することができます。詳細は、Element.animate() を参照してください。

// 現在の状態から translateX(300px) へアニメーション
logo.animate({ transform: "translateX(300px)" }, 1000);
// translateX(300px) から現在の状態へアニメーション
logo.animate({ transform: "translateX(300px)", offset: 0 }, 1000);
// 現在の状態から translateX(300px) へアニメーションし、そこから現在の状態へ戻る
logo.animate({ transform: "translateX(300px)", offset: 0.5 }, 1000);

属性

キーフレームは、アニメーションの対象となる CSS プロパティのプロパティと値のペアを指定します。プロパティ名はキャメルケースを使用して指定しますので、例えば background-color は backgroundColor となり、background-position-x は backgroundPositionX となります。margin のような一括指定も使用できます。

例外的な CSS プロパティが 2 つあります。

• float は cssFloat と書く必要があります。"float" は JavaScript で予約語であるためです。ここでは参考程度のものです。"float" はアニメーション可能な CSS プロパティではなく、アニメーションには影響しないからです。
• offset は cssOffset と書く必要があります。"offset" は下記の通り、キーフレームのオフセットを表すからです。

以下の特殊な属性を指定することもできます。

offset

キーフレームのオフセットを 0.0 から 1.0 の間の数値、または null で指定します。これは CSS スタイルシートで @keyframes を使用して始まりと終わりの状態をパーセントで指定するのと同じです。この値が null または存在しない場合、キーフレームは隣接するキーフレーム間で等間隔に配置されます。

easing

連なった次のキーフレームまでの間で使用されるイージング関数です。

composite

このキーフレームで指定した値と基底値を合成するために用いる KeyframeEffect.composite 演算子です。効果に指定した合成処理を使用している場合は auto になります。

関連情報

• ウェブアニメーション API
• Element.animate()
• KeyframeEffect()
• KeyframeEffect.setKeyframes()