Web アニメーション

1. はじめに

// アニメーションの中間地点までシークし、opacity が 50% であることを確認する
for (const animation of elem.getAnimations()) {
  const { delay, activeDuration } = animation.effect.getComputedTiming();
  animation.currentTime = delay + activeDuration / 2;
}
assert.strictEqual(getComputedStyle(elem).opacity, '0.5');

// アニメーション完了後に読み込み画面が非表示になっていることを確認する
for (const animation of elem.getAnimations()) {
  animation.finish();
}
// イベントハンドラーが実行される機会を得られるように1フレーム待機する
requestAnimationFrame(() => {
  assert.strictEqual(
    getComputedStyle(document.querySelector('#loading')).display, 'none');
});

2. 仕様上の表記規則

この仕様では、まず アニメーションや アニメーション効果などの抽象的な概念、および それらに属する 再生 速度や 反復 持続時間などのプロパティについて説明する。 これらのプロパティに加え、多くの場合、 再生速度を設定する手順や、 アニメーションの 開始 時刻を設定する手順など、 これらのプロパティを更新するための特定の手順が存在する。

この仕様が特定の手順へのリンクを明示していない場合、 「animation の 開始時刻を 未解決にする」のように、 ユーザーエージェントにプロパティの更新を要求するテキストは、 関連する手順を呼び出すことなく、プロパティを直接更新することを 意味すると解釈するものとする。

この仕様に固有ではないその他の文書上の表記規則については、 文書の表記規則で説明する。

3. Web Animations モデルの概要

この節は非規範的である

概観すると、Web Animations モデルは、大部分が 独立した2つの部分、すなわちタイミングモデルとアニメーション モデルから構成される。それぞれの役割は次のとおりである:

タイミングモデル

ある時点を受け取り、それをアニメーションの単一の反復内における 比例距離である反復 進行度に変換する。 アニメーションによっては反復するたびに変化するため、 反復インデックスも記録される。

アニメーションモデル

タイミングモデルによって生成された反復進行度の値と反復インデックスを受け取り、 それらを対象プロパティに適用する 一連の値へ変換する。

この流れは図示すると次のように表せる:

たとえば、次のようなアニメーションを考える:

• 3秒後に開始する

• 2回実行される、

• 毎回2秒かかり、

• 矩形の幅を50ピクセルから100ピクセルに変更する。

最初の3つの点はタイミングモデルに適用される。 6秒の時点では、アニメーションが 2回目の反復の中間まで進んでいると計算され、結果として 0.5 が生成される。 次にアニメーションモデルがその情報を使用して幅を計算する。

この仕様では、まずタイミングモデルを扱い、その後 アニメーションモデルへ進む。

4. タイミングモデル

この節では、Web Animations タイミングモデルの動作について説明し、定義する。

4.1. タイミングモデルの概要

この節は非規範的である

Web Animations のタイミングモデルを特徴付ける機能は2つある。それはステートレスであり、 階層的である。

4.1.1. ステートレス

Web Animations のタイミングモデルは、入力時刻を受け取り、 出力となる反復進行度を生成することで動作する。 出力は入力時刻のみに基づき、 以前の入力から独立しているため、このモデルはステートレスであると説明できる。 これにより、このモデルには次の特性がある:

フレームレートに依存しない

出力は以前の入力から独立しているため、 モデルが更新される頻度はその進行に影響しない。 入力時刻が現実世界の時間の進行に比例している限り、 アニメーションは、それを実行するデバイスの能力にかかわらず、 同一の速度で進行する。

方向に依存しない

入力の順序は重要ではないため、このモデルには 方向性がない。 つまり、特別な処理を必要とせずに、 任意の時点へモデルを更新できる。

定数時間でのシーク

各入力はその前の入力から独立しているため、 はるか未来へのシークであっても、 シーク操作に必要な処理は少なくとも潜在的には一定時間で済む。

タイミングモデルのステートレスな動作には、 いくつかの例外がある。

第一に、モデルのプログラミングインターフェイスで定義される多数のメソッドは、 アニメーションの一時停止などの再生制御を提供する。 これらのメソッドは呼び出された時刻に基づいて定義されるため、 状態を持つ。 これらのメソッドは主として利便性のために提供され、 中核となるタイミングモデルの一部ではなく、その上位層として実装される。

同様に、アニメーションの終了動作により、 アニメーションのメディア（関連付けられた効果）の終了時刻を動的に変更すると、 変更が発生する時点によって異なる結果が生じる可能性がある。 この動作は多少望ましくないものではあるが、 直感的で HTML と一貫していると判断されている。 その結果、このモデルを真にステートレスと説明できるのは、そのタイミングプロパティに動的な変更がない場合に限られる。

最後に、モデルが更新されるたびに、 一時的な状態が確立されると考えることができる。 この一時的な状態はプログラミングインターフェイスから返される値に影響するが、 その後の更新には影響しないため、 上述したステートレスな性質とは矛盾しない。

4.1.2. 階層的

タイミングモデルのもう1つの特徴は、時間が継承されることである。 時間はタイムラインから始まり、いくつかの段階を経て、 各アニメーション効果へ流れていく。 各段階では、時間を前後に移動したり、拡大縮小したり、 反転、一時停止、反復したりできる。

このレベルの仕様では、階層は浅い。 この仕様の後続レベルでは、より深いタイミング階層を可能にする グループ効果の概念が導入される。

4.2. 時間値

タイミングは、タイミングノード間の時間関係の階層に基づく。 親ノードは、子ノードに対して 時間値の形式でタイミング情報を提供する。

時間値は、名目上、 ある時点からのミリ秒数を表す実数である。 時間値と実時間のミリ秒との関連は、 値が時間階層を通過する際に適用される任意の数の変換によって 不明瞭になる場合がある。

将来、スクロール位置 または UI ジェスチャーに基づくタイムラインが存在する可能性があり、その場合、時間値と ミリ秒との関連はさらに弱くなる。

時間値は、たとえば タイミングノードが 時間値を生成できる状態にない場合には、 未解決であることもある。

4.3. タイムライン

タイムラインは、同期を目的として 時間値の供給源を提供する。

任意の時点で、タイムラインは、 タイムラインの 現在時刻と単に呼ばれる、 単一の現在の 時間値を持つ。

タイムラインは、常に意味のある 時間 値を返せるとは限らず、未解決の時間値しか返せない場合がある。 たとえば、文書の load イベントの発火など、 まだ発生していない時点を基準として定義される場合がある。 タイムラインは、 その 時間値が 未解決である場合、 非アクティブであると見なされる。

タイムラインは、その報告された 現在 時刻が、以前に報告された 現在時刻以上である場合、 単調 増加である。

特定の種類の タイムラインでは、 時間 値 time について、 タイムライン時刻を オリジン相対時刻に変換する手順を定義でき、それにより実時間ベースのタイムラインによって生成された 時間 値を比較できる。

タイムラインは、 文書に関連付けられている場合がある。

Document doc について、タイムスタンプ now で アニメーションを更新してイベントを送信するよう求められた場合、 次の手順を実行する:

1. now をタイムスタンプとして渡し、 doc に関連付けられているすべての タイムラインの 現在時刻を更新する。

   タイミングモデルの階層的な性質により、タイムラインの 現在時刻を更新することには、 次の処理も含まれる:

   • タイムラインに関連付けられている任意の アニメーションの 現在時刻を更新する。

   • 現在時刻が更新された任意の アニメーションについて、アニメーションの完了 状態を更新する手順を実行する。

   • そのようなアニメーションについて、アニメーションイベントをキューに入れる。

2. doc について置換されたアニメーションを削除する。

3. マイクロタスクチェックポイントを実行する。

   注: これは、前の手順でタイムラインを更新する一環として Promise オブジェクトを解決または拒否した結果としてキューに入れられた マイクロタスクが、アニメーションイベントを配送する前にコールバックを実行することを保証するためである。

4. events to dispatch を、doc の 保留中の アニメーションイベント キューのコピーとする。

5. doc の 保留中のアニメーションイベントキューを空にする。

6. events to dispatch 内の アニメーションイベントを、次のように安定ソートする:

   1. イベントをその 予定イベント時刻でソートし、 より早く発生するよう予定されていたイベントが、 より遅く発生するよう予定されたイベントより前に並ぶようにし、 予定イベント時刻が 未解決であるイベントは、 解決済みの予定イベント時刻を持つイベントより前に並ぶようにする。

   2. 同じ 予定イベント時刻を持つイベントの中では、 その 合成順序によってソートする。

   注: イベントをソートする目的は、 能力が異なり、その結果フレームレートも異なるデバイス上でも、 可能な限りイベントが一貫した順序で配送されることを保証することである。

   注: ソートを安定ソートとする要件は、 同じ予定イベント時刻でイベントがキューに入れられる場合があるためである。たとえば、持続時間がゼロの CSS アニメーションは、animationstart イベントと animationend イベントの両方を配送する場合があり、 これらのイベントの順序は維持されるべきである。

7. 前の手順で確立された順序を使用して、events to dispatch 内の各イベントを、それぞれ対応する対象に配送する。

この手順が呼び出されるたびに新しい アニメーション フレームが確立される、と説明すると便利なことが多い。 アニメーションまたは アニメーション効果のタイミングプロパティの変更、 あるいはオブジェクトの追加や削除により、タイミングモデルまたは アニメーションモデルの出力が変化する場合があるが、これらの操作自体は 新しい アニメーションフレームを作成するのではなく、 単に現在の アニメーション フレームを更新するだけである。

4.3.1. 文書タイムライン

文書タイムラインは、 文書に関連付けられている タイムラインの一種であり、その 現在時刻は、 アニメーションを 更新してイベントを送信する手順が実行されるたびに提供される now タイムスタンプからの固定オフセットとして計算される。 この固定オフセットは、文書タイムラインの オリジン時刻と呼ばれる。

"origin time" より適切な 用語があるはずである— "time origin" とあまりにも似ている。 [Issue #2079]

関連付けられた文書の 時刻起点が確立される前は、 文書タイムラインは 非アクティブである。

文書 タイムラインが アクティブになった後は、単調 増加となる。

Document に関連付けられており、その Document が アクティブな文書ではない 文書タイムラインも、 非アクティブであると見なされる。

文書タイムライン timeline について、 タイムライン 時刻 timeline time をオリジン相対時刻に変換するには、 timeline time と timeline の オリジン 時刻の合計を返す。timeline が非アクティブである場合は、未解決の 時間値を返す。

4.3.2. 既定の文書タイムライン

各 Document には、既定の文書タイムラインと呼ばれる 文書 タイムラインがある。 既定の文書タイムラインは各文書に固有であり、 document.open() [HTML] の呼び出しを含め、文書の存続期間全体にわたって存続する。

既定の文書タイムラインの オリジン時刻はゼロである。

4.4. アニメーション

アニメーションは、 関連付けられた効果と呼ばれる単一の アニメーション 効果を、タイムラインに接続し、 再生制御を提供する。 これら2つの関連付けはいずれも省略可能かつ設定可能であり、 アニメーションは 任意の時点で 関連付けられた効果または タイムラインを持たない場合がある。

アニメーションの タイミング用文書は、 その タイムラインが 関連付けられている Document である。 アニメーションがタイムラインに関連付けられていない場合、またはそのタイムラインが 文書に関連付けられていない場合、そのアニメーションには タイミング用文書はない。

アニメーションの 開始時刻は、その 関連付けられた効果の 再生開始が予定されている時点における、その タイムラインの 時間値である。 アニメーションの開始時刻は、初期状態では 未解決である。

アニメーションはさらに、 一時停止などの状況で、アニメーションの出力 時間値、すなわちその 現在時刻を固定するために使用される 保持時刻という 時間値も保持する。 保持時刻は、 初期状態では 未解決である。

競合する アニメーションの相対的な順序を確立するため、 アニメーションは作成された順序で グローバルアニメーションリストに追加される。ただし、特定の アニメーションの クラスでは、アニメーションを順序付ける別の手段が提供される場合がある （§ 5.4.1 アニメーションクラスを参照）。

4.4.1. アニメーションのタイムラインの設定

アニメーション animation のタイムラインを、null であってもよい new timeline に設定する手順は、 次のとおりである:

1. old timeline を、存在する場合は animation の現在の タイムラインとする。

2. new timeline が old timeline と同じオブジェクトである場合、 この手順を中止する。

3. animation の タイムラインを new timeline とする。

4. animation の 開始 時刻が 解決済みである場合、animation の 保持時刻を 未解決にする。

   注: この手順により、 animation の 完了再生状態が 「固定」されることなく、更新された 現在時刻に基づいて再評価されることが保証される。

5. did seek フラグを false、synchronously notify フラグを false に設定して、 animation について アニメーションの完了状態を更新する手順を実行する。

4.4.2. アニメーションに関連付けられた効果の設定

アニメーション animation に関連付けられた効果を、null であってもよい new effect に設定する手順は、次のとおりである:

1. old effect を、存在する場合は animation の現在の 関連付けられた効果とする。

2. new effect が old effect と同じオブジェクトである場合、 この手順を中止する。

3. animation に 保留中の一時停止タスクがある場合、 animation が 準備完了になり次第実行されるよう、そのタスクを再スケジュールする。

4. animation に 保留中の再生タスクがある場合、animation が new effect を再生する準備が整い次第実行されるよう、そのタスクを再スケジュールする。

5. new effect が null ではなく、 new effect が別の アニメーション previous animation の 関連付けられた効果である場合、 previous animation に対して new effect として null を渡し、 アニメーションに 関連付けられた効果を設定する手順（この手順）を実行する。

6. animation の 関連付けられた効果を new effect とする。

7. did seek フラグを false、synchronously notify フラグを false に設定して、 animation について アニメーションの完了状態を更新する手順を実行する。

4.4.3. アニメーションの現在時刻

アニメーションは、 その 関連付けられた 効果に、アニメーションの 現在時刻と呼ばれる 時間値を提供する。

現在 時刻は、次のうち最初に一致する条件から計算される:

4.4.4. アニメーションの現在時刻の設定

アニメーションの 現在 時刻は、新しい値に設定してアニメーションをシークできる。 現在時刻を設定する手順は2つの部分で定義される。

アニメーション animation の現在時刻を seek time に サイレントに設定する手順は次のとおりである:

1. seek time が 未解決の時間値である場合、 次の手順を実行する。

   1. 現在時刻が 解決済みである場合、 TypeError を投げる。

   2. これらの手順を中止する。

2. animation の 保持時刻または 開始時刻のいずれかを 次のように更新する:

   次の条件のいずれかが真である場合:

   • animation の 保持時刻が 解決済みである、または

   • animation の 開始時刻が 未解決である、または

   • animation に関連付けられた タイムラインがないか、 関連付けられた タイムラインが 非アクティブである、または

   • animation の 再生速度が 0 である、

   animation の 保持時刻を seek time に設定する。

   それ以外の場合、

   animation の 開始時刻を、 timeline time - (seek time / 再生速度) を評価した結果に設定する。ここで timeline time は、 animation に関連付けられた タイムラインの現在の 時間値である。

3. animation に関連付けられた タイムラインがないか、関連付けられた タイムラインが 非アクティブである場合、 animation の 開始時刻を 未解決にする。

   これにより、アクティブなタイムラインがない場合には、 開始時刻またはアニメーションの 現在時刻のいずれか一方しか設定できない、 という不変条件が維持される。

4. animation の 以前の現在時刻を 未解決にする。

アニメーション animation の 現在時刻を設定する手順は、 seek time に対して次のとおりである:

1. animation の現在時刻を seek time に サイレントに設定する手順を実行する。

2. animation に 保留中の一時停止タスクがある場合、 次の手順を実行して一時停止操作を同期的に完了する:

   1. animation の 保持時刻を seek time に設定する。

   2. animation に 保留中の再生速度を適用する。

   3. animation の 開始時刻を 未解決にする。

   4. 保留中の一時停止タスクをキャンセルする。

   5. animation の 現在の ready promiseを animation で解決する。

3. did seek フラグを true、synchronously notify フラグを false に設定して、 animation について アニメーションの完了状態を更新する手順を実行する。

4.4.5. アニメーションの開始時刻の設定

アニメーション animation の 開始 時刻を設定する手順は、new start time に対して 次のとおりである:

1. timeline time を、animation が関連付けられている タイムラインの現在の 時間値とする。 animation に関連付けられた タイムラインがない場合、 または関連付けられたタイムラインが 非アクティブである場合、 timeline time を 未解決とする。

2. timeline time が 未解決であり、new start time が 解決済みである場合、 animation の 保持時刻を 未解決にする。

   これにより、アクティブなタイムラインがない場合には、 開始時刻またはアニメーションの 現在時刻のいずれか一方しか設定できない、 という不変条件が維持される。

3. previous current time を、animation の 現在時刻とする。

   注: これは、前の手順による変更を適用した後の 現在時刻であり、 その変更によって現在時刻が 未解決になる場合がある。

4. animation に 保留中の再生速度を適用する。

5. animation の 開始時刻を new start time に設定する。

6. animation の 保持時刻を、次のうち最初に一致する 条件に基づいて更新する。

   new start time が 解決済みである場合、

   animation の 再生速度がゼロでない場合、 animation の 保持時刻を 未解決にする。

   それ以外の場合（new start time が 未解決）、

   previous current time が 未解決であっても、 animation の 保持時刻を previous current time に設定する。

7. animation に 保留中の再生タスクまたは 保留中の一時停止 タスクがある場合、そのタスクをキャンセルし、 animation の 現在の ready promiseを animation で解決する。

8. did seek フラグを true、synchronously notify フラグを false に設定して、 animation について アニメーションの完了状態を更新する手順を実行する。

4.4.6. 関連付けられた効果の待機

アニメーションは、次の条件が両方とも真となる最初の時点で 準備完了となる:

• ユーザーエージェントが、アニメーションの 関連付けられた効果の再生を開始するために必要な すべてのセットアップを完了していること。これには、任意の キーフレーム 効果の最初のフレームのレンダリングも含まれる。

• アニメーションが、非アクティブではない タイムラインに関連付けられていること。

4.4.7. 現在の ready promise

各 アニメーションには、 現在の ready promiseがある。 現在の ready promiseは、初期状態では、アニメーション自身を値として 新しい解決済み Promise を作成する手順を使用して作成され、 アニメーションの 関連する Realmで作成された、解決済みの Promise である。

このオブジェクトは、アニメーションが以前には保留中のタスクを持っていなかった状態から、 保留中の再生 タスクまたは 保留中の一時停止タスクをキューに入れるたび、あるいはアニメーションがキャンセルされるたび （§ 4.4.14 アニメーションのキャンセルを参照）に、 新しい Promise オブジェクトに置き換えられる。

animation.pause();
animation.ready.then(function() {
  // 'running' と表示する
  alert(animation.playState);
});
animation.play();

4.4.8. アニメーションの再生

フラグ auto-rewind が与えられたときに、アニメーション animation を 再生する手順は、 次のとおりである:

1. aborted pause を、animation に 保留中の一時停止 タスクがある場合は true、そうでない場合は false となる真偽値フラグとする。

2. has pending ready promise を、初期値が false の 真偽値フラグとする。

3. seek time を、初期状態では 未解決である 時間値とする。

4. auto-rewind フラグが true である場合、存在するなら、 次のうち最初に一致する条件に対応する手順を実行する:

   animation の 実効再生速度 ≥ 0 であり、 animation の 現在時刻が次のいずれかである場合:

   • 未解決、または

   • ゼロ未満、または

   • 関連付けられた効果の終端以上、

   seek time をゼロに設定する。

   animation の 実効再生速度 < 0 であり、 animation の 現在時刻が次のいずれかである場合:

   • 未解決、または

   • ゼロ以下、または

   • 関連付けられた効果の終端より大きい、

   関連付けられた効果の終端が正の無限大である場合、

   "InvalidStateError" DOMException を投げ、 これらの手順を中止する。

   それ以外の場合、

   seek time を animation の 関連付けられた効果の終端に設定する。

5. 次の3つの条件がすべて満たされる場合:

   • seek time が 未解決であり、かつ

   • animation の 開始時刻が 未解決であり、かつ

   • animation の 現在時刻が 未解決である、

   seek time をゼロに設定する。

   注: 上記の手順により、 auto-rewind フラグの設定に関係なく、この手順がアイドル状態のアニメーションを 再生することが保証される。

6. has finite timeline を、animation に関連付けられた タイムラインがあり、 それが 単調増加ではない場合に true とする。

7. seek time が 解決済みである場合、

   has finite timeline が true である場合、

   1. animation の 開始時刻を seek time に設定する。

   2. animation の 保持時刻を 未解決とする。

   3. animation に保留中の再生 速度を適用する。

   それ以外の場合、

   animation の 保持時刻を seek time に設定する。

8. animation の 保持時刻が 解決済みである場合、その 開始時刻を 未解決とする。

9. animation に 保留中の再生タスクまたは 保留中の一時停止タスクがある場合、

   1. そのタスクをキャンセルする。

   2. has pending ready promise を true に設定する。

10. 次の4つの条件がすべて満たされる場合:

    • animation の 保持時刻が 未解決であり、かつ

    • seek time が 未解決であり、かつ

    • aborted pause が false であり、かつ

    • animation に 保留中の再生 速度がない、

    この手順を中止する。

11. has pending ready promise が false である場合、 animation の 現在の ready promiseを、 animation の 関連する Realm内の 新しい promiseとする。

12. animation が 準備完了になり次第実行されるタスクをスケジュールする。 そのタスクは次の手順を実行しなければならない:

    1. animation の 開始時刻または 保持 時刻の少なくとも一方が 解決済みであることを表明する。

    2. ready time を、animation が 準備完了になった瞬間に、 animation に関連付けられていた タイムラインの 時間値とする。

    3. 存在する場合、次のうち最初に一致する条件に対応する手順を実行する:

       animation の 保持時刻が 解決済みである場合、

       1. animation に保留中の 再生速度を適用する。

       2. new start time を、 animation について ready time - 保持時刻 / 再生速度 を評価した結果とする。 再生速度がゼロである場合、new start time を単に ready time とする。

       3. animation の 開始時刻を new start time に設定する。

       4. animation の 再生速度が 0 でない場合、 animation の 保持 時刻を 未解決にする。

       animation の 開始時刻 が解決済みであり、animation に 保留中の再生速度がある場合、

       1. current time to match を、 animation について (ready time - 開始時刻) × 再生速度 を評価した結果とする。

       2. animation に保留中の 再生速度を適用する。

       3. animation の 再生速度がゼロである場合、 animation の 保持 時刻を current time to match とする。

       4. new start time を、 animation について ready time - current time to match / 再生速度 を評価した結果とする。 再生速度がゼロである場合、new start time を単に ready time とする。

       5. animation の 開始時刻を new start time に設定する。

    4. animation の 現在の ready promiseを animation で解決する。

    5. did seek フラグを false、 synchronously notify フラグを false に設定して、 animation について アニメーションの完了 状態を更新する手順を実行する。

       上記2つの手順の順序が重要であることに注意。 これにより、長さがゼロの 関連付けられた 効果を持つアニメーションは、その 現在の ready promiseを、現在の finished promiseより先に解決する。

    上記のタスクがスケジュールされているが、まだ実行されていない間、 animation は 保留中の 再生タスクを持つと説明される。 ただし、タスクの実行中は、animation は 保留中の再生 タスクを持たない。

    ユーザーエージェントが animation が直ちに 準備完了であると判断した場合、 上記のタスクをマイクロタスクとしてスケジュールし、次の マイクロタスクチェックポイントで実行されるようにしてもよいが、 タスクを同期的に実行してはならない。

    上記の 保留中の再生タスクを非同期に実行するという要件により、 次のようなコードが実装間で一貫して動作することが保証される:

    animation.play();
    animation.ready.then(
      () => { console.log('Playback commenced'); },
      () => { console.log('Playback was canceled'); }
    );
    // 何らかの条件によって再生をキャンセルする必要があるとする...
    animation.cancel();
    // "Playback was canceled" がコンソールに出力される。
    

    上記のコードで、保留中の再生タスクが同期的に実行された場合、 現在の ready promiseは拒否されないことになる。

13. did seek フラグを false、synchronously notify フラグを false に設定して、 animation について アニメーションの完了状態を更新する手順を実行する。

4.4.9. アニメーションの一時停止

アニメーションが 未解決の 開始時刻を持つ場合、 その 現在 時刻は停止する。

アニメーションを 再生する場合と同様に、一時停止も即座には起こらない場合がある （§ 4.4.6 関連付けられた効果の待機を参照）。 たとえば、アニメーションが別のプロセスによって実行される場合、 アニメーションプロセスによって描画された状態を反映することを保証するため、 現在時刻を同期する必要がある場合がある。

アニメーション animation を 一時停止する手順は、 次のとおりである:

1. animation に 保留中の一時停止タスクがある場合、これらの手順を中止する。

2. animation の 再生 状態が 一時停止中である場合、 これらの手順を中止する。

3. seek time を、初期状態では 未解決である 時間値とする。

4. has finite timeline を、animation に関連付けられた タイムラインがあり、 それが 単調増加ではない場合に true とする。

5. animation の 現在時刻が 未解決である場合、 次のうち最初に一致する条件に従って手順を実行する:

   animation の 再生速度が ≥ 0 である場合、

   seek time をゼロに設定する。

   それ以外の場合、

   animation の 関連付けられた効果の終端が正の 無限大である場合、

   "InvalidStateError" DOMException を投げ、 これらの手順を中止する。

   それ以外の場合、

   seek time を animation の 関連付けられた効果の 終端に設定する。

6. seek time が 解決済みである場合、

   has finite timeline が true である場合、

   animation の 開始時刻を seek time に設定する。

   それ以外の場合、

   animation の 保持時刻を seek time に設定する。

7. has pending ready promise を、初期値が false の 真偽値フラグとする。

8. animation に 保留中の再生タスクがある場合、そのタスクをキャンセルし、 has pending ready promise を true とする。

9. has pending ready promise が false である場合、 animation の 現在の ready promiseを、 animation の 関連する Realm内の 新しい promiseに設定する。

10. 次の条件が両方とも真になる、可能な限り早い時点で実行されるタスクをスケジュールする:

    • ユーザーエージェントが、存在する場合は animation の 関連付けられた 効果の再生を停止するために必要な処理を行っていること。

    • アニメーションが、非アクティブではない タイムラインに関連付けられていること。

    そのタスクは次の手順を実行しなければならない:

    1. ready time を、ユーザーエージェントが animation の 関連付けられた効果の再生を停止するために必要な 処理を完了した瞬間に animation に関連付けられていた タイムラインの時間値とする。

    2. animation の 開始時刻が 解決済みであり、その 保持 時刻が解決済みではない場合、 animation の 保持時刻を、 (ready time - 開始時刻) × 再生速度 を評価した結果とする。

       注: アニメーションが 完了している場合、 またはアニメーションに 保留中の再生タスクがある場合、 保持時刻は すでに設定されていることがある。 どちらの場合も、一時停止中状態に入る際、 保持 時刻を維持したい。

    3. animation に保留中の再生速度を適用する。

    4. animation の 開始時刻を未解決にする。

    5. animation の 現在の ready promiseを animation で解決する。

    6. did seek フラグを false、 synchronously notify フラグを false に設定して、 animation について アニメーションの完了 状態を更新する手順を実行する。

    上記のタスクがスケジュールされているがまだ実行されていない間、 animation は 保留中の 一時停止タスクを持つと説明される。 ただし、タスクの実行中は、animation は 保留中の一時停止 タスクを持たない。

    保留中の再生タスクと同様に、ユーザーエージェントは 保留中の 一時停止タスクを非同期に実行しなければならない。ただし、それは次の マイクロタスクチェックポイントと同じくらい早くてもよい。

11. did seek フラグを false、 synchronously notify フラグを false に設定して、 animation について アニメーションの完了状態を更新する手順を実行する。

4.4.10. 終端への到達

この節は非規範的である

DVD プレーヤーやカセットプレーヤーは通常、媒体の終端に到達するまで 再生を続け、終端に到達すると停止する。 そのようなプレーヤーが逆方向に再生できる場合、 通常は媒体の先頭に到達すると再生を停止する。 この動作を模倣し、HTML の メディア要素 [HTML] との一貫性を提供するため、 Web Animations のアニメーションの 現在時刻は、 その 関連付けられた効果の 終了 時刻を超えて順方向に再生されたり、時刻ゼロより前へ逆方向に再生されたりしない。

再生範囲の自然な境界に到達したアニメーションは、 完了したと言う。

現在時刻を制限する効果を図示すると、次のようになる。

ただし、アニメーションの 現在時刻を、 関連付けられた効果の終端より後の時刻へ シークすることは可能である。 その場合、現在時刻は進行しないが、 アニメーションはシークされた時刻で一時停止されたかのように動作する。

これにより、たとえば、関連付けられた効果を持たないアニメーションの 現在時刻を 5s にシークできる。 後で、5s より後の 終了時刻を持つ 関連付けられた効果が そのアニメーションに関連付けられた場合、再生は 5s の位置から開始される。

上記のシナリオと同様の動作は、 アニメーションの 関連付けられた効果の長さが変化したときにも生じる場合がある。

同様に、再生 速度が負の場合、現在時刻は時刻ゼロより前には進まない。

4.4.11. 現在の finished promise

各アニメーションには 現在の finished promiseがある。 現在の finished promiseは、初期状態では保留中の Promise オブジェクトである。

このオブジェクトは、アニメーションが 完了再生状態を離れるたびに、 新しい promiseに置き換えられる。

4.4.12. 完了状態の更新

正の 再生速度を持つアニメーションでは、 現在 時刻は、関連付けられた効果の終端に達するまで増加し続ける。

アニメーションの 関連付けられた効果の 終端は、アニメーションの 関連付けられた効果の 終了 時刻に等しい。 アニメーションに 関連付けられた効果がない場合、 関連付けられた効果の 終端はゼロである。

負の 再生速度を持つアニメーションでは、 現在 時刻はゼロに達するまで減少し続ける。

この境界に到達した（または越えた）実行中のアニメーションで、 解決済みの 開始時刻を持つものは、 完了したと言う。

この境界を越えることは、アニメーションオブジェクトが変更されるたびに、 以下で定義される アニメーションの完了 状態を更新する手順を使用して確認される。この手順は、アニメーションを 更新してイベントを送信する手順の一部としても実行される。どちらの場合も、以下で定義する did seek フラグは false に設定される。

各アニメーションについて、ユーザーエージェントは、初期状態では 未解決である 以前の現在 時刻という 時間値を保持する。

通常の再生中は、 アニメーションの 現在 時刻は上述の境界に制限されるが、 アニメーションの 現在時刻を設定する手順を使用して、 アニメーションの現在時刻をそれらの境界外の時刻へシークすることが可能である。

animation について、 did seek フラグ（現在 時刻を設定する後に更新が実行されているかどうかを示す）と、 synchronously notify フラグ（完了イベントのキューイングと finished promise の解決が、該当する場合に直ちに起こることを期待するコンテキストで 更新が呼び出されたことを示す）が与えられた場合に、 アニメーションの完了状態を更新する手順は、 次のとおりである:

1. unconstrained current time を、 did seek が false の場合に 保持 時刻を 未解決の時間値で置き換えて、 現在時刻を計算した結果とする。 did seek が true の場合、unconstrained current time は 現在時刻に等しい。

   注: これは、方向が変化する可能性のあるタイムラインに対応するために必要である。 この定義がなければ、一度完了したアニメーションは、 そのタイムラインが反対方向へ進行した場合でも完了したままとなる。

2. 次の3つすべての条件が真である場合、

   • unconstrained current time が 解決済みであり、かつ

   • animation の 開始時刻が 解決済みであり、かつ

   • animation が 保留中の再生タスクまたは 保留中の一時停止タスクを持たない、

   存在する場合、animation について次のうち最初に一致する条件に基づき、 animation の 保持時刻を更新する:

   再生速度 > 0 かつ unconstrained current time が 関連付けられた効果の 終端以上である場合、

   did seek が true の場合、保持時刻を unconstrained current time の値とする。

   did seek が false の場合、保持時刻を 以前の現在時刻と 関連付けられた効果の終端のうち最大の値とする。 以前の現在時刻が 未解決である場合、 保持時刻を 関連付けられた 効果の終端とする。

   再生速度 < 0 かつ unconstrained current time が 0 以下である場合、

   did seek が true の場合、保持時刻を unconstrained current time の値とする。

   did seek が false の場合、保持時刻を 以前の現在時刻とゼロのうち最小の値とする。 以前の現在時刻が 未解決である場合、 保持時刻をゼロとする。

   再生速度 ≠ 0 であり、animation が アクティブなタイムラインに関連付けられている場合、

   次の手順を実行する:

   1. did seek が true かつ 保持時刻が 解決済みである場合、 animation の 開始時刻を、 timeline time - (保持時刻 / 再生速度) を評価した結果に等しいものとする。ここで timeline time は、 animation に関連付けられた タイムラインの 現在の 時間値である。

   2. 保持時刻を 未解決とする。

3. animation の 以前の現在時刻を、その 現在時刻を計算した結果とする。

4. animation の 再生 状態が 完了である場合、current finished state を true とする。 それ以外の場合は false とする。

5. current finished state が true であり、 現在の finished promiseがまだ解決されていない場合、次の手順を実行する:

   1. 完了通知手順を、次の手順を指すものとする:

      1. animation の 再生状態が 完了に等しくない場合、 これらの手順を中止する。

      2. animation の 現在の finished promiseオブジェクトを animation で解決する。

      3. AnimationPlaybackEvent finishEvent を作成する。

      4. finishEvent の type 属性を finish に設定する。

      5. finishEvent の currentTime 属性を animation の 現在時刻に設定する。

      6. finishEvent の timelineTime 属性を、animation が関連付けられている タイムラインの 現在時刻に設定する。 animation がタイムラインに関連付けられていない場合、またはタイムラインが 非アクティブである場合、 timelineTime を null とする。

      7. animation に タイミング用文書がある場合、 finishEvent を、その タイミング用文書の 保留中のアニメーション イベントキューに、その対象 animation とともに追加する。 予定イベント時刻には、 animation の 関連付けられた効果の終端を オリジン相対時刻に変換した結果を使用する。

         それ以外の場合、animation に finishEvent を 配送するためのタスクを キューに入れる。 このタスクのタスクソースは、DOM 操作タスク ソースである。

   2. synchronously notify が true である場合、 この animation について 完了通知手順を実行するためにキューに入れられた マイクロタスクをすべてキャンセルし、完了 通知 手順を直ちに実行する。

      それ以外の場合、synchronously notify が false なら、 animation について 完了通知手順を実行するためのマイクロタスクが まだキューに入っていない場合に限り、その手順を実行するための マイクロタスクを キューに入れる。

6. current finished state が false であり、animation の 現在の finished promiseがすでに解決済みである場合、 animation の 現在の finished promiseを、animation の 関連する Realm内の 新しい promiseに設定する。

var animation = elem.animate({ left: '100px' }, 2000);
animation.playbackRate = 2;
animation.currentTime = 1000; // animation は現在完了している
animation.effect.updateTiming({ iterations: 2 }); // animation はもう完了していない

var animation = elem.animate({ left: '100px' }, 1000);
animation.finish(); // finish イベントは直ちにキューに入れられ、finished promise は
                    // 次の文によってアニメーションが完了状態を離れるにもかかわらず
                    // 解決される
animation.currentTime = 0;

4.4.13. アニメーションの完了

アニメーションは、以下で定義する animation について アニメーションを完了する手順を使用することで、 現在の再生方向における自然な終端まで進めることができる:

1. animation の 実効再生速度がゼロである場合、 または animation の 実効再生 速度 > 0 かつ 関連付けられた効果の終端が無限大である場合、 "InvalidStateError" DOMException を投げ、 これらの手順を中止する。

2. animation に 保留中の再生速度を適用する。

3. limit を次のように設定する:

   再生速度 > 0 の場合、

   limit を 関連付けられた効果の終端とする。

   それ以外の場合、

   limit をゼロとする。

4. 現在時刻を limit に サイレントに設定する。

5. animation の 開始時刻が 未解決であり、animation に関連付けられた アクティブな タイムラインがある場合、 開始時刻を timeline time - (limit / 再生速度) を評価した結果とする。ここで timeline time は、関連付けられた タイムラインの現在の 時間 値である。

6. 保留中の一時停止タスクがあり、開始時刻が 解決済みである場合、

   1. 保持時刻を 未解決とする。

      通常、保持時刻はすでに未解決である。 ただし、アニメーションが以前 アイドルであった場合を除く。

   2. 保留中の一時停止タスクをキャンセルする。

   3. animation の 現在の ready promiseを animation で解決する。

7. 保留中の再生タスクがあり、開始時刻が 解決済みである場合、そのタスクをキャンセルし、 animation の 現在の ready promiseを animation で 解決する。

8. did seek フラグを true、 synchronously notify フラグを true に設定して、 animation について アニメーションの完了状態を更新する手順を実行する。

4.4.14. アニメーションのキャンセル

アニメーションはキャンセルでき、それにより 現在時刻が 未解決となり、 関連付けられた効果によって生じた効果がすべて取り除かれる。

animation について アニメーションを キャンセルする手順は、 次のとおりである:

1. animation の 再生状態が アイドルではない場合、次の手順を実行する:

   1. animation に対して アニメーションの保留中の タスクをリセットする手順を実行する。

   2. 現在の finished promiseを、"AbortError" という名前の DOMException で拒否する。

   3. 現在の finished promiseの [[PromiseIsHandled]] 内部スロットを true に設定する。

   4. 現在の finished promiseを、 animation の 関連する Realm内の 新しい promiseとする。

   5. AnimationPlaybackEvent cancelEvent を作成する。

   6. cancelEvent の type 属性を cancel に設定する。

   7. cancelEvent の currentTime を null に設定する。

   8. timeline time を、animation が関連付けられている タイムラインの 現在時刻とする。 animation が アクティブなタイムラインに 関連付けられていない場合、timeline time を 未解決の 時間値とする。

   9. cancelEvent の timelineTime を timeline time に設定する。timeline time が 未解決である場合、 null に設定する。

   10. animation に タイミング用文書がある場合、 cancelEvent を、その タイミング用 文書の 保留中のアニメーション イベントキューに、その対象 animation とともに追加する。 animation が、タイムライン時刻を オリジン相対 時刻に変換する手順を定義する アクティブな タイムラインに関連付けられている場合、 予定イベント時刻を、その手順を timeline time に適用した結果とする。 それ以外の場合、予定イベント時刻は 未解決の 時間 値である。

       それ以外の場合、animation に cancelEvent を 配送するためのタスクを キューに入れる。 このタスクのタスクソースは、DOM 操作タスク ソースである。

2. animation の 保持時刻を 未解決にする。

3. animation の 開始時刻を 未解決にする。

animation について アニメーションの保留中のタスクをリセットする手順は、 次のとおりである:

1. animation に 保留中の再生タスクまたは 保留中の一時停止タスクがない場合、 この手順を中止する。

2. animation に 保留中の再生タスクがある場合、そのタスクをキャンセルする。

3. animation に 保留中の一時停止タスクがある場合、そのタスクをキャンセルする。

4. animation に 保留中の再生速度を適用する。

5. animation の 現在の ready promiseを、"AbortError" という名前の DOMException で 拒否する。

6. animation の 現在の ready promiseの [[PromiseIsHandled]] 内部スロットを true に設定する。

7. animation の 現在の ready promiseを、 animation の 関連する Realmにおいて、 値 animation を持つ 新しい解決済み Promise オブジェクトを作成した結果とする。

4.4.15. 速度制御

アニメーションには、 関連付けられた タイムラインの 時間値の変化率から、アニメーションの 現在時刻へのスケーリング係数を提供する 再生速度がある。 再生速度の初期値は 1 である。

アニメーションの 再生 速度をゼロに設定すると、実質的にアニメーションが一時停止する （ただし、再生状態が必ずしも 一時停止中になるわけではない）。

4.4.15.1. アニメーションの再生速度の設定

アニメーション animation の 再生速度を設定する手順は、 new playback rate に対して次のとおりである:

1. animation 上の 保留中の再生速度をすべてクリアする。

2. previous time を、再生速度を変更する前の animation の 現在時刻の値とする。

3. previous playback rate を、animation の現在の 実効再生 速度とする。

4. 再生速度を new playback rate に設定する。

5. 存在する場合、次のうち最初に一致する条件に対応する手順を実行する:

   animation が 単調増加の タイムラインに関連付けられており、 previous time が 解決済みである場合、

   animation の 現在時刻を設定することにより、 previous time に設定する。

   animation が null ではない タイムラインに関連付けられており、 そのタイムラインが 単調増加ではなく、 animation の 開始時刻が 解決済みで、 関連付けられた効果の終端が無限大ではなく、 さらに次のいずれかである場合:

   • previous playback rate < 0 かつ new playback rate ≥ 0、または

   • previous playback rate ≥ 0 かつ new playback rate < 0、

   animation の 開始時刻を、 animation について 関連付けられた効果の終端 - 開始時刻 を評価した結果に設定する。

   注: これは、非単調タイムライン上で アニメーションの開始時刻と終了時刻を実質的に反転し、 反対方向から見た開始時刻の相対オフセットを維持する。

4.4.15.2. アニメーションの再生速度の シームレスな更新

別のプロセスまたはスレッドで実行されている進行中のアニメーションでは、 アニメーションを実行するプロセスまたはスレッドが、更新を実行する プロセスまたはスレッドと現在同期していない場合、 再生速度を 設定する手順によってアニメーションが飛ぶことがある。

アニメーションの 再生速度をシームレスに変更するため、 アニメーションは 保留中の再生速度を持つ場合がある。 これは、必要な同期が行われた後 （異なるスレッドまたはプロセスで実行されるアニメーションの場合）に適用される再生速度を定義する。

アニメーションの 保留中の再生速度は、初期状態では設定されていない。

animation の 実効 再生速度は、 保留中の 再生速度が設定されている場合はその値であり、 そうでなければアニメーションの 再生速度である。

アニメーション animation に保留中の 再生 速度を適用する場合、次の手順を実行する:

1. animation に 保留中の再生速度がない場合、これらの手順を中止する。

2. animation の 再生速度を、その 保留中の再生速度に設定する。

3. animation の 保留中の再生速度をクリアする。

アニメーション animation の 現在時刻を維持したまま、 new playback rate に 再生速度をシームレスに更新する手順は次のとおりである:

1. previous play state を、animation の 再生状態とする。

   注: animation の 実効再生速度を更新する前に再生状態を記録する必要がある。 これは、次のロジックで、 animation が現在 完了している場合に、 保留中の再生速度を適用した後も完了状態のままであるかどうかに 関係なく、その 保留中の再生速度を 直ちに適用したいためである。

2. animation の 保留中の再生速度を new playback rate とする。

3. 次のうち最初に一致する条件に対応する手順を実行する:

   animation に 保留中の再生タスクまたは 保留中の一時停止タスクがある場合、

   これらの手順を中止する。

   注: 種類の異なる保留中のタスクは、 実行時に 保留中の 再生速度を適用するため、この場合、それ以上の処理は必要ない。

   previous play state が アイドルまたは 一時停止中であるか、 animation の 現在時刻が 未解決である場合、

   animation に 保留中の再生速度を適用する。

   注: 上記の2番目の条件は、 未解決の現在時刻を持ち、 保留中の再生タスクを持たない 実行中のアニメーションがある場合に、 下記でそれを再生しようとしないようにするために必要である。

   previous play state が 完了である場合、

   1. unconstrained current time を、 保持時刻を 未解決の時間値で置き換えて、 animation の 現在時刻を計算した結果とする。

   2. animation の 開始時刻を、 次の式を評価した結果とする:

      timeline time - (unconstrained current time / 保留中の再生速度)

      ここで timeline time は、 animation に関連付けられた タイムラインの現在の 時間値である。

      保留中の再生速度がゼロである場合、 animation の 開始時刻を timeline time とする。

   3. animation に保留中の再生 速度を適用する。

   4. did seek フラグを false、 synchronously notify フラグを false に設定して、 animation について アニメーションの 完了状態を更新する手順を実行する。

   それ以外の場合、

   auto-rewind フラグを false に設定して、 animation について アニメーションを再生する手順を実行する。

4.4.16. アニメーションの逆再生

アニメーション animation を 逆再生する手順は次のとおりである:

1. animation に関連付けられた タイムラインがないか、 関連付けられた タイムラインが 非アクティブである場合、 "InvalidStateError" DOMException を投げ、 これらの手順を中止する。

2. original pending playback rate を animation の 保留中の再生 速度とする。

3. animation の 保留中の再生速度を、その 実効再生速度の加法逆元（すなわち -実効再生速度）とする。

4. auto-rewind フラグを true に設定して、 animation について アニメーションを再生する手順を実行する。

   アニメーションを再生する手順が例外を投げた場合、 animation の 保留中の再生速度を original pending playback rate に設定し、その例外を伝播する。

4.4.17. 再生状態

アニメーションは、 次の 再生状態の いずれかにあると説明でき、それぞれについて非規範的な説明も示す:

ある時点における アニメーション animation の 再生状態は、 次のうち最初に一致する条件に対応する状態である:

animation.effect.updateTiming({ duration: 5000 });
animation.currentTime = 4000;
animation.pause();
animation.ready.then(function() {
  animation.effect.updateTiming({ duration: 3000 });
  alert(animation.playState); // 'paused' と表示する
  animation.startTime =
    document.timeline.currentTime - animation.currentTime * animation.playbackRate;
  alert(animation.playState); // 'finished' と表示する
});

4.4.18. アニメーションイベント

アニメーションイベントには、 この仕様で定義される アニメーション再生イベントのほか、CSS トランジションのイベント [CSS-TRANSITIONS-1] および CSS アニメーションのイベント [CSS-ANIMATIONS-1] が含まれる。 将来の仕様では、この集合にさらに別の種類の アニメーション イベントを追加できる。

各 Document は、アニメーションイベントを、 対応するイベントターゲットおよび 予定イベント 時刻とともに格納する 保留中のアニメーションイベントキューを保持する。 予定イベント 時刻は、時刻起点を基準とする 時間値であり、 アニメーションが無限に高い頻度で 更新されていたならイベントが理想的に配送されていた時刻を表す。 これは、キューに入れられた アニメーションイベントを時系列順に並べ替えるため、 アニメーションを更新してイベントを送信する手順によって使用される。 たとえば、アニメーションの タイムラインが 時刻起点と無関係な値を生成する場合（たとえば、 スクロール位置を追跡するタイムライン）、または タイムラインが 非アクティブである場合、 この値は 未解決である場合があることに注意。

4.4.18.1. アニメーションイベントの並べ替え

キューに入れられたイベントの並べ替えを支援するため、次の定義を設ける。

アニメーション animation の 開始 時刻を基準とする 時間値 time について、アニメーション時刻を タイムライン時刻に変換するには、次の手順を実行する:

1. time が 未解決である場合、time を返す。

2. time が無限大である場合、未解決の 時間値を返す。

3. animation の 再生速度がゼロである場合、 未解決の 時間値を返す。

4. animation の 開始時刻が 未解決である場合、 未解決の 時間値を返す。

5. 次の計算結果を返す: time × (1 / playback rate) + start time（ここで playback rate および start time は、それぞれ animation の 再生速度および 開始時刻である）。

タイムライン timeline の 時間値と同じ尺度で表される 時間値 time について、 タイムライン時刻を オリジン相対時刻に変換するには、次の手順を実行する:

1. timeline time を、time をアニメーション時刻からタイムライン時刻へ変換した結果とする。

2. timeline time が未解決である場合、 time を返す。

3. animation がタイムラインに関連付けられていない場合、 未解決の時間値を返す。

4. animation が非アクティブなタイムラインに関連付けられている場合、 未解決の時間値を返す。

5. animation に関連付けられたタイムラインについてタイムライン時刻をオリジン相対時刻に変換する手順が存在しない場合、 未解決の時間値を返す。

6. animation に関連付けられたタイムラインについて定義された手順を使用して、 timeline time をオリジン相対時刻に変換した結果を返す。

4.4.18.2. アニメーション再生イベント

アニメーションは再生されると、 アニメーション再生イベントを通じて、その状態の変化を報告する。

アニメーション 再生イベントはタイミングモデルの特性である。そのため、 アニメーションの 関連付けられた効果が存在しない場合や、 観察可能な結果を持たない場合でも配送される。

4.4.18.3. アニメーション再生イベントの種類

finish

アニメーションが 完了再生状態に入るたびにキューに入れられる。

cancel

アニメーションが別の状態から アイドル再生状態に入るたびにキューに入れられる。 初期状態がアイドルである新しい アニメーションを作成しても、 新しい cancel イベントは生成されない。

remove

アニメーションが自動的に削除されるたびにキューに入れられる。 § 5.5 アニメーションの置換を参照。

4.5. アニメーション効果

アニメーション効果は、 タイミング階層内の項目を指す抽象的な用語である。

4.5.1. アニメーション効果 とアニメーションの関係

アニメーションの 関連付けられた効果は、設定されている場合、 アニメーション効果の一種である。 アニメーションの 関連付けられた効果は、そのアニメーションに 関連付けられていると言う。 任意の時点で、アニメーション効果は最大1つの アニメーションにのみ 関連付けることができる。

アニメーション効果 effect は、effect が アニメーションに 関連付けられており、そのアニメーションがさらに timeline に関連付けられている場合、 timeline に関連付けられている。

4.5.2. アニメーション効果の種類

この仕様では、単一の種類の アニメーション効果、すなわち キーフレーム効果を定義する。 この仕様の後続レベルでは、さらに別の種類の アニメーション効果を定義する。

すべての種類の アニメーション 効果は、以下の節で説明する多数の共通 プロパティを定義する。

4.5.3. アクティブ区間

アニメーション効果が実行されるようスケジュールされている期間を、 その アクティブ 区間と呼ぶ。 各 アニメーション効果は、このような区間を1つだけ持つ。

アクティブ区間の下限は通常、この アニメーション効果に関連付けられた アニメーションの 開始 時刻に対応するが、アニメーション効果上の 開始遅延によってずらされる場合がある。

区間の上限は アクティブ 持続時間によって決定される。

開始時刻、開始 遅延、および アクティブ 持続時間の関係を以下に示す。

終了遅延も指定できるが、 主としてアニメーションを順序付ける場合にのみ有用である。

アニメーション効果は、 効果がその効果を生成するようスケジュールされている期間である アクティブ区間を定義する。 ただし、アクティブ 区間の外側にも適用される フィルモードは例外である。

アクティブ 区間の下限は 開始遅延によって定義される。

アニメーション効果の 開始遅延は、 そのアニメーション効果が関連付けられている アニメーションの 開始 時刻からの符号付きオフセットである。

アクティブ 区間の長さを アクティブ 持続時間と呼び、その計算は § 4.8.2 アクティブ持続時間の計算で定義される。

開始遅延と同様に、アニメーション効果には 終了遅延もあり、 主として別の アニメーション効果の 終了時刻に基づいて アニメーションを順序付ける場合に使用する。 これは通常、この仕様の後続レベルで導入されるシーケンス効果と組み合わせた場合にのみ有用だが、 SVG における min 属性 （[SVG11]、第19章）を表現する目的で ここに含まれている。

アニメーション効果の 終了時刻は、 max(開始遅延 + アクティブ 持続時間 + 終了遅延, 0) を評価した結果である。

4.5.4. ローカル時刻

任意の時点における アニメーション効果の ローカル時刻は、 次のうち最初に一致する条件に基づく:

4.5.5. アニメーション効果のフェーズと 状態

この節は非規範的である

任意の時点で、アニメーション効果は、3つの可能な フェーズのいずれかにある。 アニメーション効果が 未解決の ローカル 時刻を持つ場合、いずれのフェーズにも属さない。

各フェーズを以下に示す。

フェーズは次のとおりである:

前フェーズ

アニメーション 効果の ローカル 時刻が、効果の アクティブ 区間および 終了 時刻より前にあるか、または負の 開始遅延が有効な範囲内にある。

アクティブフェーズ

アニメーション 効果の ローカル 時刻が、効果の アクティブ 区間の内側にあり、かつ負の 開始遅延 または負の 終了遅延の範囲外にある。

後フェーズ

アニメーション 効果の ローカル 時刻が、効果の アクティブ 区間より後、または（負の 終了遅延により）それより先に来る場合は 終了時刻より後にあるが、 負の 開始遅延が有効な範囲内にはない。

これらのフェーズに加えて、アニメーション効果は、 複数の重複する状態のいずれかにあるとも記述できる。 これらの状態は単一の アニメーションフレームの期間だけ確立され、 主としてモデルの状態を持つ部分を記述するための便宜的なものである。

これらの状態とモデル内での用途を次に要約する:

再生中

各フレームで アクティブ時刻が変化している アニメーション効果に対応する。

現在

再生 中であるか、またはその アニメーションの現在の 再生速度に基づき将来 再生中になり得る アニメーション効果に対応する。

効果中

解決済みの アクティブ時刻を持つ アニメーション効果に対応する。 これは、アニメーション効果が アクティブフェーズにある場合、または アクティブフェーズの外側であっても、 効果の フィル モード（§ 4.6 フィル動作を参照）によって アクティブ時刻が解決済みとなる時刻に発生する。 効果中の アニメーション効果だけが、 その対象に結果を適用する。

これら各状態の規範的な定義を以下に示す。

アニメーション効果のフェーズを決定するには、 次の定義が必要である:

アニメーション 方向

効果が アニメーションに 関連付けられており、かつ関連付けられた アニメーションの 再生速度がゼロ未満である場合は "backwards"。 それ以外の場合、アニメーション方向は "forwards" である。

before-active 境界時刻

max(min(開始遅延, 終了時刻), 0)

active-after 境界時刻

max(min(開始遅延 + アクティブ持続時間, 終了時刻), 0)

アニメーション効果は、 アニメーション効果の ローカル時刻が 未解決ではなく、かつ 次の条件のいずれかが満たされる場合、 前フェーズにある:

1. ローカル時刻が before-active 境界時刻未満である、または

2. アニメーション 方向が "backwards" であり、ローカル 時刻が before-active 境界時刻に等しい。

アニメーション効果は、 アニメーション効果の ローカル時刻が 未解決ではなく、かつ 次の条件のいずれかが満たされる場合、 後フェーズにある:

1. ローカル時刻が active-after 境界 時刻より大きい、または

2. アニメーション 方向が "forwards" であり、ローカル 時刻が active-after 境界時刻に等しい。

アニメーション効果は、 アニメーション効果の ローカル時刻が 未解決ではなく、かつ 前フェーズにも 後フェーズにもない場合、 アクティブフェーズにある。

さらに、アニメーション効果が上記のどのフェーズにもない場合を、 アイドルフェーズにあると呼ぶと便利なことが多い。

アニメーション効果は、 次の条件がすべて満たされる場合、 再生中である:

1. アニメーション 効果が アクティブフェーズにあり、かつ

2. アニメーション 効果が、完了していないアニメーションに 関連付けられている。

アニメーション効果は、 次の条件のいずれかが真である場合、 現在である:

• アニメーション 効果が 再生中である、または

• アニメーション 効果が、再生速度 > 0 の アニメーションに 関連付けられており、 アニメーション効果が 前 フェーズにある、または

• アニメーション 効果が、再生速度 < 0 のアニメーションに 関連付けられており、 アニメーション効果が 後フェーズにある、 または

• アニメーション 効果が、アイドルの 再生 状態ではないアニメーションに 関連付けられており、そのアニメーションに関連付けられた null ではない タイムラインが 単調増加ではない。

アニメーション効果は、§ 4.8.3.1 アクティブ時刻の計算の 手順に従って計算されたその アクティブ 時刻が 未解決ではない場合、 効果 中である。

4.5.6. 関連するアニメーション

アニメーションに 関連付けられた アニメーション効果に基づいて、 そのアニメーションが 関連するものと定義できる。

アニメーションは、 次の場合 関連する:

• その 関連付けられた効果が 現在または 効果中であり、かつ

• その 置換状態が 削除済みではない。

4.6. フィル動作

アニメーション 効果が 再生中でないときの効果は、 その フィルモードによって決定される。

指定可能な フィルモードは次のとおり:

• none,

• forwards,

• backwards, and

• both.

これらのモードの規範的な定義は、 § 4.8.3.1 アクティブ時刻の計算における アクティブ時刻の 計算に組み込まれている。

// 次のアニメーションが完了した後の最初のフレームでは、
// `finished` promise のコールバックはスタイルが更新される前に実行されるため、
// ちらつきは発生しない。
elem.animate({ transform: 'translateY(100px)' }, 200).finished.then(() => {
  elem.style.transform = 'translateY(100px)';
});

elem.style.transform = 'translateY(100px)';
elem.animate({ transform: 'none', offset: 0 }, 200);

elem.addEventListener('click', async evt => {
  const animation = elem.animate(
    { transform: `translate(${evt.clientX}px, ${evt.clientY}px)` },
    { duration: 800, fill: 'forwards' }
  );
  await animation.finished;
  // commitStyles は `animation` までを含むスタイルを記録し、
  // その結果で elem の指定スタイルを更新する。
  animation.commitStyles();
  animation.cancel();
});

4.6.1. フィルモード

この節は非規範的である

各 フィルモードの効果は次のとおり:

none

アニメーション効果は 再生中でない場合、効果を持たない。

forwards

アニメーション効果が 後フェーズにある場合、 アニメーション効果は、最後に 再生中となるようスケジュールされていた時点と同じ 反復進行度の値を生成する。

それ以外の、アニメーション効果が 再生中でないすべての時点では、 効果を持たない。

backwards

アニメーション効果が 前フェーズにある場合、 アニメーション効果は、最初に 再生中となるようスケジュールされている時点と同じ 反復進行度の値を生成する。

それ以外の、アニメーション効果が 再生中でないすべての時点では、 効果を持たない。

both

アニメーション効果が 前フェーズにある場合、 backwards フィル動作が使用される。

アニメーション効果が 後フェーズにある場合、 forwards フィル動作が使用される。

これらのフィルモードの例を以下に示す。

注: フィルモードを設定しても、 アクティブ区間の端点や フェーズ間の境界には影響しない。 ただし、アニメーション効果の アクティブ時刻は、 アクティブフェーズ内または フィルが適用されている場合にのみ定義される（すなわち 未解決ではない）ため、 フィルモードはタイミングモデルの他のさまざまなプロパティには影響を与える。

4.7. 反復

4.7.1. 反復区間

アニメーション効果を固定回数または無期限に 反復するよう指定できる。 この反復は アクティブ区間の内側で発生する。 1回の反復が行われる時間範囲を 反復 区間と呼ぶ。

アクティブ 区間とは異なり、アニメーション効果は複数の 反復区間を持つことができるが、通常関心があるのは 現在の反復に対応する区間だけである。

1回の反復の長さを 反復 持続時間と呼ぶ。 アニメーション効果の初期 反復 持続時間はゼロである。

この節は非規範的である

反復持続時間と アクティブ 持続時間を比較すると、次のようになる:

反復持続時間

アニメーション効果の1回の反復が 完了するまでにかかる時間。

アクティブ持続時間

反復を含め、アニメーション効果全体が完了するまでにかかる時間。 これは 反復持続時間より長い場合も短い場合もある。

反復持続時間と アクティブ 持続時間の関係を以下に示す。

4.7.2. 反復の制御

アニメーション効果が反復する回数を、その 反復回数と呼ぶ。 反復回数は、 0 以上の実数である。 反復回数は、アニメーション効果が無期限に反復することを表すため、 正の無限大とすることもできる。

反復 回数に加えて、アニメーション 効果には、反復の系列内で アニメーション効果を開始すべきオフセットを指定する 反復 開始プロパティもある。 反復開始は、 0 以上の有限実数である。

これらのパラメーターの動作は、§ 4.8 アニメーション効果の中核計算の計算で定義される。

この節は非規範的である

反復 回数および 反復開始パラメーターの効果を以下に示す。

反復 回数パラメーターとは異なり、反復 開始パラメーターは アクティブ 持続時間の長さに影響しない。

反復開始が1以上の値は一般に、 反復合成 操作が accumulate である アニメーション効果と組み合わせて使用しない限り、 有用ではないことに注意。

4.7.3. 反復時間空間

この節は非規範的である

Web Animations では、すべての時刻は何らかの基準点を基準とする。 これらの異なる基準点によって、異なる時間 空間が生じる。

これは、コンピューターグラフィックスで使用される座標空間と比較できる。 時間空間のゼロ時刻は、 座標空間の原点に相当する。

反復するアニメーションは、アニメーションが反復するたびに 新しい時間空間、すなわち反復時間空間を確立すると説明できる。

反復時間空間とは、そのゼロ時刻が アニメーション効果の現在の反復の開始である時間空間である。

Web Animations モデル内では、アクティブ 時刻も参照する。これはアクティブ区間の開始を基準とする時刻である。 ただし、この時間空間はモデル内部のものであり、 プログラミングインターフェイスやマークアップには公開されない。

これらの時間空間を以下に示す。

注: 時間空間自体には境界がないが、Web Animations は アクティブ時刻 および 反復 進行度を、図に示すように一定の範囲に制限されるよう定義する。 たとえば、-1秒という時刻はアクティブ時間空間では有効な時刻だが、 § 4.8.3.1 アクティブ時刻の計算で定義される アクティブ時刻を計算する手順は 負の値を返すことはない。

これらの時間空間に加えて、 現在のグローバルオブジェクトの Document の 既定の文書タイムラインの 時間 値の時間空間である文書時間空間も参照できる。

4.7.4. 区間タイミング

この節は非規範的である

アニメーション効果が反復するとき、反復境界での動作を定義する必要がある。 このため、そして実際にはすべての区間タイミングについて、 Web Animations は終端を含まないタイミングモデルを使用する。 これは、区間の開始時刻は区間に含まれる一方、 終了時刻は含まれないことを意味する。 区間表記では [begin, end) と記述できる。 このモデルでは区間同士が重ならないため、 区間が反復または順序付けされる場合に自然な動作が得られる。

以下の例では、反復効果についてローカル時刻が 1s のとき、 反復時刻は 0 である。 順序付けされたアニメーションでは、タイムライン時刻が 1s のとき、 アニメーション B の 関連付けられた効果だけが 再生中となり、重複はない。

この動作の例外として、フィルを実行するときに フィルが区間の端点から始まる場合、その端点が使用される。 この動作は § 4.8.3.3 単純反復進行度の計算で示される アルゴリズムから導かれ、以下に示す。

4.8. アニメーション効果の中核計算

4.8.1. 概要

この節は非規範的である

Web Animations タイミングモデルの中核にあるのは、 ローカル時刻の値を受け取り、 反復進行度へ変換する処理である。

この処理の最初の手順は、 アクティブ 持続時間によって決定される アクティブ区間の境界を計算することである。

この処理を以下に示す。

アクティブ持続時間を計算する処理は、 § 4.8.2 アクティブ持続時間の計算で規範的に定義される。

アクティブ持続時間が確立された後、 アニメーション効果の ローカル時刻を、その 変換済み進行度（反復 進行度）へ変換する処理を以下に示す。

最初の手順である ローカル時刻の計算については、 § 4.5.4 ローカル時刻で説明する。 図の手順2から4については以下の節で説明する。 手順5および6については、それぞれ § 4.9.1 方向付き進行度の計算および § 4.10.1 変換済み進行度の計算で説明する。

4.8.2. アクティブ持続時間の計算

アクティブ持続時間は、 次のように計算される:

アクティブ持続時間 = 反復持続時間 × 反復回数

反復持続時間または 反復回数のいずれかがゼロである場合、 アクティブ持続時間は ゼロである。

IEEE 754-2008 によれば無限大にゼロを乗算した結果は未定義であるため、 この明確化が必要である。

4.8.3. ローカル時刻の変換

4.8.3.1. アクティブ時刻の計算

アクティブ時刻は、 ローカル時刻と 開始遅延に基づく。 ただし、これは アニメーション効果が 出力を生成すべき場合にのみ定義されるため、その フィルモードおよび フェーズに次のように依存する。

4.8.3.2. 全体進行度の計算

全体進行度は、 完了した反復の数（部分的な反復を含む）を表し、次のように定義される:

1. アクティブ時刻が 未解決である場合、 未解決を返す。

2. 次のうち最初に一致する条件に基づいて、 overall progress の初期値を計算する。

   反復持続時間がゼロである場合、

   アニメーション効果が 前フェーズにある場合、 overall progress をゼロとし、それ以外の場合は 反復回数に等しいものとする。

   それ以外の場合、

   overall progress を アクティブ時刻 / 反復持続時間 を計算した結果とする。

3. overall progress + 反復開始 を計算した結果を返す。

4.8.3.3. 単純反復進行度の計算

単純 反復進行度は、現在の反復内の進行を表す割合であり、 再生方向や、効果に適用される タイミング 関数によって時間に導入される変換を無視したもので、次のように計算される:

1. 全体 進行度が 未解決である場合、 未解決を返す。

2. 全体 進行度が無限大である場合、simple iteration progress を 反復開始 % 1.0 とし、それ以外の場合、simple iteration progress を 全体進行度 % 1.0 とする。

3. 次の条件がすべて真である場合、

   • 上で計算した simple iteration progress がゼロであり、かつ

   • アニメーション効果が アクティブフェーズまたは 後フェーズにあり、かつ

   • アクティブ時刻が アクティブ持続時間に等しく、かつ

   • 反復 回数がゼロに等しくない。

   simple iteration progress を 1.0 とする。

   上記の手順は、アニメーションのアクティブ区間が 反復の終端ちょうどで終了する場合、 次の反復の開始ではなく、最後の反復の終端を保持してフィルする動作を実装する。

   最後の条件は、反復回数がゼロであったために そもそもアニメーションの反復を1回も再生しなかった場合に、 この処理が適用されることを防ぐ。

4. simple iteration progress を返す。

4.8.4. 現在の反復の計算

現在の反復は、 次の手順を使用して計算できる:

1. アクティブ時刻が 未解決である場合、 未解決を返す。

2. アニメーション効果が 後フェーズにあり、かつ 反復回数 が無限大である場合、無限大を返す。

3. 単純反復進行度が 1.0 である場合、 floor(全体進行度) - 1 を返す。

4. それ以外の場合、 floor(全体進行度) を返す。

4.9. 方向制御

アニメーション効果は、 方向制御を使用して、反復を別の方向で実行するよう設定することもできる。 このため、アニメーション効果には、次の値のいずれかを取る 再生 方向パラメーターがある:

• normal,

• reverse,

• alternate, or

• alternate-reverse.

これらの値の意味は、以下の 方向付き進行度の 計算に組み込まれている。

4.9.1. 方向付き進行度の計算

方向付き進行度は、 単純反復進行度から次の手順を使用して計算される:

1. 単純反復進行度が 未解決である場合、 未解決を返す。

2. 次の一覧のうち最初に一致する条件を使用して current direction を計算する:

   再生方向が normal である場合、

   current direction を forwards とする。

   再生方向が reverse である場合、

   current direction を reverse とする。

   それ以外の場合、

   1. d を 現在の反復とする。

   2. 再生方向が alternate-reverse である場合、d を 1 増加させる。

   3. d % 2 == 0 の場合、current direction を forwards とし、それ以外の場合は current direction を reverse とする。 d が無限大である場合、current direction を forwards とする。

3. current direction が forwards の場合、 単純反復進行度を返す。

   それ以外の場合、 1.0 - 単純反復進行度 を返す。

4.10. 時間変換

アニメーション 効果が進行する速度を制御したい場合が多い。 たとえば、アニメーションの速度をイージングすると、 運動量の感覚を生み出し、より自然な効果を生成できる。 CSS Easing Functions Module [CSS-EASING-1] は、この目的のための タイミング 関数を定義する。

アニメーション効果には、 1つの タイミング関数が関連付けられている。 既定の タイミング関数は 線形タイミング 関数である。

4.10.1. 変換済み進行度の計算

変換済み 進行度は、方向付き進行度から次の手順を使用して計算される:

1. 方向付き 進行度が 未解決である場合、 未解決を返す。

2. before flag の値を次のように計算する:

   1. § 4.9.1 方向付き進行度の計算で 定義される手順を使用して current direction を決定する。

   2. current direction が forwards である場合、 going forwards を true とし、それ以外の場合は false とする。

   3. アニメーション効果が 前フェーズにあり、かつ going forwards が true の場合、または アニメーション効果が 後フェーズにあり、かつ going forwards が false の場合に、before flag を設定する。

3. 方向付き進行度を 入力進行度値として、before flag を before flag として渡し、 アニメーション効果の タイミング 関数を評価した結果を返す。

4.11. 反復進行度

アニメーション効果の 反復 進行度は、単にその 変換済み 進行度である。

5. アニメーションモデル

5.1. はじめに

アニメーション効果には、 タイミング出力の変化に応じて影響を与える、 0個以上の関連付けられたプロパティがある。これらのプロパティを 効果の 対象 プロパティと呼ぶ。

反復 進行度、現在の反復、および 基底値が与えられた場合、 アニメーション効果は、 プロパティに適した アニメーション型の手順を適用することで、 各 アニメーション可能な 対象プロパティについて 効果値を生成する。

5.2. プロパティのアニメーション

特に指定がない限り、すべての CSS プロパティは アニメーション可能である。 プロパティ値をどのように結合するかは、 各プロパティのプロパティ定義表にある アニメーション型の行で定義される:

アニメーション不可

このプロパティはアニメーション可能ではない。 アニメーションのキーフレームに列挙されても処理されず、 トランジションの影響も受けない。

注: プロパティは通常、 アニメーションさせると過度に複雑になる場合にアニメーションから除外される。 たとえば、アニメーションパラメーターを定義するプロパティは、 アニメーションさせると複雑な再帰動作が発生するため アニメーション不可である。

注: アニメーション不可なプロパティだけを対象とする アニメーション効果も、 イベントの発火や、アニメーションの 現在の finished promiseの履行を遅延させることなど、 通常の アニメーション効果としての動作は引き続き示す。

離散

プロパティの値を意味のある形で結合できないため、 加算可能ではなく、補間では 50%（p=0.5）で V_a から V_b に切り替わる。 すなわち、

$V_{\mathrm{result}}=\left\{\begin{array}{cc}{V}_{\mathrm{start}}\hfill & \text{if}p<0.5\hfill \\ V_{\mathrm{end}}\hfill & \text{if}p\ge 0.5\hfill \end{array}\right.$

計算値による

計算 値の対応する個々の成分を、その値型について示された手順を使用して 結合（補間、加算、または累積）する （CSS Values 4 § 3 値の結合: 補間、加算、および累積を参照）。 成分の数または対応する成分の型が一致しない場合、 またはいずれかの成分値が 離散アニメーションを使用し、 対応する2つの値が一致しない場合、 プロパティ値は 離散として結合される。

反復可能リスト

計算 値による場合と同じだが、2つのリストの項目数が異なる場合、 最初に項目数が最小公倍数になるまで各リストを反復する。 その後、各項目を 計算値によって結合する。 値の組を結合できない場合、 またはいずれかの成分値が 離散アニメーションを使用する場合、 プロパティ値は 離散として結合される。

注: 反復可能リストの概念により、 概念上ある長さまで反復されるリスト （たとえば background-origin が background-image リストの長さまで反復される場合）や、 無限に反復されるリストが、 任意の値の間を滑らかに遷移できるようになり、 計算値がその結果を適切に表現 （そして場合によっては適切に継承）できるようになる。

（本文を参照）

一部のプロパティには、上記のケースでは扱われない 固有の補間動作がある。 その場合、そのプロパティのアニメーション動作は明示的に指定される。

まだプロパティ定義に Animation type の行を含んでいない プロパティの アニメーション型は、 付録 A: 既存プロパティのアニメーション型で定義される。

5.2.1. カスタムプロパティ

現在のグローバルオブジェクトについて registerProperty() メソッドを使用して登録された カスタムプロパティでは、 アニメーション型は 計算値によるであり、 プロパティの 構文定義で使用される型から導出される。 プロパティに指定された構文に対応する 計算値の型が存在しない場合 （たとえば構文が 汎用構文定義である場合）、 または カスタムプロパティが登録されていない場合、 アニメーション型は 離散である。

5.3. キーフレーム効果

キーフレーム効果は、タイミングモデルの出力を使用して、 要素または 疑似要素（::before や ::after など [select]）の CSS プロパティを更新する アニメーション効果の一種であり、 その要素または疑似要素を 効果ターゲットと呼ぶ。

効果ターゲットは、 対象要素と呼ばれる Element と、対象疑似セレクターと呼ばれる 疑似要素 セレクターから構成される。 効果ターゲットが Elementである場合、 対象要素はその要素であり、 対象疑似セレクターは null である。 効果ターゲットが 疑似要素である場合、 対象要素はその 起点要素であり、 対象疑似セレクターは、 その特定の 疑似要素を指定するために必要なものとなる。

この方法で指定されるすべての 効果ターゲット （::part() 疑似要素や未対応の疑似要素など）について 計算済みプロパティ値が定義されているわけではないことに注意。

5.3.1. キーフレーム

キーフレーム効果の 効果値は、 小数オフセットに配置された一連のプロパティ値の間を補間することで計算される。 オフセットで索引付けされた各プロパティ値の集合を キーフレームと呼ぶ。

キーフレームのオフセットは、 [0, 1] の範囲の値または特殊値 null である。 キーフレーム効果の キーフレームの一覧は、 オフセットによって 緩やかにソートされていなければならない。これは、一覧内で null ではない キーフレームオフセットを持つ 各 キーフレームについて、 そのオフセットが、存在する場合には、それ以前の null ではない キーフレームオフセットを持つ キーフレームのオフセット以上であることを意味する。

キーフレームが重複する場合や 未対応の値を持つ場合の動作は、 § 5.3.4 キーフレーム効果の効果値で定義される。

各キーフレームには、タイミング関数も関連付けられており、 その関数は、それが指定されたキーフレームと一覧内の次のキーフレームとの間の期間に適用される。 一覧内の最後のキーフレームで指定された タイミング関数は適用されない。

各 キーフレームは、設定されている場合、その キーフレームで指定されたすべての値に適用される キーフレーム固有の合成 操作を持つことができる。 使用可能な操作とその意味は、§ 5.4.4 効果の合成で キーフレーム効果全体に関連付けられた 合成操作について定義されているものと同一である。 キーフレームの キーフレーム固有の合成操作が設定されていない場合、そのキーフレームで指定された値には、キーフレーム効果全体に指定された 合成操作が使用される。

5.3.2. プロパティ値の計算

var animation = elem.animate([{ fontSize: '10px', width: '10em' },
                              { fontSize: '20px', width: '20em' }], 1000);
animation.currentTime = 500;
console.log(getComputedStyle(elem).fontSize); // 15px になるはずである
console.log(getComputedStyle(elem).width); // 225px になるはずである

5.3.3. 計算済みキーフレームの計算

キーフレーム 効果の 効果 値を計算する前に、 その キーフレーム上の プロパティ値が 計算され、 null の キーフレーム オフセットを持つキーフレームについて使用するオフセットも計算される。 これらの値を解決した結果が 計算済みキーフレームの集合である。

null の各 キーフレームオフセットについて 適切な値を含む、キーフレームの集合の 計算された キーフレーム オフセットを 計算済みキーフレームオフセットと呼ぶ。

計算済みキーフレームオフセットを生成するため、 キーフレームのシーケンス keyframes を受け取り、 次の手順を持つ 欠落した キーフレームオフセットを計算する手順を定義する:

1. keyframes 内の各 キーフレームについて、 キーフレームの 計算済みキーフレームオフセットを、その キーフレームオフセットの値に等しいものとする。

2. keyframes が複数の キーフレームを含み、 keyframes の最初の キーフレームの 計算済みキーフレーム オフセットが null である場合、 最初の キーフレームの 計算済みキーフレームオフセットを 0 に設定する。

3. keyframes 内の最後の キーフレームの 計算済みキーフレームオフセットが null である場合、 その 計算済みキーフレーム オフセットを 1 に設定する。

4. 次の条件を満たす キーフレーム A と B の各組について:

   • A は keyframes 内で B より前にあり、かつ

   • A と B は null ではない 計算済みキーフレーム オフセットを持ち、かつ

   • A と B の間にあるすべての キーフレームは null の 計算済み キーフレームオフセットを持つ。

   A と B の間の各 キーフレームの 計算済みキーフレームオフセットを 次のように計算する:

   1. offset_k を、 キーフレーム k の 計算済み キーフレームオフセットとする。

   2. n を、A と B の間および それら自身を含むキーフレーム数から 1 を引いた値とする。

   3. index を、A と B の間の キーフレームのシーケンス内における keyframe の位置を表すものとし、 A の直後の最初のキーフレームの index を 1 とする。

   4. keyframe の 計算済みキーフレームオフセットを、 offset_A + (offset_B − offset_A) × index / n に設定する。

計算済みキーフレームは、 次の手順を使用して生成される。 この手順は、計算済みプロパティ値を計算できる 効果ターゲットを持つ キーフレーム効果に対してのみ実行されることに注意。

1. computed keyframes を、キーフレームの空のリストとする。

2. この キーフレーム 効果に指定された キーフレームのリスト内の各 keyframe について、 次の手順を実行する:

   1. 新しい空の キーフレーム computed keyframe を computed keyframes に追加する。

   2. keyframe で指定された各プロパティについて:

      • keyframe に指定された値を値として、 対象要素を要素として使用し、 プロパティ値を計算する。 次に、そのプロパティと結果の値を computed keyframe に追加する。

      • 略式プロパティについては、同等の個別指定プロパティを追加する。

      • 論理プロパティ [CSS-LOGICAL-1] については、 効果ターゲットの writing-mode および／または direction の計算値に基づいて、 同等の物理 プロパティ [CSS-WRITING-MODES-4] を追加する。

      たとえば、keyframe が border-width プロパティについて "12pt" の値を持つ場合、 ユーザーエージェントは次の各個別指定プロパティについて "16px" の プロパティ値を計算できる: border-bottom-width、border-left-width、border-right-width、および border-top-width。 その結果、computed keyframe は border-width プロパティの値を持たず、代わりに 各個別指定プロパティをそれぞれ "16px" の値で含む。

      略式プロパティを展開したとき、または論理プロパティを物理プロパティに置き換えたときに 競合が発生した場合は、競合が解決されるまで、 次の規則を順に適用する:

      1. 個別指定プロパティは略式プロパティを上書きする （例: border-top-color は border-top を上書きする）。

      2. 含む個別指定プロパティ数が少ない略式プロパティは、 より多くの個別指定プロパティを含むものを上書きする （例: border-top は border-color を上書きする）。

      3. 物理プロパティは論理プロパティを上書きする。

      4. 同数の個別指定成分を持つ略式プロパティでは、 各 IDL 名を構成する Unicode コードポイントによって昇順に並べたときに、 IDL 名（CSS プロパティから IDL 属性へのアルゴリズム [CSSOM] を参照）がより前に現れるプロパティが、 後に現れるものを上書きする。

3. computed keyframes に 欠落したキーフレームオフセットを計算する手順を適用する。

4. computed keyframes を返す。

5.3.4. キーフレーム効果の効果値

キーフレーム 効果がその 対象プロパティの1つとして参照する単一のプロパティの 効果値は、 与えられた iteration progress、current iteration、および underlying value について、次のように計算される。

1. iteration progress が 未解決である場合、この手順を中止する。

2. target property を、効果値を計算する対象となる 個別指定プロパティとする。

3. target property の アニメーション型が アニメーション不可である場合、 効果を適用できないため、この手順を中止する。

4. キーフレーム 効果が 効果ターゲットを持たない場合、 または 効果ターゲットについて 計算済みプロパティ値を計算できない場合、この手順を中止する。

5. 合成用の中立値を、 基底値と add 合成 操作を使用して結合したときに、 基底値を生成する値として定義する。

6. property-specific keyframes を、この キーフレーム 効果の 計算済みキーフレームの集合を取得した結果とする。

7. target property のプロパティ値を持たない キーフレームを property-specific keyframes から削除する。

8. property-specific keyframes が空の場合、underlying value を返す。

9. property-specific keyframes 内に 計算済みキーフレームオフセットが 0 の キーフレームがない場合、 計算済みキーフレームオフセットが 0、プロパティ値が 合成用の 中立値、合成操作が add である新しい キーフレームを作成し、 property-specific keyframes の先頭に追加する。

10. 同様に、property-specific keyframes 内に 計算済みキーフレーム オフセットが 1 の キーフレームがない場合、 計算済みキーフレームオフセットが 1、 プロパティ値が 合成用の中立値、 合成操作が add である新しい キーフレームを作成し、 property-specific keyframes の末尾に追加する。

11. interval endpoints をキーフレームの空のシーケンスとする。

12. 次のうち最初に一致する条件の手順に従って interval endpoints を設定する:

    iteration progress < 0 であり、 property-specific keyframes 内に 計算済みキーフレームオフセットが 0 の キーフレームが 複数ある場合、

    property-specific keyframes 内の最初の キーフレームを interval endpoints に追加する。

    iteration progress ≥ 1 であり、 property-specific keyframes 内に 計算済みキーフレームオフセットが 1 の キーフレームが 複数ある場合、

    property-specific keyframes 内の最後の キーフレームを interval endpoints に追加する。

    それ以外の場合、

    1. property-specific keyframes 内で、計算済みキーフレームオフセットが iteration progress 以下かつ 1 未満である 最後の キーフレームを interval endpoints に追加する。そのような キーフレームがない場合 （たとえば 反復進行度が負の場合）、 計算済みキーフレームオフセットが 0 の最後の キーフレームを追加する。

    2. 前の手順で追加されたものの次にある property-specific keyframes 内の キーフレームを interval endpoints に追加する。

13. interval endpoints 内の各 keyframe について:

    1. keyframe が 合成操作を持ち、その操作が replaceではない場合、 または keyframe に 合成操作がなく、この キーフレーム 効果の 合成操作が replaceではない場合、 次の手順を実行する:

       1. composite operation to use を keyframe の 合成 操作、またはそれがない場合はこの キーフレーム効果の 合成操作とする。

       2. value to combine を、keyframe に指定された target property のプロパティ値とする。

       3. keyframe 上の target property のプロパティ値を、 target property の アニメーション型に対応する composite operation to use の手順を使用して、 underlying value（V_a）と value to combine（V_b）を 結合した結果に置き換える。

14. interval endpoints にキーフレームが1つだけある場合、 そのキーフレーム上の target property のプロパティ値を返す。

15. start offset を、interval endpoints の最初のキーフレームの 計算済みキーフレームオフセットとする。

16. end offset を、interval endpoints の最後のキーフレームの 計算済みキーフレームオフセットとする。

17. interval distance を (iteration progress - start offset) / (end offset - start offset) を評価した結果とする。

18. transformed distance を、interval endpoints の最初のキーフレームに 関連付けられた タイミング関数を、 interval distance を入力進行度として渡して評価した結果とする。

19. target property の アニメーション 型によって定義される 補間手順を、 interval endpoints 内の2つのキーフレームに指定された target property の値に適用した結果を返す。 最初の値を V_start、2番目の値を V_end とし、 transformed distance を補間パラメーター p として使用する。

注: この手順では、重複する キーフレームが許可される。 重複位置では、出力値がそのオフセットで最後に定義された キーフレームの値に飛ぶ。 0 または 1 で重複するキーフレームについて、 反復 進行度が 0 未満または 1 以上である場合の出力値は、それぞれ keyframes 内の最初の キーフレームまたは最後の キーフレームの値となる。

5.4. 効果の結合

この節は非規範的である

キーフレーム効果の 効果 値を計算した後、それらは アニメーション 効果の 対象 プロパティに適用される。

複数の 効果 中の キーフレーム 効果が同じプロパティを対象にできるため、 複数の キーフレーム効果の結果を結合する必要があることが多い。 この処理を 合成と呼び、 効果中の アニメーション効果が対象とする各プロパティについて 効果スタックを 確立することに基づく。

キーフレーム 効果の結果を 合成した後、 その合成結果は 対象プロパティに指定された他の値と結合される。

その構成を以下に示す:

この処理の最初の部分、すなわち同じ プロパティを対象とする 効果値を結合するためには、 キーフレーム効果を互いにどのように結合するかだけでなく、 それらを適用する順序、すなわち相対的な合成順序も 決定する必要がある。

効果 値をどのように結合するかは、 対応する キーフレーム効果の 合成操作によって決定される。

効果値の相対的な合成順序は、 各アニメーション対象プロパティについて確立される 効果スタックによって決定される。

5.4.1. アニメーションクラス

この仕様は、このモデル上にマークアップまたはプログラミングインターフェイスを 定義する他の仕様によって使用されることを意図した共通のアニメーションモデルを提供する。 アニメーションを生成した特定のマークアップまたは プログラミングインターフェイスが、その アニメーションクラスを定義する。

後続の仕様では、異なるアニメーションクラス間、または特定のクラス内での 合成順序について、特殊な動作を定義できる。

5.4.2. 効果スタック

効果スタックは、1つ以上の キーフレーム効果によって 対象とされる各プロパティに 関連付けられる。 効果スタックは、 キーフレーム効果の相対的な合成順序を確立する。

キーフレーム効果 A および B の任意の2つについて、 効果スタック内での相対的な 合成順序は、 次のようにそれらのプロパティを比較することで確立される:

1. アニメーション効果に関連付けられたアニメーションを、 アニメーション効果に 関連付けられた アニメーションとする。

2. 順序が決定されるまで、次の条件を順に適用して A と B を並べ替える。

   1. A と B の 関連付けられたアニメーションが クラスによって異なる場合、 対応するクラスについて定義されたクラス間の合成順序に従って並べ替える。

   2. A と B がまだ並べ替えられていない場合、 A と B の 関連付けられたアニメーションに共通する クラスによって定義された、 クラス固有の合成順序に従って並べ替える。

   3. A と B がまだ並べ替えられていない場合、 それらの 関連付けられたアニメーションの グローバルアニメーションリスト内での位置に従って並べ替える。

より前に並べられる アニメーション効果は、 より低い合成順序を持つ。

5.4.3. 効果スタックの結果の計算

効果スタックの最終値を計算するために、 スタック内の各 キーフレーム効果の 効果値を 合成順序で結合する。

効果スタックを評価する処理の各段階では、 基底値を 入力として受け取る。

スタック内の各 キーフレーム効果について、 キーフレーム 効果から適切な 効果値を 基底値と結合して、新しい値を生成する。 この結果の値は、スタック内の次の キーフレーム効果を 結合するための 基底値となる。

効果 スタックの最終値は 合成値と呼ばれ、単にスタック内で最後の （最も高い合成順序を持つ） キーフレーム効果の 効果値を、 その時点での 基底値と結合した結果である。

5.4.4. 効果の合成

効果値を 基底値と結合するために使用される具体的な操作は、 効果値を生成した キーフレーム効果の 合成操作によって決定される。

この仕様では、3つの 合成操作を 次のように定義する:

replace

効果値を 基底値と合成した結果は、 単に 効果値となる。

add

効果値は 基底 値に 加算される。 加算操作が可換ではないように定義されている アニメーション型では、 オペランドの順序は 基底値 + 効果値 となる。

accumulate

効果値は 基底値に 累積される。 累積操作が可換ではないように定義されている アニメーション型では、 オペランドの順序は 基底値の後に 効果値となる。

5.4.5. 合成結果の適用

合成 値を 対象 プロパティに適用するには、指定値を CSS カスケードに追加する。

この指定値が追加されるカスケードのレベルは、 あるプロパティの 効果スタック内で最も高い合成順序を持つ効果に 関連付けられた アニメーションの クラスによって決まる。 既定では、指定値はカスケードの "Animation declarations" レベルに追加される（[css-cascade-3]）。

CSS の 対象 プロパティについて計算された 合成値は、 次の処理を使用して適用される。

1. アニメーションが存在しない状態でそのプロパティの計算値を計算して 生成される値を、そのプロパティの base value として計算する。

2. そのプロパティの 効果 スタックを確立する（§ 5.4.2 効果スタックを参照）。

3. プロパティの base value を初期 基底値として渡し、 効果 スタックの 合成値を計算する （§ 5.4.3 効果スタックの結果の計算を参照）。

4. 対象プロパティについて確立された 効果スタックの最上位の効果に 関連付けられた アニメーションの クラスについて定義されたレベルで、 合成 値を CSS カスケードへ挿入する。

5.5. アニメーションの置換

elem.addEventListener('mousemove', evt => {
  circle.animate(
    { transform: `translate(${evt.clientX}px, ${evt.clientY}px)` },
    { duration: 500, fill: 'forwards' }
  );
});

5.5.1. 置換状態

アニメーションは、 次の値のいずれかとなる 置換状態を保持する:

• active

• removed

• persisted

アニメーションの 置換状態の初期値は active である。

置換状態が removed である アニメーションの アニメーション効果は、 その 対象 プロパティの 効果 スタックに含まれない。

5.5.2. 置換されたアニメーションの削除

アニメーションは、 次の条件がすべて真である場合、 置換可能である:

• アニメーションの存在がマークアップによって規定されていない。 すなわち、所有要素を持つ CSS アニメーションでも、 所有要素を持つ CSS トランジションでもない。

• アニメーションの 再生状態が 完了である。

• アニメーションの 置換状態が removedではない。

• アニメーションが 単調増加する タイムラインに関連付けられている。

• アニメーションに 関連付けられた効果がある。

• アニメーションの 関連付けられた 効果が 効果中である。

• アニメーションの 関連付けられた 効果に 効果ターゲットがある。

Document doc について 置換されたアニメーションを削除するよう求められた場合、 次の条件を満たすすべての アニメーション animation について:

• doc の 子孫である 効果ターゲットを持つ アニメーション効果が 関連付けられており、かつ

• 置換可能であり、かつ

• 置換状態が active であり、かつ

• animation に 関連付けられたすべての アニメーション効果の 各 対象プロパティについて、 animation より高い 合成順序を持つ 置換可能な アニメーションに関連付けられた アニメーション効果が存在し、 同じ 対象プロパティを含む

次の手順を実行する:

1. animation の 置換状態を removed に設定する。

2. AnimationPlaybackEvent removeEvent を 作成する。

3. removeEvent の type 属性を remove に設定する。

4. removeEvent の currentTime 属性を animation の 現在時刻に設定する。

5. removeEvent の timelineTime 属性を、animation が関連付けられている タイムラインの 現在時刻に設定する。

6. animation に タイミング用文書がある場合、 removeEvent を、その タイミング用 文書の 保留中のアニメーションイベントキューに、 そのターゲット animation とともに追加する。 予定イベント時刻には、 animation が関連付けられている タイムラインの 現在時刻に、 タイムライン時刻をオリジン相対時刻に変換する手順を 適用した結果を使用する。

   それ以外の場合、animation に removeEvent を 配送するためのタスクを キューに入れる。 このタスクのタスクソースは DOM 操作タスク ソースである。

5.6. アニメーションの副作用

現在または 効果中であり、 かつ 置換状態が removedではない アニメーションに関連付けられた アニメーション効果の少なくとも1つによって対象とされる すべてのプロパティについて、ユーザーエージェントは 効果ターゲットの will-change プロパティ （[css-will-change-1]）に、そのプロパティが含まれているかのように 動作しなければならない。

6. プログラミングインターフェイス

6.1. プログラミングインターフェイスにおける時間値

時間値は、 プログラミングインターフェイスでは double 型で表される。未解決の時間値は null 値で表される。

6.2. AnimationTimeline インターフェイス

タイムラインは、Web Animations API では AnimationTimeline インターフェイスによって表される。

[Exposed=Window]
interface AnimationTimeline {
    readonly attribute double? currentTime;
};

6.3. DocumentTimeline インターフェイス

文書タイムラインは、 既定の文書 タイムラインを含め、Web Animations API では DocumentTimeline インターフェイスによって表される。

dictionary DocumentTimelineOptions {
  DOMHighResTimeStamp originTime = 0;
};

[Exposed=Window]
interface DocumentTimeline : AnimationTimeline {
  constructor(optional DocumentTimelineOptions options = {});
};

6.4. Animation インターフェイス

アニメーションは、 Web Animations API では Animation インターフェイスによって表される。

[Exposed=Window]
interface Animation : EventTarget {
    constructor(optional AnimationEffect? effect = null,
                optional AnimationTimeline? timeline);
             attribute DOMString                id;
             attribute AnimationEffect?         effect;
             attribute AnimationTimeline?       timeline;
             attribute double?                  startTime;
             attribute double?                  currentTime;
             attribute double                   playbackRate;
    readonly attribute AnimationPlayState       playState;
    readonly attribute AnimationReplaceState    replaceState;
    readonly attribute boolean                  pending;
    readonly attribute Promise<Animation>       ready;
    readonly attribute Promise<Animation>       finished;
             attribute EventHandler             onfinish;
             attribute EventHandler             oncancel;
             attribute EventHandler             onremove;
    undefined cancel();
    undefined finish();
    undefined play();
    undefined pause();
    undefined updatePlaybackRate(double playbackRate);
    undefined reverse();
    undefined persist();
    [CEReactions]
    undefined commitStyles();
};

計算済みスタイルをコミットするには、アニメーション animation に対して:

1. targets を、animation に関連付けられた アニメーション効果の すべての 効果ターゲットからなる 集合とする。

2. targets 内のtargetごとに次を実行する:

   1. target が style 属性 [CSS-STYLE-ATTR] を持つことができる要素ではない場合 （たとえば、疑似要素であるか、 style 属性が定義されていない文書形式内の要素である場合）、 "NoModificationAllowedError" DOMException を投げ、 これらの手順を中止する。

   2. 保留中のスタイル変更を適用した後、target がレンダリングされていない場合、 "InvalidStateError" DOMException を投げ、 これらの手順を中止する。

      レンダリングされている [HTML] の定義における display: contents の扱いについては、現在も議論中である。 この手順の目的上、それ以外であれば 関連付けられたレイアウトボックスを持つ display: contents の要素（すなわち、接続されており、 display: none サブツリーの一部ではない要素）は、 レンダリングされているものと仮定する。

   3. inline style を、target の style 属性に対応する CSS 宣言ブロックを取得した結果とする。 target が style 属性を持たない場合、 inline style を、所有者ノードを target に設定した 新しい空の CSS 宣言ブロックとする。

   4. targeted properties を、target を 効果ターゲットとする、 animation に関連付けられた少なくとも1つの アニメーション 効果の 対象プロパティである 物理個別指定プロパティの 集合とする。

   5. targeted properties 内の各プロパティ property について:

      1. partialEffectStack を、target 上の property の 効果スタックのコピーとする。

      2. animation の 置換状態が removed である場合、 animation に関連付けられたすべての アニメーション効果のうち、 効果ターゲットが target であり、property を 対象プロパティとして含むものを、 partialEffectStack に追加する。

      3. partialEffectStack から、それに関連付けられた アニメーションが animation より高い 合成順序を持つ アニメーション効果を すべて削除する。

      4. effect value を、target の計算済み スタイルを使用して property の partialEffectStack の結果を計算した結果とする （§ 5.4.3 効果スタックの 結果の計算を参照）。

      5. inline style 内で、property を effect value にする CSS 宣言を設定する。

   6. inline style についてstyle 属性を更新する。

6.4.1. AnimationPlayState 列挙型

enum AnimationPlayState { "idle", "running", "paused", "finished" };

idle

アイドル 再生状態に対応する。

running

実行中再生状態に対応する。

paused

一時停止中再生状態に対応する。

finished

完了再生状態に対応する。

6.4.2. AnimationReplaceState 列挙型

enum AnimationReplaceState { "active", "removed", "persisted" };

active

active 置換状態に対応する。

removed

removed 置換状態に対応する。

persisted

persisted 置換状態に対応する。

6.5. AnimationEffect インターフェイス

アニメーション効果は、 Web Animations API では抽象 AnimationEffect インターフェイスによって表される。

[Exposed=Window]
interface AnimationEffect {
    EffectTiming         getTiming();
    ComputedEffectTiming getComputedTiming();
    undefined            updateTiming(optional OptionalEffectTiming timing = {});
};

remove() メソッドは、効果をその親グループまたはアニメーションのいずれからも削除するために使用できる。 レベル1に残し、単にアニメーション効果をそのアニメーションから削除するものとして 定義すべきだろうか？ [Issue #2082]

6.5.1. EffectTiming および OptionalEffectTiming 辞書

EffectTiming 辞書は、AnimationEffect のタイミングプロパティを表す。

OptionalEffectTiming 辞書は、EffectTiming 辞書の変種であり、一部のメンバーが存在しないことを許容する。 これは、AnimationEffect インターフェイスの updateTiming() メソッドが、アニメーション効果の タイミングプロパティを差分更新するために使用する。

dictionary EffectTiming {
    double                             delay = 0;
    double                             endDelay = 0;
    FillMode                           fill = "auto";
    double                             iterationStart = 0.0;
    unrestricted double                iterations = 1.0;
    (unrestricted double or DOMString) duration = "auto";
    PlaybackDirection                  direction = "normal";
    DOMString                          easing = "linear";
};

dictionary OptionalEffectTiming {
    double                             delay;
    double                             endDelay;
    FillMode                           fill;
    double                             iterationStart;
    unrestricted double                iterations;
    (unrestricted double or DOMString) duration;
    PlaybackDirection                  direction;
    DOMString                          easing;
};

6.5.2. FillMode 列挙型

enum FillMode { "none", "forwards", "backwards", "both", "auto" };

none

フィルしない。

forwards

順方向にフィルする。

backwards

逆方向にフィルする。

both

逆方向と順方向の両方にフィルする。

auto

フィルしない。 この仕様の後続レベルでは、他の種類の アニメーション効果に対して異なる 動作を生成する可能性がある。

6.5.3. PlaybackDirection 列挙型

enum PlaybackDirection { "normal", "reverse", "alternate", "alternate-reverse" };

normal

すべての反復を指定されたとおりに再生する。

reverse

すべての反復を、指定された順序とは逆の方向に再生する。

alternate

偶数回の反復は指定されたとおりに再生し、奇数回の反復は 指定された順序とは逆の方向に再生する。

alternate-reverse

偶数回の反復は指定された順序とは逆の方向に再生し、 奇数回の反復は指定されたとおりに再生する。

6.5.4. AnimationEffect のタイミングの更新

EffectTiming または OptionalEffectTiming オブジェクト input から、effect の アニメーション 効果のタイミングプロパティを更新するには、 次の手順を実行する:

1. input の iterationStart メンバーが存在し、かつゼロ未満である場合、 TypeError を投げ、 この手順を中止する。

   注: RangeError ではなく TypeError を使用する理由は、 将来この注釈を浮動小数点値に使用できるようになった場合に、 WebIDL の [EnforceRange] 注釈の動作を 模倣するためである。

2. input の iterations メンバーが存在し、 かつゼロ未満であるか値 NaN である場合、 TypeError を投げ、 この手順を中止する。

3. input の duration メンバーが存在し、 かつゼロ未満であるか値 NaN である場合、 TypeError を投げ、 この手順を中止する。

4. input の easing メンバーが存在するが、<easing-function> 生成規則 [CSS-EASING-1]を使用して 構文解析できない場合、TypeError を投げ、この手順を中止する。

5. input に存在する各メンバーを、 次のように effect の対応するタイミングプロパティに割り当てる:

   • delay → 開始遅延

   • endDelay → 終了遅延

   • fill → フィルモード

   • iterationStart → 反復 開始

   • iterations → 反復 回数

   • duration → 反復持続時間

   • direction → 再生方向

   • easing → タイミング関数

6.5.5. ComputedEffectTiming 辞書

タイミングモデルによって計算されたタイミングプロパティは、ComputedEffectTiming 辞書オブジェクトを使用して公開される。

dictionary ComputedEffectTiming : EffectTiming {
    unrestricted double  endTime;
    unrestricted double  activeDuration;
    double?              localTime;
    double?              progress;
    unrestricted double? currentIteration;
};

6.6. KeyframeEffect インターフェイス

キーフレーム効果は、 KeyframeEffect インターフェイスによって表される。

[Exposed=Window]
interface KeyframeEffect : AnimationEffect {
    constructor(Element? target,
                object? keyframes,
                optional (unrestricted double or KeyframeEffectOptions) options = {});
    constructor(KeyframeEffect source);
    attribute Element?           target;
    attribute CSSOMString?       pseudoElement;
    attribute CompositeOperation composite;
    sequence<object> getKeyframes();
    undefined        setKeyframes(object? keyframes);
};

6.6.1. 新しい KeyframeEffect オブジェクトの作成

var effect = new KeyframeEffect(elem, { left: '100px' }, 3000);

// 複数のプロパティを一度に指定する
var effectA = new KeyframeEffect(elem, { left: '100px', top: '300px' }, 3000);

// 複数のキーフレームを指定する
var effectB = new KeyframeEffect(elem, [ { left: '100px' }, { left: '300px' } ], 3000);

var effect =
  new KeyframeEffect(elem, { left: '100px' }, { duration: 3000, delay: 2000 });

var effect =
  new KeyframeEffect(elem, { visibility: 'hidden' }, { fill: 'forwards' });

elem.animate({ left: '100px' }, 3000);

6.6.2. プロパティ名と IDL 名

property に対する アニメーションプロパティ名から IDL 属性名へ のアルゴリズムは次のとおり:

1. property が <custom-property-name> 生成規則に従う場合、 property を返す。

2. property が CSS の float プロパティを参照する場合、 文字列 "cssFloat" を返す。

3. property が CSS の offset プロパティを参照する場合、 文字列 "cssOffset" を返す。

4. それ以外の場合、property に CSS プロパティから IDL 属性へアルゴリズム [CSSOM]を適用した 結果を返す。

attribute に対する IDL 属性名からアニメーションプロパティ名へ のアルゴリズムは次のとおり:

1. attribute が <custom-property-name> 生成規則に従う場合、 attribute を返す。

2. attribute が文字列 "cssFloat" である場合、 CSS の float プロパティを表すアニメーションプロパティを返す。

3. attribute が文字列 "cssOffset" である場合、 CSS の offset プロパティを表すアニメーションプロパティを返す。

4. それ以外の場合、attribute に IDL 属性から CSS プロパティへアルゴリズム [CSSOM]を適用した 結果を返す。

6.6.3. keyframes 引数の処理

// 次の2つの式は同じ結果を生成する:
elem.animate([ { color: 'blue' },
               { color: 'green' },
               { color: 'red' },
               { color: 'yellow' } ], 2000);
elem.animate({ color: [ 'blue', 'green', 'red', 'yellow' ] }, 2000);

// 同様に、複数プロパティのアニメーションでは、次の2つの
// 式は同等である:
elem.animate([ { color: 'blue', left: '0px' },
               { color: 'green', left: '-20px' },
               { color: 'red', left: '100px' },
               { color: 'yellow', left: '50px'} ], 2000);
elem.animate({ color: [ 'blue', 'green', 'red', 'yellow' ],
               left: [ '0px', '-20px', '100px', '50px' ] }, 2000);

// ちなみに、次の3つの式はいずれも同等である:
elem.animate([ { color: 'red' } ], 1000);
elem.animate({ color: [ 'red' ] }, 1000);
elem.animate({ color: 'red' }, 1000);

// オフセットのないキーフレームには、最初のキーフレームに 0、
// 中間のキーフレームに 0.65、最後のキーフレームに 1 が
// 自動的に計算される。
elem.animate([ { color: 'blue' },
               { color: 'green', offset: 0.5 },
               { color: 'red' },
               { color: 'yellow', offset: 0.8 },
               { color: 'pink' } ], 2000);

// 次も同じ結果を生成する。最後の値を指定する必要はなく、
// 自動的に 'null' として扱われ、その後、前の例と同様に
// 自動割り当てが適用されることに注意。
elem.animate({ color: [ 'blue', 'green', 'red', 'yellow', 'pink' ],
               offset: [ null, 0.5, null, 0.8 ] }, 2000);

// タイミング関数はキーフレームの_間_に適用されるため、
// 最後のキーフレームにタイミング関数を指定しても無視される。
elem.animate([ { color: 'blue', easing: 'ease-in' },
               { color: 'green', easing: 'ease-out' },
               { color: 'yellow' } ], 2000);

// 次も同じ結果を生成する。
elem.animate({ color: [ 'blue', 'green', 'yellow' ],
               easing: [ 'ease-in', 'ease-out' ] }, 2000);

// 反復動作により、すべてのキーフレームへ同じ値を割り当てることが
// 簡単になる:
elem.animate({ color: [ 'blue', 'green', 'yellow' ],
               easing: 'ease-in-out' }, 2000);

// ここでは、'ease-in-out' が各色値の間に適用される。
elem.animate({ color: [ 'blue', 'green', 'yellow' ],
               easing: 'ease-in-out' }, 2000);

// ただし、この場合、'ease-in-out' はアニメーション全体、
// すなわち 'blue' から 'yellow' までに適用される。
elem.animate({ color: [ 'blue', 'green', 'yellow' ] },
             { duration: 2000, easing: 'ease-in-out' });

dictionary Keyframe {
    // ... プロパティと値のペア ...
    // すなわち DOMString propertyName
    double?                   offset = null;
    DOMString                 easing = "linear";
    CompositeOperationOrAuto  composite = "auto";
};

dictionary PropertyIndexedKeyframes {
    // ... プロパティと値、およびプロパティと値リストのペア ...
    // すなわち (DOMString or sequence<DOMString>) propertyName
    (double? or sequence<double?>)                         offset = [];
    (DOMString or sequence<DOMString>)                     easing = [];
    (CompositeOperationOrAuto or sequence<CompositeOperationOrAuto>) composite = [];
};

typedef (sequence<Keyframe> or PropertyIndexedKeyframes) KeyframeArgument;

keyframes 引数を取る各メソッドについて、入力に対して keyframes 引数を処理する手順を実行し、 その手順の結果を保持する。

まず、2つの補助的な定義を定義する。

ECMAScript 操作を呼び出して得られた 完了レコード result について、 result の完了レコードを確認するという命令は、 次の手順と同等である:

1. result が 突然の完了である場合、 result の [[value]] フィールドに含まれる例外を投げ、この手順を中止する。

   [[type]] が break、continue、または return の場合、どうすべきか？ そのようなことはあり得るか？

2. result を、result の [[value]] フィールドに 含まれる値で置き換える。

キーフレーム風オブジェクトを処理する手順は、 次の2つの引数を取る:

• ECMAScript オブジェクト keyframe input、および

• allow lists 真偽値フラグ

そして、allow lists が false の場合はプロパティ名から DOMString 値へのマップを、 それ以外の場合はプロパティ名から DOMString 値のシーケンスへのマップを、 次の手順を使用して返す:

1. keyframe input を ECMAScript 値とし、 allow lists フラグの値に応じて次の辞書型を使用して、 ECMAScript 値を辞書型へ変換する手順 [WEBIDL] を実行する:

   allow lists が true の場合、

   次の辞書型を使用する:

   dictionary BasePropertyIndexedKeyframe {
       (double? or sequence<double?>)                         offset = [];
       (DOMString or sequence<DOMString>)                     easing = [];
       (CompositeOperationOrAuto or sequence<CompositeOperationOrAuto>) composite = [];
   };
   

   それ以外の場合、

   次の辞書型を使用する。

   dictionary BaseKeyframe {
       double?                  offset = null;
       DOMString                easing = "linear";
       CompositeOperationOrAuto composite = "auto";
   };
   

   この手順の結果を keyframe output として格納する。

2. animatable properties のリストを次のように構築する:

   1. animatable properties を、実装によってアニメーション可能な プロパティ名（アニメーション可能な個別指定サブプロパティを持つ 略式プロパティを含む）のリストとする。

   2. animatable properties 内の各プロパティ名に アニメーションプロパティ名から IDL 属性名へアルゴリズムを適用し、 等価な IDL 属性へ変換する。

3. input properties を、keyframe input をオブジェクトとして EnumerableOwnNames 操作を呼び出した結果とする。

4. 両方の input properties と animatable properties に含まれるプロパティ、 または input properties に含まれ、かつ <custom-property-name> 生成規則に従う プロパティすべてからなる、新しいリスト animation properties を作成する。

5. animation properties を、それぞれのプロパティ名を定義する Unicode コードポイントによって昇順に並べ替える。

6. animation properties 内の各 property name について、

   1. raw value を、keyframe input 上で property name をプロパティキー、keyframe input を レシーバーとして [[Get]] 内部メソッドを呼び出した結果とする。

   2. raw value の完了レコードを確認する。

   3. raw value を、次のように DOMString または DOMString のシーケンス property values に変換する:

      allow lists が true の場合、

      property values を、 ECMAScript 値を IDL 値に変換するために定義された手順 [WEBIDL]を使用して、 raw value を IDL 型 (DOMString or sequence<DOMString>) に変換した結果とする。

      property values が単一の DOMString である場合、 property values を、その元の値を唯一の要素とする DOMString のシーケンスで置き換える。

      それ以外の場合、

      property values を、 ECMAScript 値を DOMString に変換する手順 [WEBIDL]を使用して、 raw value を DOMString に変換した結果とする。

   4. normalized property name を、property name に IDL 属性名から アニメーションプロパティ名へアルゴリズムを適用した結果として計算する。

   5. keyframe output に、プロパティ名として normalized property name、プロパティ値として property values を持つ プロパティを追加する。

7. keyframe output を返す。

keyframes 引数を処理する手順は、null 許容の ECMAScript オブジェクト object を入力として受け取り、 次の手順を使用してキーフレームのシーケンスを返す:

1. object が null の場合、空のキーフレームシーケンスを返す。

2. processed keyframes を キーフレームの空のシーケンスとする。

3. method を GetMethod(object, @@iterator) の結果とする。

4. method の完了レコードを確認する。

5. 以下のうち最初に一致する条件に対応する手順を実行する。

   method が undefined ではない場合、

   1. iter を GetIterator(object, method) とする。

   2. iter の完了レコードを確認する。

   3. 次を繰り返す:

      1. next を IteratorStep(iter) とする。

      2. next の完了 レコードを確認する。

      3. next が false の場合、このループを中止する。

      4. nextItem を IteratorValue(next) とする。

      5. nextItem の完了 レコードを確認する。

      6. Type(nextItem) が Undefined、Null、Object のいずれでもない場合、 TypeError を投げ、 これらの手順を中止する。

      7. nextItem を keyframe input として渡し、allow lists フラグを false に設定して キーフレーム風 オブジェクトを処理する手順を実行した結果を、 processed keyframes に追加する。

   それ以外の場合、

   1. object を keyframe input として渡し、 allow lists フラグを true に設定して キーフレーム風 オブジェクトを処理する手順を実行した結果を、 property-indexed keyframe とする。

   2. property-indexed keyframe 内の各メンバー m について、次の手順を実行する:

      1. property name を m のキーとする。

      2. property name が "composite"、"easing"、または "offset" の場合、このループの残りの手順を省略し、 property-indexed keyframe 内で m の 次のメンバーから続行する。

      3. property values を m の値とする。

      4. property keyframes を キーフレームの空のシーケンスとする。

      5. property values 内の各値 v について、 次の手順を実行する:

         1. k を、null の キーフレームオフセットを持つ 新しい キーフレームとする。

         2. プロパティと値のペア property name → v を k に追加する。

         3. k を property keyframes に追加する。

      6. property keyframes に 欠落した キーフレーム オフセットを計算する手順を適用する。

      7. property keyframes 内の キーフレームを processed keyframes に追加する。

   3. processed keyframes を、各 キーフレームの 計算済み キーフレームオフセットによって昇順に並べ替える。

   4. processed keyframes 内で、等しい 計算済みキーフレームオフセットを持つ 隣接する キーフレームをマージする。

   5. offsets を、property-indexed keyframe の "offset" メンバーの型に基づいて 次のように割り当てられる null 許容の double 値の シーケンスとする:

      sequence<double?>,

      "offset" の値をそのまま使用する。

      double?,

      "offset" の値を唯一の項目とする長さ1のシーケンス、 すなわち « offset »、

   6. いずれかのシーケンスの末尾に到達するまで、 offsets 内の各値を processed keyframes 内の 対応する位置にある キーフレームの キーフレーム オフセットに割り当てる。

   7. easings を、property-indexed keyframe の "easing" メンバーの型に基づいて次のように割り当てられる DOMString 値のシーケンスとする:

      sequence<DOMString>,

      "easing" の値をそのまま使用する。

      DOMString,

      "easing" の値を唯一の項目とする長さ1のシーケンス、 すなわち « easing »、

   8. easings が空のシーケンスである場合、 単一の値 "linear" を含む長さ1のシーケンス、 すなわち « "linear" » とする。

   9. easings の項目数が processed keyframes より少ない場合、easings の要素を リストの先頭から順に反復し、easings が processed keyframes と同じ項目数になるまで続ける。

      たとえば、processed keyframes が5項目を持ち、easings がシーケンス « "ease-in", "ease-out" » である場合、easings は反復され、 « "ease-in", "ease-out", "ease-in", "ease-out", "ease-in" » となる。

   10. easings の項目数が processed keyframes より多い場合、余分な項目を unused easings として格納する。

   11. processed keyframes の末尾に到達するまで、easings 内の各値を processed keyframes 内の対応する位置にある キーフレーム上の "easing" という名前のプロパティに割り当てる。

   12. property-indexed keyframe の "composite" メンバーが空のシーケンスではない場合:

       1. composite modes を、 property-indexed keyframe の "composite" メンバーから割り当てられた CompositeOperationOrAuto 値のシーケンスとする。 そのメンバーが単一の CompositeOperationOrAuto 値である場合、composite modes を "composite" の値を唯一の項目とする 長さ1のシーケンスとする。

       2. easings と同様に、composite modes の項目数が processed keyframes より少ない場合、 composite modes の要素をリストの先頭から順に反復し、 composite modes が processed keyframes と 同じ項目数になるまで続ける。

       3. processed keyframes の末尾に到達するまで、 composite modes 内の auto ではない各値を、processed keyframes 内の対応する位置にある キーフレーム上の キーフレーム固有の 合成操作に割り当てる。

6. processed keyframes が オフセットによって 緩やかにソートされていない場合、TypeError を投げ、これらの手順を中止する。

7. processed keyframes 内に、null ではなくゼロ未満または1より大きい キーフレームオフセットを持つ キーフレームが存在する場合、 TypeError を投げ、 これらの手順を中止する。

8. processed keyframes 内の各 frame について、 次の手順を実行する:

   1. frame 内の各プロパティと値のペアについて、 そのプロパティに指定された構文を使用してプロパティ値を構文解析する。

      プロパティ値がそのプロパティの構文に従って無効である場合、 そのプロパティと値のペアを破棄する。 コンテンツ内のエラー診断をサポートするユーザーエージェントは、 無効なプロパティ値を強調する適切な警告を生成するべきである。

   2. frame の タイミング関数を、 EffectTiming 辞書の easing メンバーについて定義された CSS 構文を使用して、 frame 上の "easing" プロパティを構文解析した結果とする。

      "easing" プロパティの構文解析に失敗した場合、 TypeError を投げ、 この手順を中止する。

      注: 上記の両方の手順で CSS パーサーを使用することは、 CSS コメントおよびエスケープが許可されるものの、 値が正常に構文解析された場合には保持されないことを意味する。

      注: "easing" プロパティの構文解析に失敗した場合、 TypeError を、 object からすべてのプロパティを読み取った後に投げることが重要である。 そうしなければその違いが観察可能となり、将来 WebIDL で 部分的に開放された辞書がサポートされた場合の動作と一致しない。

9. unused easings 内の各値を、EffectTiming インターフェイスの easing メンバーについて定義された CSS 構文を使用して構文解析し、 いずれかの値の構文解析に失敗した場合、TypeError を投げ、この手順を中止する。

   この最後の手順は、次のすべての場合に TypeError が投げられるという一貫した動作を 提供するために必要である:

   elem.animate({ easing: 'invalid' });
   elem.animate({ easing: ['invalid'] });
   elem.animate([{ easing: 'invalid' }]);