什么是无障碍树(Accessibility Tree)?
了解浏览器如何构建无障碍树并计算角色和名称,以及如何在 DevTools 中检查,并用 Playwright 测试控件。
无障碍树是浏览器基于 DOM 为辅助技术构建的另一种网页表示形式。它保留每个有意义元素的角色(role)、可访问名称(accessible name)、状态(state)和值(value),同时剔除大部分仅用于布局的包装元素。
你在以下场景中会遇到它:审计工具报告 “button has no accessible name”;linter 对可点击的 div 发出警告;或者 Playwright 的 getByRole 找不到一个明明显示在屏幕上的元素。这三者报告的其实是同一个结构。本文将介绍浏览器如何构建这棵树、每个节点包含哪些信息、如何检查它,以及如何针对它编写测试。
要点速览
- 浏览器根据 DOM、原生 HTML 语义和 ARIA 属性构建无障碍树。仅用于样式的
div和span元素通常不会生成独立节点。 - 通过
display: none、visibility: hidden、hidden属性或aria-hidden="true"隐藏的内容会被排除在无障碍树之外,尽管它们仍然保留在 DOM 中。 - 简单来说,元素的可访问名称依次取自
aria-labelledby、aria-label、原生标签机制(<label>、alt)、文本内容,最后是title。 - 带有点击处理函数的
<div>在树中没有 button 角色,因此屏幕阅读器不会将其播报为控件,键盘用户也无法访问它。 - Playwright 的
getByRole定位器和 ARIA 快照基于角色和可访问名称工作,因此用它们编写的测试会在那些阻碍辅助技术用户的缺陷上同样失败。
浏览器如何构建无障碍树
浏览器根据三类输入构建无障碍树:DOM、HTML 元素的内置语义,以及所有 ARIA 属性。HTML-AAM 定义了每个 HTML 元素如何映射到无障碍角色,Core-AAM 1.2 则定义了 ARIA 角色、状态和属性如何映射到平台无障碍 API。
从 DOM 到无障碍树的映射并非一一对应。仅为 flexbox 布局或样式而存在的 <div> 或 <span> 通常会被扁平化处理掉。反过来,HTML-AAM 规定,带有 controls 属性的 <video> 会将其内置控件(如播放和音量)作为子节点暴露出来,并映射为 button、slider 等角色。而这些控件都不会出现在页面的 DOM 中。
隐藏内容同样会被移除。当元素未被渲染(display: none、visibility: hidden、HTML hidden 属性)或带有 aria-hidden="true" 时,WAI-ARIA 1.2 会将其从树中排除。“视觉隐藏”(visually hidden)或 sr-only 这类 CSS 类则属于另一种情况:它们只是把内容移出屏幕,因此内容仍然保留在树中。
无障碍节点包含哪些信息?
无障碍树中的每个节点最多暴露四类信息:角色(它是什么)、名称(它叫什么)、状态(它当前的情况),以及部分控件特有的值。以下是一个带标签的复选框:
<label><input type="checkbox" checked> Email me product updates</label>
在 Playwright 的 ARIA 快照格式中,生成的节点如下所示(示意):
- checkbox "Email me product updates" [checked]
角色是 checkbox,名称由 <label> 提供,[checked] 是状态。复选框通过其勾选状态传达信息。值适用于文本框、滑块等控件,快照格式会将其放在冒号之后:
- textbox "Email": ada@example.com
关于各个角色是如何确定的,以及何时需要自行添加 ARIA 角色,请参阅 Understanding Accessibility Roles in HTML。
可访问名称是如何计算的?
简单来说,浏览器会从第一个能提供名称的来源获取元素的可访问名称:
aria-labelledby,指向其他元素的文本aria-label- 原生标签机制:
<label>元素,或图片的alt文本 - 元素自身的文本内容,适用于允许从内容获取名称的角色(按钮、链接)
title属性,作为最后的备选
ARIA 的优先级高于原生标签机制。如果一个按钮的可见文本是 “Send”,同时带有 aria-label="Submit form",屏幕阅读器会播报 “Submit form”,而语音控制用户说出 “click Send” 时可能无法匹配到该按钮。完整算法(包括嵌入控件和递归处理)详见 Accessible Name and Description Computation 1.2。
屏幕阅读器如何使用无障碍树?
屏幕阅读器并不读取 DOM。它们通过操作系统的无障碍 API 读取无障碍树,而该 API 由浏览器负责实现。Core-AAM 的映射表涵盖了 Windows 上的 MSAA(配合 IAccessible2)和 UI Automation、macOS 上的 AX API(NSAccessibility),以及 Linux 上的 ATK/AT-SPI。屏幕阅读器向这些对象查询角色、名称和状态,并监听焦点变化等事件。如果某个属性从未进入无障碍树,用户也就永远听不到它。
如何检查无障碍树
Chrome DevTools 和 Firefox DevTools 都可以直接查看无障碍树:Chrome 通过 Elements 面板中的 Accessibility 标签页,Firefox 通过其 Accessibility Inspector(无障碍检查器)。
**Chrome:**打开 Elements 面板,选中一个节点,然后打开 Accessibility 标签页(它可能隐藏在 More Tabs » 按钮后面)。该标签页会显示计算得出的角色、名称和属性,以及名称的来源。开启 Show accessibility tree 后,Elements 面板中的 DOM 树会被替换为整个页面的无障碍树。Chrome DevTools 无障碍参考文档对这两项功能都有说明。Chrome 还提供了一个内部页面 chrome://accessibility,用于浏览器级别的调试。
Firefox:Accessibility Inspector 可以通过页面右键菜单(Inspect Accessibility Properties)打开,也可以在 Inspector 的 HTML 窗格中右键单击某个节点并选择 Show Accessibility Properties。该检查器展示的是 Gecko 自身的无障碍树,而非来自平台无障碍层的信息,因此在所有操作系统上的输出都相同。
无障碍树揭示的两类缺陷
无障碍树能让两类常见的组件缺陷一目了然:没有 button 角色的可点击 div,以及没有可访问名称的图标按钮。每个问题都表现为缺失角色或缺失名称。Vue 和 Angular 模板会产生同样的结果,因为无障碍树只看渲染后的 DOM。
没有 button 角色的可点击 div
// Before
<div className="btn" onClick={save}>Save</div>
// After
<button type="button" onClick={save}>Save</button>
# Before (illustrative)
- text: Save
# After
- button "Save"
带有点击处理函数的 <div> 在无障碍树中没有 button 角色。屏幕阅读器不会将其播报为控件,键盘用户也无法通过 Tab 键聚焦到它,或用 Enter、Space 键激活它。这类缺陷的会话回放能清楚地展现其中的差距:鼠标用户可以顺利点击该控件,而键盘用户按 Tab 键时会直接跳过这个看起来像按钮、但在无障碍树中并不以按钮身份存在的元素。
没有名称的图标按钮
// Before
<button onClick={close}><svg aria-hidden="true">{/* icon */}</svg></button>
// After
<button aria-label="Close dialog" onClick={close}>
<svg aria-hidden="true">{/* icon */}</svg>
</button>
# Before (illustrative)
- button
# After
- button "Close dialog"
一个仅含图标、既没有文本也没有 aria-label 的按钮,会显示为名称为空的 button,屏幕阅读器除了 “button” 之外无可播报。
使用 Playwright 测试无障碍树
Playwright 的 getByRole 定位器遵循 W3C 规范,通过 ARIA 角色、ARIA 属性和可访问名称查找元素,并且默认只匹配未隐藏的元素。因此,按角色和名称查找控件的测试,同时也在检查该控件是否暴露了相应的角色和名称。ARIA 快照则更进一步:locator.ariaSnapshot() 和 page.ariaSnapshot() 返回无障碍树的 YAML 视图,expect(locator).toMatchAriaSnapshot() 则基于它进行断言。
import { test, expect } from '@playwright/test';
test('save control is a real button', async ({ page }) => {
await page.goto('/settings');
await page.getByRole('button', { name: 'Save' }).click();
await expect(page.locator('body')).toMatchAriaSnapshot(`- button "Save"`);
await expect(page.locator('body')).toMatchAriaSnapshot(`- button "Close dialog"`);
});
针对”修复前”的标记运行此测试,getByRole 调用会失败,其原因与屏幕阅读器用户受阻的原因相同。模板只需匹配树的一部分,像上面这样的单节点模板可以在任意层级上匹配。如果模板在顶层列出多个节点,它们必须拥有同一个父节点,且顺序与树中一致。当定位器失败时,可以输出 await page.ariaSnapshot() 的结果,查看树中实际包含的内容。以上均为 JavaScript 中的 API 名称,其他语言绑定也有对应的等价 API。Playwright 文档同时指出,基于角色的定位器并不能替代无障碍审计和合规性测试,因此应将其视为早期反馈手段。
角色和名称数据的作用也不止于测试运行器。一些 AI 驱动的自动化工具会读取页面的语义结构,这也是智能体浏览器(agentic browsers)在语义化标记上表现最佳的原因之一。
总结
无障碍树是辅助技术实际接收到的 UI 版本,其中缺失的角色或空名称意味着该控件对这些用户而言是不可用的。打开你最常用的自定义组件的 Accessibility 标签页,检查它的角色和名称,然后把这项检查转化为 getByRole 断言,确保问题修复后不再复发。
常见问题
给 div 添加 role='button' 能在无障碍树中修复问题吗?
只能部分修复。添加 role='button' 会让该 div 在无障碍树中拥有一个 button 节点,屏幕阅读器会将其播报为按钮,但它并不会带来任何按钮行为。该 div 仍需要 tabindex='0' 才能加入 Tab 键顺序,还需要一个 keydown 处理函数,在按下 Enter 和 Space 键时执行相应操作。原生 button 元素默认就提供焦点和键盘激活能力。
aria-hidden='true' 能阻止键盘用户聚焦元素吗?
不能。aria-hidden='true' 会将元素及其后代从无障碍树中移除,但对键盘焦点没有任何影响。位于 aria-hidden 容器内的链接、按钮或输入框仍然可以通过 Tab 键获得焦点,导致键盘用户停留在一个辅助技术无法为其命名的控件上。在子元素上设置 aria-hidden='false' 并不能让它重新暴露出来。若要对所有用户隐藏交互内容,请使用 display: none 或 hidden 属性。
如何在自动化测试中读取元素计算后的角色和可访问名称?
应使用自动化命令,而不是页面脚本。W3C WebDriver 规范定义了 Get Computed Role 和 Get Computed Label 命令,ChromeDriver 实现了这两个命令,WebdriverIO 则将其暴露为 getComputedRole() 和 getComputedLabel()。Playwright 为单个元素提供了 toHaveRole() 和 toHaveAccessibleName() 断言,并提供 ariaSnapshot() 用于获取整个子树的 YAML 视图。这些方式报告的都是辅助技术实际接收到的角色和名称。
为什么升级到 Playwright 1.65 后,getByRole 的名称匹配结果发生了变化?
Playwright 1.65 不再将浏览器未渲染的文本计入可访问名称和 ARIA 快照。未分配到插槽(slot)的文本,或直接位于已关闭的 details 元素内部的文本,都不再计入。这可能会改变带 name 选项的 getByRole() 的结果、ariaSnapshot() 的输出以及 toMatchAriaSnapshot() 断言,因此期望的名称必须只匹配浏览器实际渲染的文本。
Gain control over your UX
See how users are using your site as if you were sitting next to them, learn and iterate faster with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.
Star on GitHub12k