11 无障碍(二):主题切换与 axe 修复
一句话结论:按钮的可访问名称必须和当前可见文案一致;动态
aria-label在 SSR 与水合之间最容易失配,label-content-name-mismatch只是把这个隐藏问题提前暴露出来,真正的修复是让名称来自 DOM 里可见的文字。
它解决什么问题
亮暗主题切换看起来是一个很小的交互:一个按钮,点一下,换一套颜色。但它同时涉及三件事:首屏前要避免闪烁、客户端要持久化偏好、按钮要告诉读屏器「点下去会发生什么」。前两件在 04 的前端篇里已经讲过,这篇只处理第三件。
第一版实现很自然:按钮的可见文案跟着当前主题变,aria-label 也跟着变。
<BaseButton :aria-label="resolved === 'dark' ? '切换到浅色' : '切换到暗色'">
{{ resolved === 'dark' ? '浅色' : '暗色' }}
</BaseButton>
浅色主题下,按钮显示「暗色」,可访问名称是「切换到暗色」;暗色主题下,显示「浅色」,名称是「切换到浅色」。逻辑上完全对。e2e 测试在浅色下也能通过。问题出在 SSR 输出和客户端初始化之间:服务端不知道用户本地存了什么偏好,只能先按默认亮色渲染;客户端脚本读到暗色偏好后,把可见文案改成「浅色」,但 aria-label 的更新时机和可见文案并不总是一致。
axe 在暗色主题下报了:
label-content-name-mismatch
impact: serious
nodes: ["button"]
这条规则的意思是:可访问名称里必须包含可见的文字内容。屏幕上写着「浅色」,读屏器却听到「切换到暗色」,两个用户看到的是两个不同的按钮。
我怎么试的
1. 先复现,不急着改
我把 axe 的扫描拆成亮暗两组,用 Playwright 的 colorScheme 模拟系统主题:
for (const theme of ['light', 'dark'] as const) {
test.describe(`${theme} 主题`, () => {
test.use({ colorScheme: theme })
// ...
})
}
亮色组全部通过,暗色组在首页报出 label-content-name-mismatch。这说明问题不在按钮的视觉样式,而在「当前主题」这个状态进入 DOM 的时机。
2. 理解可访问名称的计算顺序
读屏器读一个按钮时,名称不是简单取 textContent,而是按一套优先级计算:
aria-labelledby指向的元素;aria-label;- 元素内部的可见文字;
title等兜底属性。
aria-label 的优先级高于内部文字。所以第一版里,即使可见文案已经变成「浅色」,只要 aria-label 还是「切换到暗色」,读屏器就会读旧值。SSR 与水合的时间差,正好让这两个来源短暂不一致。
这里还有一个容易忽略的点:display: none 的文字不参与可访问名称计算。后面用 CSS 切换两段文案时,隐藏的那段不会被读出来;读屏器只会读到当前显示的那一段。这是方案能成立的前提。
3. 修复:让名称来自可见文字
最后把 aria-label 去掉,改成三段文字:
<BaseButton variant="secondary" @click="toggle">
<span :class="$style.content">
<span :class="$style['sr-only']">切换到</span>
<span :class="[$style.label, $style['label-light']]">暗色</span>
<span :class="[$style.label, $style['label-dark']]">浅色</span>
<svg aria-hidden="true">...</svg>
</span>
</BaseButton>
sr-only的「切换到」只给读屏器,补齐动作语义;- 「暗色」和「浅色」都在 DOM 里,用 CSS 控制显示;
- SVG 是装饰图标,
aria-hidden="true",不参与名称。
CSS 只做显示切换:
.label-dark,
.icon-dark {
display: none;
}
:global([data-theme='dark']) .label-light,
:global([data-theme='dark']) .icon-light {
display: none;
}
:global([data-theme='dark']) .label-dark {
display: inline;
}
:global([data-theme='dark']) .icon-dark {
display: block;
}
亮色下,可访问名称是「切换到 暗色」;暗色下是「切换到 浅色」。名称和可见文案来自同一个 DOM 状态,不再需要额外同步一个属性。
这里也没有加 aria-live。主题切换是用户主动触发的,按钮名称会跟着变;再加一个实时区域,反而可能在用户每次切换时重复播报。读屏器用户需要的是按钮名称准确,不是额外的通知。e2e 里对应断言:
const toggle = page.getByRole('button', { name: /切换到\s*暗色/ })
await expect(toggle).toContainText('暗色')
4. axe 矩阵:6 页 × 2 主题
可访问性测试不是只扫首页:
const pages = [
'/',
'/notes',
'/notes/magpie',
'/notes/build-log-00-overview',
'/notes/build-practice-05-deployment-docker',
'/series',
'/about',
'/chat',
]
八个页面分别覆盖首页、目录、两篇详情、系列总览、关于页和聊天页;每个页面在亮暗两套主题下各跑一次,共 16 个测试;另外还有一条单独检查助手浮窗的用例。扫描标签限定在 WCAG 2 A/AA 和 WCAG 2.1 A/AA,只把 serious 和 critical 作为失败条件:
const serious = results.violations.filter(
(violation) => violation.impact === 'serious' || violation.impact === 'critical',
)
expect(serious).toEqual([])
只卡严重级别,是因为 minor 和 moderate 里可能包含需要人工判断的项;如果全部卡死,CI 会因为一些不影响可用性的提示长期变红,最后大家对红色麻木。严重和致命问题先清零,剩下的进入人工清单。
5. 修复后的人工检查
axe 通过后,我仍然做了几件事:
- 用 Tab 走到主题按钮,确认焦点环在亮暗背景下都看得见;
- 按空格切换主题,确认焦点没有丢失、按钮文案和图标同步变化;
- 把页面放大到 200%,确认按钮没有被裁切;
- 用读屏器听一遍按钮,确认读出来的是「切换到 暗色」或「切换到 浅色」,而不是重复或缺失。
这些检查不能自动化,但它们决定了「没有 axe 错误」和「真的可用」之间的差距。
坑和限制
1. axe 通过不等于没有可访问性问题。 axe 能检查名称、对比度、landmark 等结构性规则,但检查不了朗读顺序是否自然、错误提示是否有上下文、动效是否让人不适。它是一道筛子,不是结论。
2. aria-pressed 不是这个按钮的正确答案。 主题按钮描述的是「点击后会发生什么」,不是「当前是否开启」。如果加 aria-pressed,读屏器可能读成「切换到 暗色,切换按钮,未按下」,反而让状态和动作混在一起。这里保持普通按钮语义更清楚。
3. CSS 切换文案依赖 DOM 里同时存在两段文字。 这意味着按钮的文本内容在源码里是重复的;如果以后做国际化,需要确保两段文案都走翻译,而不是只翻译当前显示的那一段。
4. SSR 与水合的时序仍然重要。 修复解决的是名称不一致,不是首屏闪烁。首屏主题仍然由 nuxt.config.ts 里的内联脚本在样式前设置 data-theme;这一段如果被 CSP 或脚本加载顺序破坏,用户还是会看到闪一下。
5. prefers-reduced-motion 还没有实现。 主题切换本身没有复杂动画,但页面其他过渡效果没有统一的减少动效策略。这是一项已知缺口,不能因为 axe 通过就认为可访问性工作结束。
6. 没有读屏器自动化。 CI 里只有 axe;真正的读屏器测试仍然是手动。个人项目可以接受,但要知道这条边界。
适合谁
这篇适合正在做主题切换、图标按钮或设计系统的前端。它讲的是一个很小的按钮,但背后是可访问名称、SSR 水合和自动化测试边界三个常见问题。如果你的按钮同时有图标和会变化的文字,这篇的坑大概率也会遇到。