CSS 動畫下的焦點管理
本文件記錄修復浮動元件(Select、DropdownMenu、Popover)在 CSS 開合動畫下鍵盤導航問題的學習心得。
問題
當浮動內容元素使用從 opacity: 0 起始的 CSS 動畫(例如 Tailwind 的 animate-in fade-in-0),瀏覽器可能會因為元素不可見而拒絕 element.focus() 的呼叫。
症狀
- 使用滑鼠點擊時元件正常開啟
- 使用鍵盤開啟後,鍵盤導航(方向鍵、Escape)失效
- 在沒有動畫類別的示範頁面上正常運作
- 在有動畫類別的示範頁面上失效
根本原因
- CSS 動畫(如
fade-in-0)讓元素從opacity: 0開始 - 在渲染後立即呼叫
focus()時,元素仍處於不可見狀態 - 瀏覽器拒絕將焦點放在不可見元素上
- 焦點停留在觸發按鈕,而非移至內容
- 鍵盤事件進入觸發按鈕(開啟時無作用),而非內容
主控台除錯證據
// 開啟 Select 後,鍵盤事件進入觸發按鈕,而非內容:
Document keydown: ArrowDown Target: <button role="combobox" ...>
// 活動元素是觸發按鈕,而非內容:
Active: BUTTON summit-select-...-trigger
解決方案
實作一個針對動畫元素的焦點重試機制,讓動畫在放棄前有機會越過 opacity: 0 狀態。
JavaScript 實作
// src/SummitUI/Scripts/floating.js
/**
* 使用重試機制聚焦於元素,適用於動畫元素。
* 起始於 opacity:0 的 CSS 動畫元素可能會拒絕初始焦點。
* 本函數最多重試 5 次,每次延遲 20ms,讓動畫
* 能夠越過不可見狀態。
* @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 有時間套用
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 | 在動畫存在時以鍵盤開啟 |
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 撰寫方式
- 效能影響極小
- 若聚焦始終不成功,可優雅地失敗
相關模式
此模式類似於 bits-ui 在 Svelte 元件中處理動畫存在(animated presence)的方式。關鍵洞察在於 DOM 操作(如聚焦)可能需要等待 CSS 動畫達到可聚焦狀態後再執行。