焦点陷阱测试工具 - 检测模态框是否困住 Tab

焦点陷阱（Focus Trap）是一种键盘导航管理技术，用于将用户的键盘焦点限制在页面上某个特定的交互区域内。当用户打开一个模态框或对话框时，焦点陷阱确保 Tab 键只能在该组件的可聚焦元素之间循环，而不会导航到被遮罩层覆盖的背景内容上。在无障碍设计中，焦点陷阱扮演着至关重要的角色，因为它确保了屏幕阅读器用户和纯键盘导航用户在与弹出组件交互时能够保持清晰的空间感知。如果没有焦点陷阱，用户可能会在按下 Tab 键后发现焦点跳到了看不见的背景区域，导致屏幕阅读器朗读无关内容，用户无法理解当前的交互状态。正确实现的焦点陷阱通过限制焦点范围，帮助用户集中注意力在当前任务上，同时通过提供 Escape 键关闭功能，确保用户始终能够退出当前交互。

模态框需要焦点陷阱的核心原因是确保键盘和屏幕阅读器用户能够正确地与模态框内容交互，而不会被背景内容干扰。当模态框打开时，背景内容通常被半透明遮罩层覆盖，从视觉上不可交互。但是，如果没有焦点陷阱，这些背景元素在 DOM 中仍然是可聚焦的，用户按下 Tab 键时焦点会移动到这些不可见的背景元素上。对于屏幕阅读器用户来说，这意味着屏幕阅读器会开始朗读背景内容，与模态框的内容混在一起，造成严重的理解障碍。不添加焦点陷阱的后果包括：用户可能无法通过键盘关闭模态框（如果关闭按钮的焦点被背景元素截获）、屏幕阅读器用户在模态框和背景内容之间反复跳转导致迷失方向、以及用户体验的严重下降。在无障碍审计中，模态框缺少焦点陷阱是最常见的无障碍问题之一，可能导致网站不符合 WCAG 标准，面临法律和合规风险。

WCAG（Web 内容无障碍指南）对焦点管理有多个相关要求。首先是准则 2.1.1 键盘（Keyboard），要求所有功能必须可通过键盘访问，这包括模态框内的所有交互元素。其次是准则 2.1.2 无键盘陷阱（No Keyboard Trap），这是与焦点陷阱最直接相关的准则，它要求如果通过键盘可以将焦点移动到页面的某个部分，那么也必须能够仅通过键盘将焦点从该部分移出。这意味着焦点陷阱必须有明确的退出机制（如 Escape 键或关闭按钮）。准则 2.4.3 焦点顺序（Focus Order）要求焦点的移动顺序必须保持可理解和可预测的逻辑顺序。准则 2.4.7 焦点可见（Focus Visible）要求焦点指示器在视觉上是可见的。在实际实现中，模态框的焦点陷阱需要满足以下条件：所有可聚焦元素都包含在陷阱区域内、用户可以通过 Escape 键关闭模态框、焦点在模态框关闭后能够恢复到触发元素、焦点顺序与视觉布局保持逻辑一致。

正确实现焦点陷阱需要遵循以下几个关键步骤和最佳实践。首先，在模态框打开时，收集所有可聚焦元素的引用并建立元素列表。可聚焦元素包括按钮、链接、输入框、选择框等交互元素，可以通过 querySelectorAll 方法结合适当的 CSS 选择器来获取。其次，监听模态框区域内的 keydown 事件，当检测到 Tab 键按下时，判断下一个焦点目标是否在陷阱区域内。如果不在，需要阻止默认行为并手动将焦点移动到区域内的第一个或最后一个元素。对于 Shift+Tab 组合键，焦点应该移动到最后一个元素；对于普通 Tab 键，焦点应该移动到第一个元素。最佳实践还包括：在模态框打开时将焦点移动到模态框的第一个可聚焦元素上、在模态框关闭时将焦点恢复到触发元素、确保 Escape 键能够关闭模态框、为焦点陷阱区域设置适当的 aria-modal 属性、以及使用 role="dialog" 和 aria-labelledby 描述模态框的语义。建议使用成熟的无障碍组件库（如 React Aria、Headless UI）来实现焦点陷阱，这些库已经处理了各种边界情况和浏览器兼容性问题。

焦点陷阱对屏幕阅读器用户的重要性体现在多个关键方面。首先，屏幕阅读器依赖键盘焦点来确定应该朗读的内容。当焦点移动到模态框外部时，屏幕阅读器会开始朗读背景内容，这会与模态框的内容混杂在一起，使用户完全无法理解当前的交互上下文。焦点陷阱通过将焦点限制在模态框内部，确保屏幕阅读器始终朗读与当前任务相关的内容。其次，屏幕阅读器用户无法看到模态框的视觉边界，他们完全依赖焦点的位置来感知交互区域的范围。焦点陷阱帮助屏幕阅读器用户建立正确的空间心智模型，理解哪些内容是可以访问的，哪些内容被暂时屏蔽。第三，焦点陷阱与 ARIA 属性（如 aria-modal="true"）配合使用，能够向屏幕阅读器明确传达模态框的交互状态，使屏幕阅读器能够在模态框打开时忽略背景内容的更新。最后，正确的焦点陷阱确保屏幕阅读器用户能够完整地访问模态框内的所有功能，包括填写表单、选择选项和提交操作，而不会因为焦点的意外移动而中断操作流程。对于依赖屏幕阅读器的用户来说，焦点陷阱不是可选的增强功能，而是确保基本可用性的必要条件。

常见的焦点陷阱实现错误包括以下几种。第一种是遗漏可聚焦元素，即模态框内的某些可聚焦元素没有被纳入焦点循环中，导致用户在 Tab 导航时跳过这些元素。避免方法是在每次模态框打开时重新获取所有可聚焦元素的列表，而不是在初始化时硬编码。第二种是 Escape 键未绑定关闭功能，这是违反 WCAG 2.1.2 准则的严重错误。必须确保 Escape 键能够关闭模态框并将焦点恢复到触发元素。第三种是焦点恢复失败，即模态框关闭后焦点没有回到触发按钮或链接上，而是停留在页面的某个不确定位置。这通常是因为在模态框关闭的异步操作中，焦点恢复的时机不正确。第四种是在动态内容场景下焦点陷阱失效，例如模态框打开后异步加载了新的可聚焦元素，但焦点列表没有更新。解决方法是在内容变化后重新计算可聚焦元素列表。第五种是 tabindex 管理不当，过度使用正整数的 tabindex 值导致焦点顺序混乱。应尽量避免使用正整数 tabindex，保持焦点顺序与 DOM 顺序一致。第六种是嵌套焦点陷阱处理不当，当模态框内部包含下拉菜单等需要独立焦点管理的子组件时，焦点陷阱的行为可能不符合预期。建议使用成熟的组件库来处理这些复杂的嵌套场景。定期使用焦点陷阱测试工具进行验证，可以帮助开发者及早发现和修复这些问题。

焦点陷阱测试工具与浏览器开发者工具的焦点追踪功能在功能定位和使用体验上有显著区别。浏览器开发者工具（如 Chrome DevTools 的 Focus Emulation）主要提供基础的焦点状态查看功能，允许开发者手动设置或查看当前获得焦点的元素，但它不会自动记录焦点的变化历史，也不会统计 Tab 按键次数或检测焦点逃逸。开发者需要手动观察和记录焦点的变化，这在测试复杂的焦点陷阱场景时效率较低。焦点陷阱测试工具则专门针对焦点陷阱的测试场景设计，提供了自动化的检测能力。它会实时记录每一次焦点变化，统计 Tab 按键次数和循环完成次数，自动检测焦点逃逸事件，并将所有测试结果以结构化的方式呈现。此外，该工具还提供了焦点陷阱的启用/禁用切换功能，方便开发者进行对比测试。浏览器开发者工具更适合通用的页面调试，而焦点陷阱测试工具更适合系统化的无障碍焦点测试。建议在实际测试中将两者结合使用，先用焦点陷阱测试工具进行整体的行为验证，再用开发者工具深入调试发现的具体问题。

在 React、Vue 等前端框架中实现焦点陷阱，推荐使用成熟的无障碍组件库，而不是从零开始手写实现。React 生态中，推荐使用 React Aria（由 Adobe 维护）或 Headless UI（由 Tailwind Labs 维护）提供的 Dialog 和 Modal 组件，这些组件内置了完善的焦点陷阱管理、焦点恢复和 Escape 键处理。Vue 生态中，可以使用 PrimeVue 的 Dialog 组件或 Headless UI Vue 版本，它们同样提供了无障碍优化的焦点管理。如果需要自定义实现，核心逻辑与原生 JavaScript 类似：在组件挂载时收集可聚焦元素列表，在组件内部监听 Tab 键事件进行焦点限制，在组件卸载时恢复焦点。React 中可以使用 useEffect Hook 来管理焦点陷阱的生命周期，Vue 中可以使用 onMounted 和 onUnmounted 钩子。无论使用哪种框架，都应该确保组件支持 ref 转发（React）或模板引用（Vue），以便外部代码能够访问模态框内部的 DOM 元素。在实现过程中，还需要特别注意动态内容的场景，例如模态框内异步加载的内容可能包含新的可聚焦元素，需要在内容更新后重新计算焦点列表。使用框架的响应式系统（如 React 的 state 或 Vue 的 reactive）可以自动触发焦点列表的更新。

焦点陷阱测试应该嵌入到完整的无障碍测试流程中，作为键盘可访问性测试的重要环节。在开发阶段，前端开发者应在实现焦点陷阱后立即使用焦点陷阱测试工具进行自测，确保基本的焦点行为正确。在代码审查阶段，审查者应将焦点陷阱的实现作为检查点之一，确认所有弹出组件都包含了焦点管理逻辑。在 QA 测试阶段，测试人员应将焦点陷阱测试纳入无障碍测试用例集，对每个模态框和弹出组件进行系统的测试，包括焦点限制、循环行为、Escape 键退出和焦点恢复等场景。在发布前的无障碍审计阶段，审计人员应使用焦点陷阱测试工具生成测试报告，作为合规性证据的一部分。除了手动测试，还应该配合自动化无障碍检测工具（如 axe-core、Lighthouse）来检查更广泛的无障碍问题，但需要注意焦点陷阱的行为测试通常无法完全自动化，因为焦点的移动需要模拟真实的键盘交互。建议建立焦点陷阱测试的标准操作流程（SOP），明确测试步骤、预期结果和问题记录格式，确保测试的一致性和可重复性。

当焦点逃逸检测报错时，需要按照以下步骤进行系统化的排查和修复。首先，确认焦点逃逸发生的具体场景：是在焦点陷阱启用还是禁用状态下发生的？是通过 Tab 键还是 Shift+Tab 触发的？逃逸到了哪个具体的元素上？工具的日志功能会提供这些关键信息。其次，检查焦点陷阱的边界定义是否准确，确认陷阱区域的 DOM 容器是否正确包裹了所有需要限制的可聚焦元素。常见的问题是模态框的 DOM 结构中包含了陷阱区域之外的可聚焦元素（如页面头部的导航链接），这些元素应该被排除在 Tab 导航之外。第三，检查键盘事件处理逻辑是否正确处理了所有边界情况，特别是当焦点位于第一个或最后一个可聚焦元素时的 Tab 和 Shift+Tab 处理。第四，检查是否有动态添加的可聚焦元素没有被纳入陷阱范围，可以通过在元素添加后重新计算焦点列表来解决。第五，检查 CSS 的 z-index 和定位属性是否正确，确保遮罩层不会影响焦点的视觉和逻辑边界。修复后，使用焦点陷阱测试工具重新执行测试，确认焦点逃逸问题已解决，同时验证焦点陷阱的其他功能（循环、Escape 键退出等）未受到修复的影响。