修复我的工具提示可访问性错误

# 修复我的工具提示无障碍错误 来源：https://jakearchibald.com/2026/my-tooltip-a11y-mistake/ 我犯了一个无障碍错误，希望你能从我的错误中汲取教训。我最近一直在制作关于 Web 平台功能（当它们在 Firefox 中落地时）的短视频，也涉及其他 Web 标准和开发相关内容。如果你更愿意观看这篇文章的 3 分钟视频版本，请选择你的平台，如果你对这类内容感兴趣，也可以关注这个账号： 该账号也在 Bluesky（https://bsky.app/profile/webdevs.firefox.com）上，但视频上传功能在那里已经坏了一段时间了。 否则，这里是文字版本…… ## 我做了什么 我在创建这样一个工具提示时犯了无障碍错误： 一个文本格式工具栏，包含粗体、斜体、下划线等按钮。鼠标指针悬停在粗体按钮上，一个工具提示显示着“粗体（⌘B）”。 那是我关于 `popover="hint"` 的视频的一部分，该视频还涵盖了如何为视觉用户显示工具提示。哦对了，这里是那个视频的链接： 我确实试图把它做对！我与一些比我更懂无障碍的朋友交流，他们向我指出了 Scott O'Hara 的这些演示（https://scottaohara.github.io/a11y_tooltips/）。Scott 很清楚自己在说什么，所以我想我可以直接复制他演示中的模式。 Scott 的演示早于 hint popover 出现，所以这里是他其中一个示例的现代化版本： ```html <button aria-describedby="tooltip">编辑</button> <p role="tooltip" id="tooltip">修改账户设置。</p> ``` 按钮通过 `aria-describedby` 与工具提示连接，因此屏幕阅读器通常会在按钮获得焦点时朗读工具提示。`aria-describedby` 的一个好处是，即使它指向的元素是隐藏的（就像这里的情况），它也能正常工作。 所以，我将 Scott 的代码改编到了我的工具栏演示中： ```html <button aria-label="粗体" aria-describedby="tooltip"> (粗体图标) </button> <p role="tooltip" id="tooltip">粗体（⌘B）</p> ``` 这是一个非常相似的模式，只是我在按钮上加了 `aria-label`，因为它包含的是 SVG 图标而不是文本。和 Scott 一样，我添加了 `aria-describedby` 来将按钮连接到工具提示。 我在 VoiceOver 中测试了一下，它说“粗体。粗体。Command B。按钮。”我觉得这不太对劲——它不需要把“粗体”说两遍。 那之所以发生，是因为与 Scott 的示例（工具提示只包含额外内容）不同，我的工具提示也包含了标签本身。粗体被说了两遍，因为它在那里出现了两次。 所以我移除了 `aria-label`…… ```html <button aria-describedby="tooltip"> (粗体图标) </button> <p role="tooltip" id="tooltip">粗体（⌘B）</p> ``` ……然后 VoiceOver 现在说“可点击图像。粗体。Command B。按钮。”我想，这样就够了！我发布了视频，然后去了酒吧。 ## 我哪里做错了 我收到了来自无障碍机构 TetraLogical 的 Léonie Watson（https://front-end.social/@tink）和 Gez Lemon（https://www.linkedin.com/in/gez-lemon-0240692/）的消息，他们非常礼貌地告诉我，我犯了一个愚蠢的错误。Scott 的模式是正确的，但我在移除 `aria-label` 时偏离了正轨，因为现在按钮没有可访问名称了。`aria-describedby` 提供的是附加信息——它不是可访问名称的替代品。 事实上，Windows 上的 JAWS 会尝试从附近元素收集可访问文本，最终把粗体按钮同时播报为粗体和斜体，因为斜体工具提示元素在 DOM 中是兄弟节点。 其实有一个线索：当 VoiceOver 说“可点击图像”时，那是在表示它没有可宣布的可访问名称。我当时只是没有意识到这一点。 ## 修复方法 Léonie 和 Gez 告诉了我如何修复： 我将 `aria-describedby` 换成了 `aria-labelledby`。 ```html <button aria-labelledby="tooltip"> (粗体图标) </button> <p role="tooltip" id="tooltip">粗体（⌘B）</p> ``` `aria-labelledby` 的工作方式与 `aria-describedby` 类似，但它提供的是可访问名称，而不是附加描述。现在按钮从工具提示中获取其可访问名称，VoiceOver 会说“粗体。Command B。按钮。”——完美！ 如果我愿意，我可以将其拆分，使可访问名称仅为“粗体”，附加描述为“Command B”： ```html <button aria-labelledby="label" aria-describedby="description"> (粗体图标) </button> <span id="label">粗体</span> <p role="tooltip" id="description">⌘B</p> ``` 我认为在这种情况下这样做有些多余，但如果你有更长的工具提示描述，那可能就有意义了。 就是这样！始终确保交互元素具有可访问名称。并且如果可能的话，用多种屏幕阅读器进行测试。在一种屏幕阅读器中测试就像在一种浏览器中测试——它并不总能让你看到全貌。 这是修复后的演示（https://random-stuff.jakearchibald.com/popover-hint-tooltip/），不过在 Safari 中它不太正常，因为 Safari 还不支持 `popover="hint"`。