ARIA地标未包含文本无障碍错误排查及修复方案咨询

问题描述 #

我有一个打开日历模态框的按钮，虽然知道日历组件无障碍表现不佳，但客户坚持要用。打开按钮代码如下：

<div class="col-sm-6 hidden-xs text-right calendar-cta">
     <a type="button" onclick="openNav()" href="#" class="btn-primary">Calendar view</a>
</div>

模态框的关闭按钮触发了无障碍错误：Text not included in an ARIA landmark，模态框代码如下：

<div id="myNav" class="overlay" role="menu">
<a class="closebtn" tabindex="-1" role="menuitem" aria-label="close calendar view">×</a>
<div class="overlay-content">  </div>
</div>

错误原因分析 #

这个错误的核心是关闭按钮未被包含在符合无障碍标准的ARIA地标区域内，同时模态框的角色定义存在错误：

1. 给模态框设置role="menu"是误用——menu角色专为导航菜单设计，而模态弹窗应该使用role="dialog"，这能让无障碍工具正确识别弹窗类型，自动关联内部元素的上下文。
2. 关闭按钮的tabindex="-1"会让键盘用户无法聚焦到该按钮，完全丧失可访问性，也会导致无障碍工具无法识别它的归属区域。

修复步骤 #

1. 修正模态框的角色与属性 #

将模态框的role="menu"替换为role="dialog"，同时添加aria-modal="true"明确这是模态弹窗，可搭配aria-label或aria-labelledby增强上下文识别：

<!-- 无标题时用aria-label -->
<div id="myNav" class="overlay" role="dialog" aria-modal="true" aria-label="Calendar view modal">

如果模态框有标题元素（比如隐藏的屏幕阅读器专用标题），可以用aria-labelledby关联：

<div id="myNav" class="overlay" role="dialog" aria-modal="true" aria-labelledby="calendar-modal-title">
  <h2 id="calendar-modal-title" class="sr-only">Calendar View</h2>

2. 调整关闭按钮的可访问性设置 #

• 移除tabindex="-1"，确保键盘用户能聚焦到按钮（链接元素默认支持键盘聚焦，无需额外设置）
• 保留aria-label="close calendar view"，保证屏幕阅读器能读取按钮功能
• 移除role="menuitem"，因为模态框已是dialog角色，内部按钮不需要菜单项角色：

<a class="closebtn" aria-label="close calendar view" onclick="closeNav()">×</a>

3. 完整修复后的模态框代码 #

<div id="myNav" class="overlay" role="dialog" aria-modal="true" aria-label="Calendar view modal">
  <!-- 可选：屏幕阅读器专用标题 -->
  <!-- <h2 id="calendar-modal-title" class="sr-only">Calendar View</h2> -->
  <a class="closebtn" aria-label="close calendar view" onclick="closeNav()">×</a>
  <div class="overlay-content">
    <!-- 日历内容 -->
  </div>
</div>

额外无障碍优化建议 #

• 打开模态框时，自动将焦点聚焦到关闭按钮（或日历的第一个可交互元素），确保键盘用户能直接操作
• 关闭模态框时，将焦点返回到触发打开的“Calendar view”按钮
• 添加键盘事件支持：按下ESC键可关闭模态框

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