CSSアニメーションにおけるフォーカス管理
このドキュメントは、浮動コンポーネント(Select、DropdownMenu、Popover)にCSSの開閉アニメーションがある場合のキーボードナビゲーションの問題を修正した学習内容をまとめたものです。
問題
浮動コンテンツ要素にopacity: 0から始まるCSSアニメーション(Tailwindのanimate-in fade-in-0など)があると、ブラウザが要素を不可視と判断し、element.focus()の呼び出しを拒否する場合があります。
症状
- マウスクリックではコンポーネントが正しく開く
- キーボードで開いた後、キーボードナビゲーション(矢印キー、Escape)が機能しない
- アニメーションクラスがないデモでは正常に動作する
- アニメーションクラスがあるデモでは動作しない
根本原因
fade-in-0のようなCSSアニメーションは要素をopacity: 0から開始する- レンダリング直後に
focus()が呼び出されると、要素はまだ不可視状態 - ブラウザは不可視要素へのフォーカスを拒否する
- フォーカスがトリガーボタンに留まり、コンテンツに移動しない
- キーボードイベントが(開いている状態では何もしない)トリガーに送られ、コンテンツには届かない
コンソールデバッグによる証拠
// セレクトを開いた後、キーボードイベントはコンテンツではなくトリガーに送られる:
Document keydown: ArrowDown Target: <button role="combobox" ...>
// アクティブ要素はコンテンツではなくトリガー:
Active: BUTTON summit-select-...-trigger
解決策
フォーカスが失敗した場合に、アニメーションがopacity: 0の状態を過ぎて進行するのを待つリトライ機構を実装します。
JavaScript実装
// src/SummitUI/Scripts/floating.js
/**
* アニメーション要素向けのリトライ機構付きフォーカス関数。
* opacity:0から始まるCSSアニメーション要素は、初期状態でフォーカスを拒否する場合がある。
* 20ms間隔で最大5回リトライし、アニメーションが不可視状態を過ぎるのを待つ。
* @param {HTMLElement} element - フォーカスする要素
*/
export function focusElement(element) {
if (!element) return;
function tryFocus(attempts) {
element.focus();
// フォーカスが成功せず、リトライ回数が残っている場合、再試行
if (document.activeElement !== element && attempts > 0) {
setTimeout(() => tryFocus(attempts - 1), 20);
}
}
// CSSが適用されるよう、1フレーム後に最初の試行
requestAnimationFrame(() => tryFocus(5));
}
重要なポイント
- 最初に
requestAnimationFrameを使用 - CSSが適用されてからフォーカスを試行することを保証 document.activeElementを確認 - フォーカスが実際に成功したか検証- 遅延付きでリトライ - 20ms間隔でアニメーションの進行を許可
- リトライ回数を制限 - 5回のリトライ = 最大100msの待機、一般的なアニメーションに十分
- すべてのフォーカス関数に適用 -
focusElement(element)とfocusElementById(id)の両方にこのパターンが必要
更新された関数
floating.js:focusElement(element)- SelectContentで使用floating.js:focusElementById(elementId)- DropdownMenuContentで使用
テスト
「アニメーションあり」セクションをテストデモページに追加し、対応するPlaywrightテストも追加しました。
テスト用CSSアニメーションクラス
/* tests/SummitUI.Tests.Manual/SummitUI.Tests.Manual/wwwroot/app.css */
@keyframes fadeInZoomIn {
from {
opacity: 0;
transform: scale(0.95);
}
to {
opacity: 1;
transform: scale(1);
}
}
@keyframes fadeOutZoomOut {
from {
opacity: 1;
transform: scale(1);
}
to {
opacity: 0;
transform: scale(0.95);
}
}
.animated-content[data-state="open"] {
animation: fadeInZoomIn 150ms ease-out forwards;
}
.animated-content[data-state="closed"] {
animation: fadeOutZoomOut 150ms ease-in forwards;
}
テストケース
各コンポーネント(Select、DropdownMenu、Popover)に対して:
| テスト | 検証内容 |
|---|---|
Animated*_ShouldOpen_OnEnterKey | アニメーションありでキーボード(Enter)で開くこと |
Animated*_ShouldNavigate_WithArrowKeys | アニメーションありで開いた後に矢印キーが動作すること |
Animated*_ShouldSelect/Activate_OnEnterKey | アニメーションありで開いた後に項目を選択/実行できること |
Animated*_ShouldClose_OnEscape | Escapeキーで閉じるアニメーションがトリガーされること |
アニメーションテストの実行
dotnet run --project tests/SummitUI.Tests.Playwright -- --treenode-filter '/*/*/*/Animated*'
関連ファイル
| ファイル | 目的 |
|---|---|
src/SummitUI/Scripts/floating.js | focusElementとfocusElementById関数を含む |
src/SummitUI/Components/Select/SelectContent.cs | 開く際にFocusElementAsyncを呼び出す |
src/SummitUI/Components/DropdownMenu/DropdownMenuContent.cs | メニュー項目に対してFocusElementByIdAsyncを呼び出す |
src/SummitUI/Components/Popover/PopoverContent.cs | ポップオーバーコンテンツのフォーカスを管理 |
検討した代替アプローチ
- より長い初期遅延 - 最初のフォーカス試行前に50~100msの遅延を入れる方法。ただし、顕著なラグが生じる。
- アニメーション開始前にフォーカス - レンダリング順序の変更が必要で複雑。
- フォーカス中にアニメーションを無効化 - 視覚的な不具合が生じる。
- CSSの
visibilityをopacityの代わりに使用 - アニメーションの記述方法を変更する必要がある。
リトライ機構を選択した理由:
- あらゆるアニメーション時間に対応
- CSSの記述方法を変更する必要がない
- パフォーマンスへの影響が最小限
- フォーカスが最終的に成功しなくても、グレースフルに失敗する
関連パターン
このパターンは、Svelteコンポーネントにおけるbits-uiのアニメーションプレゼンス処理と似ています。重要な洞察は、DOM操作(フォーカスなど)はCSSアニメーションがフォーカス可能な状態に達するのを待つ必要がある可能性があるということです。