React项目启用屏幕阅读器后键盘Tab聚焦跳转功能失效如何解决

异常原因 #

• 模态属性声明不符合ARIA规范：NVDA会严格校验弹窗的可访问性属性，如果弹窗没有配置role="dialog"、aria-modal="true"属性，NVDA不会将弹窗识别为当前需要交互的独立模态区域，会判定弹窗内元素不属于当前焦点上下文，触发Tab时自动把焦点拉回弹窗出现前的活跃元素。
• 自定义焦点锁定逻辑未适配屏幕阅读器场景：大部分手写或二次封装的React弹窗焦点锁定，仅通过拦截普通浏览模式下的Tab keydown事件实现，而NVDA开启后有独立的浏览模式/焦点模式两套逻辑，会接管系统Tab事件，普通的JS事件拦截规则对其不生效，导致焦点锁定失效。
• 弹窗外内容未做隐藏标记：如果React弹窗通过Portal挂载到body根节点，但未给页面原有根内容（如#root节点）设置aria-hidden="true"，NVDA会同时识别到原有页面和弹窗的所有可聚焦元素，Tab跳转时优先匹配原有页面元素，出现焦点回跳。

修复方案 #

• 补全标准可访问性属性
  给弹窗根节点添加必填ARIA属性：

  role="dialog"
  aria-modal="true"
  aria-labelledby="弹窗标题对应的元素ID"
  

  弹窗开启时给页面所有非弹窗的根容器设置aria-hidden="true"，弹窗关闭时恢复为false，确保NVDA仅识别弹窗内的可交互内容。
• 优先使用经过无障碍验证的组件库
  避免手写焦点锁定逻辑，直接用@radix-ui/react-dialog、@react-aria/dialog等经过NVDA兼容性测试的弹窗组件，内置的焦点管理逻辑已经适配了屏幕阅读器场景。
• 手动适配焦点管理逻辑
  如果必须自行封装弹窗，除了拦截Tab keydown事件外，额外监听focusout事件，当焦点即将移出弹窗范围时，强制将焦点放回弹窗内的第一个可聚焦元素；弹窗打开时主动把焦点落到弹窗内的首个可交互元素（如关闭按钮、确认按钮），弹窗关闭时主动把焦点放回触发弹窗的按钮元素，避免NVDA的焦点上下文丢失。
• 规范可聚焦元素声明
  弹窗内的可交互元素不要省略原生可聚焦属性，自定义交互组件主动添加tabindex="0"声明可聚焦，禁止使用tabindex>0打乱默认焦点排序，避免NVDA识别异常。

内容的提问来源于stack exchange，提问作者Rahul Bhaskar