Alpine.js模态框步骤间屏幕阅读器焦点管理异常排查

问题 #

在基于TALL（+Filament）栈的应用中，我用Alpine.js结合Filament UI组件实现了多步骤模态对话框。视觉焦点能在步骤间正常切换，但屏幕阅读器无法正确播报新步骤内容：点击「Next」按钮后，浏览器视觉焦点（橙色边框）显示在新步骤标题上，可屏幕阅读器先播报“Chrome无响应”后中断，仅提示“group”，且实际焦点落在「Back」按钮而非标题上。

已尝试的方案：

• 使用$nextTick()在切换页面后聚焦对应步骤标题
• 为标题添加tabindex="-1"使其可聚焦
• 为步骤容器设置role="region"、aria-labelledby关联标题、x-cloak隐藏未激活步骤

环境信息：屏幕阅读器为VoiceOver/JAWS（当前使用Mac VoiceOver）、浏览器为最新版Chrome、Alpine.js v3.x、Filament UI组件

请问如何确保Alpine.js模态框切换步骤时，屏幕阅读器能正确聚焦并播报新步骤标题？我的ARIA实现或焦点管理方式是否存在遗漏？

解决方案 #

1. 修正焦点触发时机与优先级 #

Filament模态框内置的焦点管理逻辑可能会覆盖手动聚焦操作，建议在步骤切换完成后，先阻断默认焦点重置再执行聚焦：

// Next按钮的点击处理逻辑
$wire.nextStep().then(() => {
  $nextTick(() => {
    // 移除模态框的自动聚焦属性
    document.querySelector('.filament-modal').removeAttribute('autofocus');
    // 精准聚焦当前步骤标题
    const targetTitle = document.getElementById(`step-${currentStep}-title`);
    if (targetTitle) targetTitle.focus();
  });
});

2. 强化ARIA语义与实时播报 #

• 给每个步骤容器添加aria-live="polite"，让屏幕阅读器主动感知内容变化并播报：

<div 
  x-show="currentStep === 1" 
  role="region" 
  aria-labelledby="step-1-title"
  aria-live="polite"
  x-cloak
>
  <h2 id="step-1-title" tabindex="-1">步骤1：基本信息</h2>
  <!-- 步骤内容 -->
</div>

• 给未激活步骤添加aria-hidden="true"，避免屏幕阅读器读取隐藏内容：

<div 
  x-show="currentStep === 2" 
  role="region" 
  aria-labelledby="step-2-title"
  aria-live="polite"
  x-cloak
  :aria-hidden="currentStep !== 2"
>
  <h2 id="step-2-title" tabindex="-1">步骤2：详细设置</h2>
  <!-- 步骤内容 -->
</div>

3. 优化标题元素的可访问性标识 #

给步骤标题明确声明角色与层级，确保屏幕阅读器识别为标题类型：

<h2 
  id="step-1-title" 
  tabindex="-1"
  role="heading"
  aria-level="2"
>步骤1：基本信息</h2>

4. 调整Filament焦点陷阱规则 #

Filament模态框的焦点陷阱会强制焦点在交互元素循环，可自定义规则将步骤标题纳入允许聚焦范围：

// Alpine组件的init钩子中
init() {
  const modalTrap = document.querySelector('.filament-modal')._x_trap;
  if (modalTrap) {
    modalTrap.options.allowedElements = (el) => {
      // 允许按钮和带tabindex="-1"的标题元素获取焦点
      return el.tagName === 'BUTTON' || (el.hasAttribute('tabindex') && el.getAttribute('tabindex') === '-1');
    };
  }
}

5. 强制触发屏幕阅读器播报 #

如果焦点到位但仍不播报，可通过临时修改aria-label强制触发：

const targetTitle = document.getElementById(`step-${currentStep}-title`);
targetTitle.focus();
// 临时添加标签触发播报
targetTitle.setAttribute('aria-label', `当前步骤：${targetTitle.textContent.trim()}`);
// 立即移除避免干扰后续操作
setTimeout(() => targetTitle.removeAttribute('aria-label'), 100);

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