CSSアニメーション レベル2

1. デルタ仕様

これはデルタ仕様であり、現在はCSS Animations Level 1 [CSS3-ANIMATIONS] からの差分のみを含みます。 Level 1仕様が完成に近づいた時点で、ここに追加された内容と統合されて完全なLevel 2仕様となります。

2. アニメーション

この仕様で定義されたアニメーションプロパティのいずれかに変更があると、 対応する CSSAnimation オブジェクトおよびその関連オブジェクトは、 これらのプロパティと § 3 キーフレームの組み立てで定義されるWeb Animationsの概念との対応に従って更新されます。

ただし、著者がWeb Animationsプログラミングインターフェイスを使用してアニメーションを変更した場合は、 以下のようにプログラミングインターフェイスによる変更が優先されます：

• setKeyframes() を KeyframeEffect （CSSAnimation に関連付けられている）に対して正常に呼び出した後は、 その後に一致する @keyframes 規則や、 対象要素の animation-timing-function プロパティの解決値の変更は そのアニメーションに反映されなくなります。

  ただし、最後に一致する @keyframes 規則が削除された場合は、 アニメーションは必ずキャンセルされなければなりません。

• updateTiming() を KeyframeEffect （CSSAnimation に関連付けられている）に対して正常に呼び出した後は、 timing パラメータに含まれる各プロパティについて、 その後に対応するアニメーションプロパティの変更は そのアニメーションに反映されなくなります。

  例えば、cssAnimation.effect.updateTiming({ duration: 1000 }) を呼び出すと、 その後の animation-duration の変更は無視されますが、 animation-delay の変更は KeyframeEffect の timingに反映され続けます。

• play() または pause() を CSSAnimation に対して正常に呼び出した後は、 その後の animation-play-state の変更によって CSSAnimation が再生または一時停止されることはなくなります（§ 4.5 animation-play-stateプロパティ参照）。

• reverse() を CSSAnimation に対して呼び出した後、 または startTime を CSSAnimation に正常に設定した後、 その呼び出しによって play state が paused play state へと変化した場合、 その後の animation-play-state の変更によって CSSAnimation が再生または一時停止されることはなくなります（§ 4.5 animation-play-stateプロパティ参照）。

  paused play state への変化が必要なのは、 reverse() や startTime の設定後でも、アニメーションが animation-play-state の変更を監視し続けるためです。

• effect を CSSAnimation で null または元の KeyframeEffect 以外の AnimationEffect に正常に設定した場合は、 animation-name や animation-play-state 以外の アニメーションプロパティの変更は そのアニメーションに反映されません。 また、一致する @keyframes 規則の変更も そのアニメーションに反映されません。 ただし、最後に一致する @keyframes 規則が削除された場合は、 アニメーションは必ずキャンセルされなければなりません。

注意、 上記の規則で「正常な呼び出し」が参照されているのは、 これらのメソッドが例外をスローした場合は オーバーライドの挙動が適用されないことを保証するためです。

2.1. 所有要素

所有要素とは、 アニメーションを生成した animation-name プロパティが適用された 要素または疑似要素を指します。

要素の display プロパティが none に設定されていて、 TransitionsとAnimations カスケード起点を無視した場合に display の値が none になるなら、 この 所有要素 の実行中アニメーションを終了します。 要素の display が none で、 TransitionsとAnimations カスケード起点を無視した場合に display の値が none だった場合、 display を none 以外に更新すると animation-name プロパティによって適用された すべてのアニメーションが開始されます。

注意： 実際には、display の値が none へのアニメーションは、 スタイルがアニメーションの効果を除いて none に算出されない限り、 実行中アニメーションを終了しません。

この仕様で定義されたマークアップを使用して生成されたアニメーションが、 後に animation-name プロパティの算出値の更新により 所有要素 から切り離された場合、 そのアニメーションは 所有要素 から切り離されます （つまりその時点から 所有要素 を持ちません）。

elem.style.animation = 'spin 1s';
let animation = elem.getAnimations()[0]; // animationの所有要素はelem
elem.style.animation = ''; // animationはもう所有要素を持たない

elem.style.animation = 'move 1s';
let animation = elem.getAnimations()[0];
// animation.effect.target == elem == animationの所有要素

animation.effect.target = elem2;
// animation.effect.target == elem2 != animationの所有要素

animation.effect = null;
// animation.effect?.targetはundefined != animationの所有要素

2.2. アニメーション合成順序

アニメーション は この仕様で定義されたマークアップから生成された場合、 animation class が「CSS Animation」となります。

所有要素 を持つCSSアニメーションは、 CSSトランジションよりも後、特定の animation class を持たないアニメーションよりも前の合成順序になります。

所有要素 を持つCSSアニメーションの集合内では、 2つのアニメーション A と B の合成順序（先から後）は以下のようにソートされます：

1. 所有要素 が A と B で異なる場合、 A と B は、それぞれの 所有要素 の ツリー順序でソートされます。 疑似要素に関する順序は以下の通りです：

   • element

   • ::marker

   • ::before

   • このリストに特記されていないその他の疑似要素は、 各セレクターを構成するUnicodeコードポイントの昇順でソート

   • ::after

   • elementの子

2. それ以外の場合、A と B は、 共通の animation-name プロパティの算出値における 所有要素 での位置によってソートされます。

所有要素 を持たないCSSアニメーションの合成順序は、 global animation list 内の位置に基づきます。

この挙動はトランジションで定義されているものとは異なります。 おそらく、まずトランジション、次にアニメーション、最後にglobal animation listでソートしたほうが良いでしょう。 なぜなら、開発者ツールなどが孤立したアニメーションやトランジションを保持して再生する場合、 合成順序を大体維持する必要があるからです。

この仕様で定義されたマークアップを使って生成されたCSSアニメーションは、作成時に global animation list には追加されません。 代わりに、これらのアニメーションが idle play state から離れた最初の瞬間に global animation list に追加されます（所有要素から切り離された後）。 所有要素 から切り離されてもまだ idle のCSSアニメーションは、 合成順序が定義されません。

注意、 この挙動は、 アニメーションが 所有要素 から切り離されると そのアニメーションが必ず（またはそのまま） idle play state になることに依存しています。

3. キーフレームの組み立て

3.1. キーフレームの宣言: @keyframes 規則

CSS Animations 1 § 3 キーフレーム を参照してください。

3.2. キーフレームの処理

ターゲット（疑似）要素 element の coordinated value list における N 番目の animation-* プロパティによって定義された各アニメーション効果について、 その関連する キーフレーム は以下のように生成されます：

1. デフォルトの設定:

   • default timing function を element 上の computed value の animation-timing-function とする。

   • default composite を element 上の computed value の animation-composition とする。

   • keyframes を空の キーフレームオブジェクトのシーケンスとして初期化する。 各キーフレームは keyframe offset, keyframe timing function, keyframe composite, keyframe values を持つ。

   • animated properties をCSSプロパティ名の空集合として初期化する。

2. 宣言されたキーフレームを収集:

   1. 文書順で最後に現れる @keyframes at-rule を探し、 対応する animation-name の値 name と <keyframes-name> が一致するものとする。

      一致する @keyframes at-rule が存在しない場合 （あるいは name が none の場合）、 この手順を中止する。 この場合、アニメーションは生成されず、 name と一致する既存のアニメーションはキャンセルされる。

   2. 同じ キーフレームブロック を specified な <keyframe-selector> （from は 0%、to は 100% とみなす）ごとにグループ化し、 最後に宣言された animation-timing-function の computed value（宣言がなければ default timing function をデフォルトとする）、 および最後に宣言された animation-composition の computed value（宣言がなければ default composite をデフォルトとする）を取得する。

   3. 各グループごとに、最も早い キーフレームブロック の順で次を行う：

      1. そのグループの全ての 宣言ブロック を カスケードし、 各CSSプロパティ（「アニメーション不可」は除外）について 全ての キーフレームブロック の中で最後に宣言されたものが優先される。 [CSS-CASCADE-4]

         注意： カスケードは ショートハンドプロパティを サブプロパティに展開し、 各 論理プロパティグループにおける対応するプロパティ群を element の computed な 書字モードに従ってマッピングする。

      2. このカスケードの結果得られた 宣言値のセットを keyframe values として持つ空の キーフレーム keyframe を keyframes に追加する。 その keyframe offset, keyframe timing function, keyframe composite を設定する。

      3. keyframe properties に追加されたプロパティ名を animated properties に追加する。

3. 初期フレーム・最終フレームの生成:

   1. initial keyframe を探すか新しく作成する。 keyframe offset は 0%、 keyframe timing function は default timing function、 keyframe composite は default composite とする。

   2. animated properties に含まれるプロパティで、 0% のオフセットのキーフレームや used keyframe order でそれより前に配置されるキーフレームに 含まれていないものについては、 element 上のそのプロパティの computed value を initial keyframe の keyframe values に追加する。

   3. initial keyframe の keyframe values が空でなければ、 keyframes の先頭に initial keyframe を追加する。

   4. final keyframe についても同様に、 オフセットは 100%、 used keyframe order でより後に配置されるキーフレームを考慮し、 keyframes の末尾に追加する。

4. フレームのソート:

   • 指定順序は、 上記の手順で得られた keyframes の順序、 すなわち文書順で重複キーフレームは最も早い位置にまとめられる。

   • 算出順序は、 keyframes のうち <percentage>、from、 to キーワードで指定されたオフセットを持つものを リストの先頭（生成された initial keyframe の後）に移動し、 それらを keyframe offset で安定ソートした順序。 getKeyframes() の返す順序となる。

   • 使用順序は、 keyframes をアニメーション効果のタイムライン上に iteration count 1と仮定して 早い順から遅い順に並べ、 同じオフセットの場合は 算出順序で決定する。 実際のアニメーションフレームの補間および計算に使われる順序。

   この仕様で導入された算出キーフレームのソートに関する要件は、 Web Animations § 5.3.3 Calculating computed keyframes に統合されるべきです。 使用キーフレームに関する要件も Web Animations § 5.3.4 The effect value of a keyframe effect に統合されるべきです。 上記のキーフレーム集合の区別については説明的注記に移動すべきです。

   注意： 算出順序は <percentage> のオフセットでキーフレームをソートしますが、 <timeline-range-name> で指定されたキーフレームは 指定順序（生成された final keyframe 以外の <percentage> キーフレームの後）を保持します。 これらが 使用順序で後に来る場合でも同様です。

4. アニメーションの宣言

CSSアニメーションは、animation-* プロパティを使って キーフレームを要素にバインドすることで定義されます。 これらのリスト値プロパティはすべて ロングハンドであり、 animation の ショートハンドです。 coordinating list property group を形成し、 animation-name が coordinating list base property となり、 coordinated value list の各項目が 1つのアニメーション効果のプロパティ群を定義します。

各 animation-* プロパティ値の連携方法については CSS Values 4 § A Coordinating List-Valued Properties を参照してください。

4.1. animation-duration プロパティ

animation-duration プロパティは アニメーションの関連付けられた 反復時間 を指定します。

auto

時間駆動型アニメーションの場合、 0s と同等です。

スクロール駆動型アニメーションの場合、 タイムラインを埋めるのに必要な時間と同等です。 animation-range、 animation-delay、 animation-iteration-count を考慮する。 Scroll-driven Animations § 4.1 有限タイムライン計算 を参照。

<time [0s,∞]>

時間駆動型アニメーションの場合、 アニメーションが1サイクル完了するまでの時間を指定します。 負の <time> は無効です。

<time> が 0s（初期値など）の場合、 アニメーションのキーフレームは効果を持ちませんが、 アニメーション自体は即座に発生します。 具体的には、開始イベントと終了イベントが発火します。 animation-fill-mode が backwards または both の場合、 アニメーションの最初のフレーム（animation-direction により定義される）が animation-delay 中に表示されます。 animation-delay の後は、 アニメーションの最後のフレーム（animation-direction で定義）が animation-fill-mode が forwards または both の場合に表示されます。 animation-fill-mode が none の場合は アニメーションは目に見える効果を持ちません。

スクロール駆動型アニメーションの場合は auto として扱われます。

4.2. animation-timing-function プロパティ

animation-timing-function は、イージング関数（タイミング関数）を各 キーフレーム に適用するために使用されます。詳しくは § 3 キーフレームの組み立て を参照してください。

4.3. animation-iteration-count プロパティ

animation-iteration-count プロパティは、アニメーションの 反復回数を指定します（関連付けられた アニメーション効果）。

4.4. animation-direction プロパティ

animation-direction プロパティは、アニメーションの 再生方向（playback direction）を指定します（関連付けられた アニメーション効果）。

4.5. animation-play-state プロパティ

animation-play-state は、アニメーションを一時停止または再生するために使用されます。

アニメーションが生成された時点を含め、いつでも、 そのアニメーションに対応する animation-play-state の解決値が新たに running になった場合、 実装は アニメーションの再生手順を auto-rewind flag を false に設定して実行しなければなりません。

アニメーションが生成された時点を含め、いつでも、 そのアニメーションに対応する animation-play-state の解決値が新たに paused になった場合、 実装は アニメーションの一時停止手順を 該当アニメーションに対して実行しなければなりません。

上記の要件は、Web Animations API によってアニメーションの再生状態がオーバーライドされている場合（§ 2 アニメーション参照）には適用されません。

4.6. animation-delay プロパティ

animation-delay プロパティは、アニメーションの 開始遅延（start delay）を指定します（関連付けられた アニメーション効果）。

4.7. animation-fill-mode プロパティ

animation-fill-mode プロパティは、アニメーションの フィルモード（fill mode）を指定します（関連付けられた アニメーション効果）。

4.8. animation-composition プロパティ

animation-composition プロパティは、複数のアニメーションが同じプロパティに同時に影響を与える場合に使用される 合成操作（composite operation）を定義します。

<single-animation-composition> = replace | add | accumulate

animation-composition の値は、Web Animations で定義されている composite operation の該当値の意味を持ちます。 詳しくは [WEB-ANIMATIONS] を参照してください。

キーフレーム内で指定した場合、animation-composition は、 そのキーフレームで指定された各プロパティについて 次のキーフレームでそのプロパティが指定されるまで使用される合成操作を定義します。

@keyframes heartbeat {
  from {
    scale: 1;
    animation-timing-function: ease-out;
  }
  30% {
    scale: 1.3;
  }
}
.heartbeat {
  animation: heartbeat 0.3s 2s infinite;
}

@keyframes throb {
  50% {
    scale: 1.8;
  }
}
.icon:mouseover {
  animation: throb 0.4s add;
}

.icon {
  filter: blur(20px);
  transition: filter 0.5s;
}
.icon:hover {
  filter: blur(0px);
  animation: brightness-pulse 3s infinite add;
}

@keyframes brightness-pulse {
  0% {
    scale: 1.1;
    filter: brightness(130%);
  }
  10% {
    scale: 1;
    filter: brightness(100%);
  }
}

4.9. animation-timeline プロパティ

animation-timeline プロパティは、アニメーションで使用される タイムライン を定義します。

注: この仕様ではアニメーションタイムラインを指定する構文は導入されていません。タイムラインの指定は Scroll-linked Animations [SCROLL-ANIMATIONS] など他の仕様によって行われます。

<single-animation-timeline> = auto | none | <custom-ident> | <scroll()> | <view()>

animation-timeline プロパティは animation-name や animation-duration のように、複数の値を持つことができ、それぞれが要素上の対応する アニメーションに追加の挙動を与えます。タイムラインとアニメーションの対応はこちらで説明されています。

各値は型 <single-animation-timeline> であり、次のような効果があります:

auto

アニメーションの タイムラインは DocumentTimeline、つまり デフォルト文書タイムライン になります。

none

アニメーションは タイムライン に関連付けられません。

<custom-ident>

この要素でスコープ内に名前付き スクロール進捗タイムライン または ビュープログレスタイムライン があれば、Scroll-driven Animations § 4.2 名前付きタイムラインのスコープおよび検索 に従い参照されたタイムラインを使用します。

それ以外の場合、アニメーションは タイムライン に関連付けられません。

<scroll()>

指定した scroll() 関数により示される スクロール進捗タイムライン を使用します。 詳細は Scroll-driven Animations § 2.2.1 scroll() 記法 を参照。

<view()>

指定した view() 関数により示される ビュープログレスタイムライン を使用します。 詳細は Scroll-driven Animations § 3.3.1 view() 記法 を参照。

animation-name でタイムラインを選択しやすくするべき。animation-timeline が指定されていない場合に animation-name をタイムライン選択に利用できれば、よくあるアニメーションはキー名を1つ使うだけでタイムライン・キーフレーム両方を指定でき、シンプルかつ使いやすくなります。animation-timeline プロパティは必要に応じてキーフレームとタイムラインを個別に指定できる追加制御を提供します。

複数の animation-* プロパティが同時に設定された場合、animation-timeline が最初に更新されます。つまり例えば animation-play-state の変更は、同時に適用された animation-timeline に対して適用されます。

4.10. animation ショートハンドプロパティ

animation ショートハンドプロパティの構文は以下の通りです：

<single-animation> = <'animation-duration'> || <easing-function> || <'animation-delay'> || <single-animation-iteration-count> || <single-animation-direction> || <single-animation-fill-mode> || <single-animation-play-state> || [ none | <keyframes-name> ] || <single-animation-timeline>

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

5.1. イベントの発行

注: これはCSS Animations Level 1 [CSS3-ANIMATIONS] よりも一般的なイベント発行の説明であり、Web Animations API [WEB-ANIMATIONS] を用いたアニメーションのシークや逆再生の可能性も考慮しています。

CSSアニメーションイベントの target は、アニメーションの所有要素です。 所有要素 がない場合、CSSアニメーションイベントは発行されません （ただしWeb Animationsで定義されている アニメーション再生イベントは対応する CSSAnimation オブジェクトで発行されます）。

どのイベントを発行するか判定するために、Web Animationsモデルで定義されている フェーズを使用します。これらの定義は アニメーション効果に適用されますが、イベント発行の目的ではCSSアニメーションは関連付けられた 効果と同じフェーズとみなします。 例えば、CSSアニメーションの before phase は、その 関連効果が before phase である場合です。

関連付けられた 効果 を持たないCSSアニメーションは、idle phase（current time が unresolved の場合）、 before phase（current time が0未満の場合）、それ以外は after phase とみなされます。

同様に、CSSアニメーションの start delay、active duration、current iteration、iteration start、iteration duration への参照は、アニメーションの関連効果の対応するプロパティを指します。

各イベントの elapsedTime の計算には、以下の定義を使用します：

• interval start = max(min(-start delay, active duration), 0)

• interval end = max(min(associated effect end - start delay, active duration), 0)

新しい アニメーションフレーム が確立され、アニメーションが pending play task や pending pause task を持たない場合、 発行するイベントは新しい アニメーションフレーム の確立前後のフェーズを比較して決定します：

٭ 状態変化で複数イベントが列挙されている場合、記載順に連続してすべてのイベントが発行されます。

† animationiteration イベントの経過時間は以下のように定義されます：

1. previous current iteration を前のアニメーションフレームの current iteration とする。

2. previous current iteration が current iteration より大きければ iteration boundary を current iteration + 1 とし、それ以外は current iteration とする。

3. 経過時間は、 (iteration boundary - iteration start) × iteration duration) の評価結果です。

上記の表や手順で定義された 経過時間 はミリ秒単位なので、 elapsedTime メンバーに割り当てる前に AnimationEvent の秒単位値にするため、1,000で割る必要があります。

6. DOMインターフェース

6.1. CSSAnimationインターフェース

[Exposed=Window]
interface CSSAnimation : Animation {
  readonly attribute CSSOMString animationName;
};

animationName, 型 CSSOMString, 読み取り専用

アニメーション作成時点で関連効果（associated effect）を定義する一致するキーフレーム規則を検索するためのキーです。 この値は、このオブジェクトを生成した animation-name プロパティの値です。

6.2. 保留中のスタイル変更への要件

様々な操作により、要素のプロパティの算出値が影響を受けることがあります。ユーザーエージェントは最適化のため、必要になるまでこれらの値の再計算を遅延させる場合があります。 しかし、この仕様で定義されたプログラミングインターフェースに含まれる全ての操作、そしてWeb Animations [WEB-ANIMATIONS]で定義された、オブジェクトやアニメーション状態を返す可能性のある操作は、保留中の算出値への変更が完全に処理された結果と一貫性のある結果を生成しなければなりません。

elem.style.animation = 'fadeOut 1s';
elem.getAnimations()[0].pause();

elem.style.animation = 'fadeOut 1s paused';
const anim = elem.getAnimations()[0];
elem.style.animationPlayState = 'running';
console.log(anim.playState); // 'running' であるべき。

7. プライバシーに関する考慮事項

本仕様について報告されたプライバシー上の懸念はありません。

8. セキュリティに関する考慮事項

本仕様について報告されたセキュリティ上の懸念はありません。

9. 変更点

9.1. 最近の変更

2023年3月2日付 作業草案 以降の変更点は以下の通りです:

• auto を 初期値として animation-duration に追加 (Issue 6530)
• § 3.2 キーフレームの処理 をカスケードの再利用、パーセンテージ以外のキーフレームオフセットへの対応、[0,1]範囲外のキーフレームオフセットへの対応、animation-composition の値をデフォルトcompositとして使用するように書き直し
• display: none によるアニメーションキャンセルのケースを削減 (Issue 6429)
• CSS Values 4 § A Coordinating List-Valued Properties へリンクし、各 animation-* プロパティの連携方法を定義
• アニメーションプロパティのうち animation-timeline が最初に適用されることを明確化

9.2. CSS Animations, Level 1 からの変更点

• CSS Animations と Web Animations の相互作用を定義し、所有要素・アニメーション合成順序の概念を導入
• キーフレームオブジェクトの生成方法を詳細に記述
• animation-composition プロパティを導入し、複数のアニメーションが同じプロパティに同時に影響を与える場合の合成操作を定義
• animation-timeline プロパティを導入し、アニメーションで使用されるタイムラインを定義
• animation ショートハンドプロパティをこれら新しいプロパティに対応するよう更新
• アニメーションイベントの発行方法を記述
• CSSAnimation インターフェースを追加
• 保留中のスタイル変更への要件を記述