Web 无障碍工程化实战：ARIA 属性体系与键盘导航在复杂应用中的落地指南-171主机测评

Web 无障碍工程化实战：ARIA 属性体系与键盘导航在复杂应用中的落地指南

前言

周六的清晨，我照例在阳台上看书。"像素"趴在我膝头，偶尔抬头蹭蹭翻页的手。

手机亮了，是同事发来的消息："我们 App 被无障碍审计打回来了，好几个组件完全不支持键盘操作，屏幕阅读器读到的东西也是乱的。产品的意思是，下个迭代必须修完。"

我叹了口气，关掉了手里的书。Web 无障碍（a11y）在国内前端圈一直是个"说起来重要，做起来次要"的话题。不是大家不想做，而是真的不知道从哪下手。

今天我就从 ARIA 的核心原理出发，带你走一遍工程化的无障碍落地路径。

一、底层原理

1.1 无障碍树的本质

浏览器在解析 DOM 树的同时，会生成一棵无障碍树（Accessibility Tree）。屏幕阅读器（如 NVDA、VoiceOver）读取的是这棵树，而非直接读 DOM。

graph TD
A["HTML DOM 树"] –> B["浏览器构建 Accessibility Tree"]
C["ARIA 属性"] –> B
B –> D["屏幕阅读器 API\\n(Windows: UIA / macOS: AXAPI)"]
D –> E["语音合成输出\\n或盲文显示"]

F["键盘事件处理"] –> G["焦点管理\\n(Focus Management)"]
G –> H["用户通过键盘操作"]

这意味着：一个在视觉上完美的组件，如果无障碍树里是空的，那它对辅助技术来说就等于不存在。

1.2 ARIA 的三大支柱

ARIA（Accessible Rich Internet Applications）规范定义了三个核心概念：

概念表示方式作用

角色（Role）	role="button"	告诉辅助技术"这是个什么东西"
属性（Property）	aria-label="关闭"	描述元素的特征或状态
状态（State）	aria-expanded="true"	表示元素的当前状态，会动态变化

最重要的一条 ARIA 原则：不要滥用 ARIA。优先使用原生 HTML 语义元素，只有当原生语义不足时才用 ARIA 补充。

<!– ✅ 好的做法：用原生 button –>
<button>提交</button>

<!– ❌ 差的做法：用 div + ARIA –>
<div role="button" tabindex="0">提交</div>

<!– ✅ ARIA 的正确使用场景：复杂组件 –>
<div role="tabpanel" aria-labelledby="tab-1">
这里是标签面板的内容
</div>

1.3 焦点管理是键盘导航的基石

所有可交互的元素必须能被键盘焦点抵达。在 Web 平台上，只有少数元素默认可获得焦点：

元素默认可获得焦点可参与 Tab 键顺序

<a href="…">	✅	✅
<button>	✅	✅
<input>	✅	✅
<select>	✅	✅
<textarea>	✅	✅
<div> / <span>	❌	❌

对于非默认可聚焦的元素，需要用 tabindex 赋予焦点能力：

tabindex 值含义

tabindex="0"	元素可通过 Tab 获得焦点，按 DOM 顺序排列
tabindex="-1"	元素只能通过 JS 调用 .focus() 获得焦点，Tab 跳过
tabindex="5"	⚠️ 不要用正数，会破坏自然的 Tab 顺序

二、快速上手

2.1 三行代码提升 80% 的无障碍水平

你不需要学完整个 ARIA 规范。只需要做到这三件事，就能覆盖大部分场景：

<!– 1. 给每一个交互元素提供可访问的名称 –>
<button aria-label="关闭对话框">✕</button>

<!– 2. 告知动态内容的变化 –>
<div role="alert" aria-live="polite">
表单提交成功！
</div>

<!– 3. 确保所有功能可通过键盘操作 –>
<div
role="button"
tabindex="0"
@keydown.enter.prevent="handleClick"
@keydown.space.prevent="handleClick"
>
自定义按钮
</div>

2.2 最小可行性示例：一个无障碍的折叠面板

<div class="accordion">
<h3>
<button
class="accordion-trigger"
aria-expanded="false"
aria-controls="panel-content"
id="accordion-btn"
>
什么是无障碍设计？
</button>
</h3>
<div
id="panel-content"
role="region"
aria-labelledby="accordion-btn"
class="accordion-panel"
hidden
>
<p>无障碍设计（Accessible Design）是指让产品能被尽可能多的人使用的设计方法，包括残障人士。</p>
</div>
</div>

.accordion-trigger {
width: 100%;
padding: 12px 16px;
background: var(–color-surface, #fff);
border: 1px solid var(–color-border, #e2e8f0);
border-radius: 8px;
font-size: 16px;
text-align: left;
cursor: pointer;
display: flex;
justify-content: space-between;
align-items: center;
}

.accordion-trigger:focus-visible {
outline: 2px solid #6573ed;
outline-offset: 2px;
}

.accordion-trigger[aria-expanded="true"]::after {
content: "▲";
}

.accordion-trigger[aria-expanded="false"]::after {
content: "▼";
}

.accordion-panel {
padding: 16px;
border: 1px solid var(–color-border, #e2e8f0);
border-top: none;
border-radius: 0 0 8px 8px;
}

document.querySelectorAll('.accordion-trigger').forEach(btn => {
btn.addEventListener('click', () => {
const isExpanded = btn.getAttribute('aria-expanded') === 'true';
const panel = document.getElementById(btn.getAttribute('aria-controls'));

btn.setAttribute('aria-expanded', !isExpanded);
panel.hidden = isExpanded;
});

// 支持 Enter 和 Space 键（button 默认支持，这里是显式演示）
btn.addEventListener('keydown', (e) => {
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault();
btn.click();
}
});
});

三、深水区：复杂组件的无障碍工程化

3.1 对话框（Dialog）的无障碍模式

模态对话框是无障碍中最容易出问题的组件之一。它必须实现：

打开时焦点移到对话框内

内容后面的元素应标记为不可见（aria-hidden）

按 Escape 键关闭

焦点在对话框内循环（focus trap）

关闭后焦点回到触发按钮

class AccessibleDialog {
constructor(triggerBtn, dialogElement) {
this.trigger = triggerBtn;
this.dialog = dialogElement;
this.previousFocus = null;
this.focusableElements = [];

this.init();
}

init() {
this.trigger.addEventListener('click', () => this.open());

this.dialog.addEventListener('keydown', (e) => {
if (e.key === 'Escape') this.close();

// 焦点循环 (Focus Trap)
if (e.key === 'Tab') {
this.trapFocus(e);
}
});

// 收集所有可获得焦点的子元素
const selector = 'a[href], button, input, textarea, select, [tabindex]:not([tabindex="-1"])';
this.focusableElements = [
…this.dialog.querySelectorAll(selector),
];
}

open() {
this.previousFocus = document.activeElement;

// 隐藏背景内容
const mainEl = document.querySelector('main');
if (mainEl) mainEl.setAttribute('aria-hidden', 'true');

this.dialog.removeAttribute('hidden');
this.dialog.setAttribute('aria-modal', 'true');
this.dialog.setAttribute('role', 'dialog');

// 焦点移到对话框的第一个可聚焦元素
const firstFocusable = this.focusableElements[0];
if (firstFocusable) {
firstFocusable.focus();
}
}

close() {
this.dialog.setAttribute('hidden', '');
this.dialog.removeAttribute('aria-modal');

const mainEl = document.querySelector('main');
if (mainEl) mainEl.removeAttribute('aria-hidden');

// 焦点回到触发按钮
if (this.previousFocus) {
this.previousFocus.focus();
}
}

trapFocus(e) {
const first = this.focusableElements[0];
const last = this.focusableElements[this.focusableElements.length – 1];

if (e.shiftKey && document.activeElement === first) {
e.preventDefault();
last.focus();
} else if (!e.shiftKey && document.activeElement === last) {
e.preventDefault();
first.focus();
}
}
}

💡 里欧的碎碎念：aria-modal="true" 是 HTML 5.2 引入的属性，它告诉屏幕阅读器"对话框之外的内容不可访问"。相比手动控制 aria-hidden，这是更干净的方案——但为了兼容性，我通常两种都用。

3.2 自定义 Select 组件的完整键盘交互

一个符合 WAI-ARIA 规范的自定义选择器，需要实现以下键盘映射：

class AccessibleSelect {
constructor(container) {
this.container = container;
this.combobox = container.querySelector('[role="combobox"]');
this.listbox = container.querySelector('[role="listbox"]');
this.options = […container.querySelectorAll('[role="option"]')];
this.currentIndex = -1;

this.init();
}

init() {
this.combobox.addEventListener('click', () => this.toggle());
this.combobox.addEventListener('keydown', (e) => this.handleKeydown(e));
this.listbox.addEventListener('keydown', (e) => this.handleKeydown(e));

// 点击选项时选择
this.options.forEach((opt, i) => {
opt.addEventListener('click', () => this.select(i));
});
}

open() {
this.listbox.removeAttribute('hidden');
this.combobox.setAttribute('aria-expanded', 'true');
this.currentIndex = 0;
this.highlight(0);
}

close() {
this.listbox.setAttribute('hidden', '');
this.combobox.setAttribute('aria-expanded', 'false');
}

toggle() {
const expanded = this.combobox.getAttribute('aria-expanded') === 'true';
expanded ? this.close() : this.open();
}

select(index) {
// 更新之前选项的状态
this.options.forEach(opt => opt.setAttribute('aria-selected', 'false'));

// 选中当前选项
const selected = this.options[index];
selected.setAttribute('aria-selected', 'true');
this.combobox.textContent = selected.textContent;
this.combobox.setAttribute('aria-activedescendant', selected.id);

this.currentIndex = index;
this.close();
}

highlight(index) {
this.options.forEach(opt => opt.classList.remove('highlighted'));
this.options[index]?.classList.add('highlighted');
this.combobox.setAttribute('aria-activedescendant', this.options[index]?.id || '');
}

handleKeydown(e) {
const expanded = this.combobox.getAttribute('aria-expanded') === 'true';

switch (e.key) {
case 'Enter':
case ' ':
e.preventDefault();
if (expanded && this.currentIndex >= 0) {
this.select(this.currentIndex);
} else {
this.open();
}
break;

case 'Escape':
e.preventDefault();
this.close();
break;

case 'ArrowDown':
e.preventDefault();
if (!expanded) { this.open(); return; }
this.currentIndex = Math.min(this.currentIndex + 1, this.options.length – 1);
this.highlight(this.currentIndex);
break;

case 'ArrowUp':
e.preventDefault();
if (!expanded) { this.open(); return; }
this.currentIndex = Math.max(this.currentIndex – 1, 0);
this.highlight(this.currentIndex);
break;

case 'Home':
e.preventDefault();
if (expanded) {
this.currentIndex = 0;
this.highlight(0);
}
break;

case 'End':
e.preventDefault();
if (expanded) {
this.currentIndex = this.options.length – 1;
this.highlight(this.currentIndex);
}
break;
}
}
}

<!– 符合 ARIA 规范的自定义 Select –>
<div class="custom-select">
<div
role="combobox"
aria-expanded="false"
aria-haspopup="listbox"
aria-controls="select-listbox"
aria-label="选择城市"
tabindex="0"
id="select-combobox"
>
请选择城市
</div>
<ul
role="listbox"
id="select-listbox"
aria-labelledby="select-combobox"
hidden
>
<li role="option" id="opt-beijing" aria-selected="false">北京</li>
<li role="option" id="opt-shanghai" aria-selected="false">上海</li>
<li role="option" id="opt-guangzhou" aria-selected="false">广州</li>
<li role="option" id="opt-shenzhen" aria-selected="false">深圳</li>
</ul>
</div>

四、实战演练

4.1 场景：一个完整的无障碍 Tabs 组件

Tabs 组件必须遵守 WAI-ARIA Tabs 设计模式。关键的交互规则：

Tab 键进入 Tab 列表后，用左右箭头切换 Tab
aria-selected 标识当前选中的 Tab
aria-controls 关联 Tab 与对应的 panel
tabindex="-1" 让未激活的 Tab 不可通过 Tab 键到达

<div role="tabpanel" id="panel-all" aria-labelledby="tab-all">
<p>全部文章列表…</p>
</div>
<div role="tabpanel" id="panel-frontend" aria-labelledby="tab-frontend" hidden>
<p>前端文章列表…</p>
</div>
<div role="tabpanel" id="panel-backend" aria-labelledby="tab-backend" hidden>
<p>后端文章列表…</p>
</div>
</div>

.tab-list {
display: flex;
gap: 0;
border-bottom: 2px solid var(–color-border, #e2e8f0);
}

[role="tab"] {
padding: 10px 20px;
border: none;
background: none;
font-size: 15px;
cursor: pointer;
color: var(–color-text-secondary, #64748b);
border-bottom: 2px solid transparent;
margin-bottom: -2px;
transition: color 0.2s, border-color 0.2s;
}

[role="tab"][aria-selected="true"] {
color: var(–color-primary, #6573ed);
border-bottom-color: var(–color-primary, #6573ed);
}

[role="tab"]:focus-visible {
outline: 2px solid var(–color-primary, #6573ed);
outline-offset: 2px;
border-radius: 4px;
}

[role="tabpanel"] {
padding: 20px 0;
}

class AccessibleTabs {
constructor(container) {
this.container = container;
this.tabs = […container.querySelectorAll('[role="tab"]')];
this.panels = […container.querySelectorAll('[role="tabpanel"]')];

this.init();
}

init() {
this.tabs.forEach((tab, index) => {
tab.addEventListener('click', () => this.activate(index));
tab.addEventListener('keydown', (e) => this.handleKeydown(e, index));
});
}

activate(index) {
// 更新所有 tab 状态
this.tabs.forEach((tab, i) => {
const isActive = i === index;
tab.setAttribute('aria-selected', String(isActive));
tab.setAttribute('tabindex', isActive ? '0' : '-1');
});

// 更新所有 panel 状态
this.panels.forEach((panel, i) => {
panel.hidden = i !== index;
});

// 焦点移到激活的 tab
this.tabs[index].focus();
}

handleKeydown(e, index) {
let targetIndex = -1;

switch (e.key) {
case 'ArrowRight':
e.preventDefault();
targetIndex = (index + 1) % this.tabs.length;
break;
case 'ArrowLeft':
e.preventDefault();
targetIndex = (index – 1 + this.tabs.length) % this.tabs.length;
break;
case 'Home':
e.preventDefault();
targetIndex = 0;
break;
case 'End':
e.preventDefault();
targetIndex = this.tabs.length – 1;
break;
}

if (targetIndex >= 0) {
this.activate(targetIndex);
}
}
}

五、避坑指南与最佳实践

⚠️ 警告 1：aria-label 会覆盖元素内的文本内容。如果你给一个 <button aria-label="关闭">✕</button> 加了 aria-label，屏幕阅读器会读"关闭"而不是"✕"。但如果你写的是 <button aria-label="关闭">关闭窗口</button>，那「关闭」会被读两遍。语义要唯一。

⚠️ 警告 2：不要移除 :focus 轮廓线而不提供替代方案。outline: none 是 Web 无障碍中最常见的违规项。移除默认轮廓后，必须用 :focus-visible 提供自定义焦点样式。默认的蓝色轮廓确实不够美观，但直接移除等于让键盘用户"失明"。

✅ 推荐 1：用 :focus-visible 替代 :focus。:focus-visible 只在键盘导航时显示焦点环，鼠标点击时不显示。这是目前最推荐的焦点样式策略：

/* 鼠标点击时不显示焦点环 */
button:focus:not(:focus-visible) {
outline: none;
}

/* 键盘 Tab 导航时显示 */
button:focus-visible {
outline: 2px solid #6573ed;
outline-offset: 2px;
}

✅ 推荐 2：用 aria-live 告知动态内容变化。对于 Toast 通知、表单验证消息等动态更新的内容，使用 aria-live 区域让屏幕阅读器自动播报：

aria-live 的三个模式：

off：不自动播报（默认）
polite：在当前内容读完后再播报（推荐用于大多数通知）
assertive：立即中断当前内容播报（仅用于紧急警告）

✅ 推荐 3：用 sr-only 类给视觉隐藏但辅助技术可读的内容。

.sr-only {
position: absolute;
width: 1px;
height: 1px;
padding: 0;
margin: -1px;
overflow: hidden;
clip: rect(0, 0, 0, 0);
white-space: nowrap;
border: 0;
}

使用场景：操作按钮不需要视觉标签，但屏幕阅读器需要：

🎨 里欧的美学贴士：无障碍设计从来不是"为少数人做的妥协"，而是"让所有人体验更好的设计"。高对比度、大热区、清晰的焦点指示——这些对残障人士是必需品，对普通用户同样是体验升级。一个好的前端工程师，应该把无障碍当成代码质量的一部分，而非锦上添花。

六、综合实战演示

下面是一个无障碍检查清单，可以直接作为团队 Code Review 的参考标准：

// a11y-audit.js — 运行时无障碍自检工具
class A11yAudit {
constructor(root = document) {
this.root = root;
this.issues = [];
}

run() {
this.issues = [];
this.checkImages();
this.checkButtons();
this.checkForms();
this.checkFocus();
this.checkHeadings();
this.checkLandmarks();
this.checkColorContrast();
return this.report();
}

checkImages() {
// 所有 <img> 必须有 alt 属性
this.root.querySelectorAll('img:not([alt])').forEach(img => {
this.issues.push({
severity: 'error',
element: img,
message: '图片缺少 alt 属性',
fix: `添加 alt="${img.getAttribute('src')?.split('/').pop() || '图片描述'}"`,
});
});
}

checkButtons() {
// 检查所有可点击的 div/span 是否有关联的 role 和 tabindex
const clickableDivs = this.root.querySelectorAll(
'[onclick], [ng-click], [@click]'
);
clickableDivs.forEach(el => {
if (el.tagName !== 'BUTTON' && el.tagName !== 'A') {
if (!el.getAttribute('role')) {
this.issues.push({
severity: 'warning',
element: el,
message: '非按钮元素绑定了点击事件，缺少 role="button"',
fix: '添加 role="button" 和 tabindex="0"',
});
}
}
});
}

checkForms() {
// 所有 input 必须有对应的 label
this.root.querySelectorAll('input, select, textarea').forEach(field => {
const id = field.getAttribute('id');
if (id) {
const label = this.root.querySelector(`label[for="${id}"]`);
if (!label && !field.getAttribute('aria-label')) {
this.issues.push({
severity: 'error',
element: field,
message: `表单字段缺少关联的 label`,
fix: `添加 <label for="${id}">…</label> 或 aria-label 属性`,
});
}
} else {
this.issues.push({
severity: 'warning',
element: field,
message: '表单字段缺少 id 属性，无法关联 label',
fix: '添加 id 属性并关联对应的 label',
});
}
});
}

checkFocus() {
// 检查是否有 outline: none 但没有替代焦点样式
this.root.querySelectorAll('[tabindex]').forEach(el => {
const style = window.getComputedStyle(el);
if (style.outlineStyle === 'none') {
this.issues.push({
severity: 'warning',
element: el,
message: '元素移除了 outline 但未提供替代焦点样式',
fix: '添加 :focus-visible 样式',
});
}
});
}

checkHeadings() {
// 检查标题层级是否跳跃
const headings = […this.root.querySelectorAll('h1,h2,h3,h4,h5,h6')];
let lastLevel = 0;
headings.forEach(h => {
const level = parseInt(h.tagName[1]);
if (lastLevel > 0 && level > lastLevel + 1) {
this.issues.push({
severity: 'warning',
element: h,
message: `标题层级从 h${lastLevel} 跳到了 h${level}`,
fix: `考虑使用 h${lastLevel + 1} 替代 h${level}`,
});
}
lastLevel = level;
});
}

checkLandmarks() {
// 检查是否有关键区域标识
const landmarks = [
'header', 'nav', 'main', 'footer', 'aside',
'[role="banner"]', '[role="navigation"]',
'[role="main"]', '[role="contentinfo"]',
];
const found = landmarks.some(sel => this.root.querySelector(sel));
if (!found) {
this.issues.push({
severity: 'info',
element: this.root.body,
message: '页面缺少 landmark 区域标识',
fix: '使用 <header>、<nav>、<main>、<footer> 等语义元素',
});
}
}

checkColorContrast() {
// 简化的对比度检查（仅检查显式设置的颜色）
const textElements = this.root.querySelectorAll('[style*="color"]');
textElements.forEach(el => {
const style = window.getComputedStyle(el);
const color = style.color;
const bg = style.backgroundColor;
if (color && bg) {
const ratio = this.getContrastRatio(color, bg);
if (ratio < 4.5) {
this.issues.push({
severity: 'warning',
element: el,
message: `文字对比度不足 (ratio: ${ratio.toFixed(1)})`,
fix: '使用对比度 ≥ 4.5:1 的颜色组合',
});
}
}
});
}

getContrastRatio(color1, color2) {
// 简化的亮度计算
const l1 = this.getLuminance(color1);
const l2 = this.getLuminance(color2);
const lighter = Math.max(l1, l2);
const darker = Math.min(l1, l2);
return (lighter + 0.05) / (darker + 0.05);
}

getLuminance(color) {
// 简化版：解析 rgb 值计算相对亮度
const match = color.match(/rgb\$(\\d+),\\s*(\\d+),\\s*(\\d+)\$/);
if (!match) return 1;
const [r, g, b] = [match[1], match[2], match[3]].map(c => {
const s = parseInt(c) / 255;
return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
});
return 0.2126 * r + 0.7152 * g + 0.0722 * b;
}

report() {
const errors = this.issues.filter(i => i.severity === 'error');
const warnings = this.issues.filter(i => i.severity === 'warning');
const infos = this.issues.filter(i => i.severity === 'info');

return {
total: this.issues.length,
errors: errors.length,
warnings: warnings.length,
infos: infos.length,
issues: this.issues,
pass: errors.length === 0,
};
}
}

// 在控制台运行
// const audit = new A11yAudit();
// console.table(audit.run().issues);

七、总结

Web 无障碍不是一条"额外的负担"，而是一条"正确的路"。ARIA 规范不是要你背下来，而是要你理解它背后的逻辑——让信息对所有人平等可及。

回到开头那个被无障碍审计打回来的项目，其实需要改动的地方并不多。一个规范的焦点管理、几行 aria-label、一些 role 标记——这些投入换来的，是产品对用户的包容性承诺。

"像素"在阳台上打了个哈欠，伸展了一下身体。阳光暖洋洋的，就像好的无障碍设计——你感受不到它的存在，但它让一切变得更舒适。

我是里欧，下期见。

Web 无障碍工程化实战：ARIA 属性体系与键盘导航在复杂应用中的落地指南