Webアニメーションの最適化
基本ルール
実際のページを編集前に測定すること。目的は動作を削除することではなく、オフスクリーンでの動作を停止させ、表示されている状態では正しく再開させ、ルート/アンマウント時にクリーンアップが行われて長期リソースが解放されるようにすることです。
可能な場合はCodex Browserを使用してください。特にlocalhostページでは推奨します。ユーザーが明示的に要求した場合を除き、Chromeは使用しないでください。
ワークフロー
-
リポジトリのコンテキストを調査する。
AGENTS.mdまたはローカルの指示を読む。- 早期に
git status --shortを実行する。 - ページコンポーネント、アニメーションフック、CSSキーフレーム、
requestAnimationFrame、setInterval、setTimeout、canvas/WebGL/physicsコンポーネント、メディア要素、GSAPタイムライン/トゥイーン、既存の可視性ユーティリティを特定する。 - エフェクトのクリーンアップで、イベントリスナー、オブザーバー、RAFループ、インターバル、タイマー、外部スクリプト、メディアストリーム、WebGLテクスチャ/マテリアル/ジオメトリ/レンダラー、およびアンマウント後に完了する可能性のある非同期処理を検索する。
- ワークツリーがダーティな場合、最初から狭いステージングを計画する。
-
ブラウザでベースラインを取得する。
- ユーザーが指定した正確なルートを開く。
- ページ上部、中間、フッター/下部コンテンツ、およびレイアウトが異なる可能性がある1つのモバイルビューポートでプロファイルを取得する。
- 計算された
animationName、animationPlayState、および可視性によりCSSアニメーションをカウントする。::beforeと::afterを含める。 - canvas/WebGL要素は個別に検査する。CSSプロファイリングだけではRAFループが停止したことを証明できない。
- オフスクリーンで実行されているアニメーション名と、その原因となっているDOM所有者を記録する。
- メモリ/リークの要求の場合、要素/キャンバス/画像/iframeのカウント、利用可能な場合の露出したJSヒープメトリクス、10〜30秒後のアイドルサンプル、および短いルートサイクルサンプルも記録する。ヒープAPIが
nullを返すか、Browserサンドボックスがモンキーパッチをブロックする場合は、その旨を明記し、安定した観測可能なカウントとソース監査に依存する。 - ストレステストは制限された範囲に留める。プロファイリング中のブラウザタブのクラッシュは過負荷の証拠であるが、最小限のテストで再現されない限り、原因を過大に帰属しない。
- 再利用可能なCodex Browser評価ツールについては
references/browser-profiling.mdを参照。
-
動作を制御する最小の所有者にパッチを適用する。
- アプリに既存のページリビール/可視性フックがある場合は、それを優先する。
- それ以外の場合は、セクションとアニメーションする子要素に
is-offscreenのような安定したクラスをトグルするIntersectionObserverを追加する。 - CSSアニメーションを対象としたルールで一時停止する:
main > section.is-offscreen .expensive-animation,
.expensive-animation.is-offscreen {
animation-play-state: paused !important;
}
- 繰り返しカードやプレースホルダーの場合、ドキュメント全体ではなく、カードシェルとアニメーションする子孫を監視する。
- マーキー/ティッカートラックの場合、そのセクションがオフスクリーンのときにトラックを一時停止する。
- スケルトンローダーや疑似要素グリマーの場合、必要に応じて
::beforeと::afterの一時停止セレクターを含める。 - canvas/WebGL/physicsループの場合、RAFループを直接ゲートする:
- キャンバス/コンテナが交差したときに開始する。
- オフスクリーン時に
requestAnimationFrameをキャンセルする。 - 再入場時に再開する。
- クリーンアップ時にオブザーバーを切断し、フレームをキャンセルする。
- ブラウザ検証に役立つ場合、
data-animation-activeのような非視覚的デバッグマーカーを追加する。
- コンポーネントがすでに
prefers-reduced-motionを尊重している場合はそれに従い、スクロール/アニメーション状態のためのReactレンダーループの導入を避ける。 - リーク対策:
- エフェクトによって作成されたすべてのタイムアウト/インターバルをクリアする。
- アンマウント前およびループ再開前にRAFをキャンセルする。
IntersectionObserver、ResizeObserver、MutationObserver、およびカスタムサブスクリプションを切断する。- 同じハンドラ参照を持つグローバル/ウィンドウ/ドキュメントのリスナーを削除する。
- Three/WebGLのテクスチャ、マテリアル、ジオメトリ、レンダラーを破棄し、レンダラーDOMノードを削除する。
- DOMノードおよびシェーダーユニフォームなどの可変オブジェクトに対するGSAPトゥイーン/タイムラインを強制終了する。
- メディアストリームを停止し、切り離されたビデオ/オーディオソースを一時停止する。
- 非同期ローダーを
isDisposedフラグで保護し、アンマウント後に解決した場合にロードされたリソースを破棄する。 - Reactのクリーンアップでは、lintがrefが変更される可能性があると警告する場合、returnする前にエフェクト内で
ref.currentの値をキャプチャする。 - 可視性ポーズ後の物理またはシミュレーションフレームデルタを制限し、遅延フレームが過大な更新を実行しないようにする。
-
ビルドだけでなく、動作を検証する。
- ルートをリロードし、同じ上部/中間/フッター/モバイルプロファイルを再実行する。
- 目標結果:テスト中のページセクションで
offscreenRunningCount: 0。 - 表示されているアニメーションが引き続き実行されるか、スクロールして表示されたときに再開されることを確認する。
- RAF/キャンバスループがオフスクリーンで非アクティブ、ビュー内でアクティブであること、またはソース/ランタイム状態からキャンセルが証明されていることを確認する。
- リーク監査の場合、前後のルートサイクルとアイドルサンプルを比較する。DOM/キャンバス/画像のカウントは、繰り返しナビゲーション後に同じベースラインに戻る必要があります。わずかな非同期コンテンツ変更は許容されます。
- 検索/フィルター/ナビゲーションなどの通常のページインタラクションを実行し、オブザーバーが動的コンテンツを壊さないことを確認する。
- 新しいタブのコンソール警告/エラーを確認する。
-
ローカルチェックを実行する。
- リポジトリの通常のゲートを使用する。React/Viteアプリの場合、多くの場合これで十分です:
git diff --check
npm run lint
npm run build
- 既知の致命的でない警告は、失敗とは別に言及する。
- リポジトリまたはユーザーの指示に従って、狭い範囲でコミットする。
- 無関係なダーティ変更が存在する場合、分離されたインデックスを使用する:
rm -f /tmp/<task>-index
GIT_INDEX_FILE=/tmp/<task>-index git read-tree HEAD
# 意図したハンクのみを一時インデックスに適用する。
GIT_INDEX_FILE=/tmp/<task>-index git diff --cached --check
GIT_INDEX_FILE=/tmp/<task>-index git commit -m "オフスクリーン <page> アニメーションを一時停止"
git restore --staged <files> 2>/dev/null || true
- ダーティワークツリーから広範なファイルをステージングしてはならない。すべてのハンクがタスクに属する場合を除く。
- 証拠をもって報告する。
- 発見事項を先頭に:まだ実行されていたもの、リークの可能性があるもの、測定できなかったもの。
- ソース監査のリスクとライブブラウザ測定を分離する。
- サンプリングされた正確なルート、オフスクリーンアニメーションカウント、DOM/キャンバスカウントの安定性、ルートサイクル結果、およびローカルチェックを含める。
- 特に利用できないヒープカウンターやブロックされたブラウザ計測については、制限を明確に述べる。
良い修正パターン
- 長いセクションで、ビューポート外の子アニメーションがまだ実行される可能性がある場合、セクションレベルの
is-offscreenと要素レベルのis-offscreenを併用する。 - ルートごとに共有される可視性セレクター定数。例:
COURSES_PAGE_ANIMATION_VISIBILITY_SELECTOR。 - アニメーションゲーティング用の
IntersectionObserverしきい値0.01程度。 - WebGL/キャンバスエフェクト用の直接RAFループ制御。CSS
animation-play-stateではJavaScriptレンダーループを一時停止できない。 - 一時停止または遅延フレーム後に再開する物理ループ用のフレームデルタ制限。
- GSAP/WebGLエフェクトで使用されるReact ref用のキャプチャされたクリーンアップノード。
- アンマウント後に解決する可能性がある画像/ビデオ/テクスチャ/データローダー用の
isDisposedガード。 - 蓄積するDOMノード、キャンバス、iframe、または未解放メディアをキャッチするための短いアイドルおよびルートサイクルプローブ。
避けるべきこと
- プロファイルを通過させるためにすべてのアニメーションを削除すること。
- 祖先セレクターが広すぎるために、表示されているヒーロー動作を一時停止すること。
animation-play-stateが疑似要素やJavaScript RAFループをカバーすると想定すること。- 長いページで単一のページ上部測定を信頼すること。
- 利用できないヒープカウンターをメモリリークがない証拠として扱うこと。
- ブラウザで無制限のストレスループを実行すること。制限されたサイクルを使用し、クラッシュを記録するが、因果関係を過大に述べないこと。
- パフォーマンスの証拠としてスクリーンショットのみを使用すること。
- コミットに無関係なローカルハンクを混在させること。