CSS 动画下的焦点管理
本文档记录了在浮动组件(Select、DropdownMenu、Popover)具有 CSS 开闭动画时,修复键盘导航问题所积累的经验。
问题
当浮动内容元素的 CSS 动画从 opacity: 0 开始(例如 Tailwind 的 animate-in fade-in-0),浏览器可能会拒绝 element.focus() 调用,因为元素此时不可见。
症状
- 使用鼠标点击可以正常打开组件
- 使用键盘打开组件后,键盘导航(方向键、Escape)失效
- 没有动画类别的演示中工作正常
- 有动画类别的演示中出现故障
根本原因
- 诸如
fade-in-0的 CSS 动画使元素从opacity: 0开始 - 在渲染后立即调用
focus()时,元素仍然不可见 - 浏览器拒绝将焦点置于不可见元素上
- 焦点停留在触发按钮上,而未移动到内容区
- 键盘事件被发送给了触发按钮(打开后不做任何操作),而非内容区
控制台调试证据
// 打开 select 后,键盘事件被发送给触发按钮,而非内容区:
Document keydown: ArrowDown Target: <button role="combobox" ...>
// 活动元素是触发按钮,不是内容区:
Active: BUTTON summit-select-...-trigger
解决方案
实现一个焦点重试机制,允许动画在放弃之前越过 opacity: 0 状态。
JavaScript 实现
// src/SummitUI/Scripts/floating.js
/**
* 为动画元素实现带重试机制的焦点设置。
* CSS 动画从 opacity:0 开始的元素最初可能拒绝焦点设置。
* 此函数最多重试 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 组件中处理动画存在性的方式。关键洞察在于,DOM 操作(如焦点设置)可能需要等待 CSS 动画达到可聚焦状态后才可执行。