a11y-debugging

核心概念

页面定位：页面范围内的工具（take_snapshot、list_console_messages、evaluate_script、press_key、take_screenshot、lighthouse_audit 等）都需要 pageId 参数。使用 list_pages 获取可用的页面 ID，或从 new_page 获取。

无障碍树与 DOM：以视觉方式隐藏元素（例如 CSS opacity: 0）对屏幕阅读器的影响不同于 display: none 或 aria-hidden="true"。take_snapshot 工具会返回页面的无障碍树，表示辅助技术“看到”的内容，因此这是了解语义结构最可靠的依据。

阅读 web.dev 文档：如果需要研究特定的无障碍指南（例如 https://web.dev/articles/accessible-tap-targets），可以在 URL 后追加 .md.txt（例如 https://web.dev/articles/accessible-tap-targets.md.txt），获取简洁的原始 Markdown 版本。这样更容易阅读！

工作流模式

1. 自动化审计（Lighthouse）

首先运行 Lighthouse 无障碍审计，获取全面的基准结果。此工具会提供整体评分，并列出未通过审计的具体元素及修复建议。

1. 运行审计：
   • 将 mode 设为 "navigation"，以刷新页面并捕获加载问题。
   • 省略 outputDirPath，将报告保存到默认临时目录（report.json 的确切路径会在 Reports 下返回）；或者将 outputDirPath 设为工作区中的某个目录。
2. 分析摘要：
   • 在默认文本输出中，类别评分采用 0–100 分制（100 分为满分），随后会显示 Passed: N 和 Failed: N 审计计数。
   • 如果服务以 --experimentalStructuredContent 启动，则应改为查看结构化内容中的 summary.scores[].score（0–1 分制）和 summary.audits.failed。
3. 查看报告（重要）：
   • 解析：不要逐行读取整个文件。使用 jq 等命令行工具，或单行 Node.js 命令，根据 lighthouse_audit 返回的报告路径筛选未通过项：

     # 提取未通过的审计及其详情（替换为工具响应中的 report.json 路径）
     node -e "const r=require('<path/to/report.json>'); Object.values(r.audits).filter(a=>a.score!==null && a.score<1).forEach(a=>console.log(JSON.stringify({id:a.id, title:a.title, items:a.details?.items})))"
     

   • 这样可以高效提取未通过元素的 selector 和 snippet，而无需将整份报告加载到上下文中。

2. 浏览器问题与审计

Chrome 会自动检查常见的无障碍问题。使用 list_console_messages 检查这些原生审计：

• types：["issue"]
• includePreservedMessages：true（用于捕获页面加载期间发生的问题）

这通常能发现缺少标签、无效的 ARIA 属性和其他关键错误，无需手动调查。

3. 语义与结构

无障碍树会显示标题层级和语义地标。

1. 导航到页面。
2. 使用 take_snapshot 捕获无障碍树。
3. 检查标题级别：确保标题级别（h1、h2、h3 等）符合逻辑，且没有跳级。快照会包含标题角色。
4. 内容顺序调整：验证 DOM 顺序（它决定无障碍树）是否与视觉阅读顺序一致。使用 take_screenshot 检查视觉布局，并与快照结构对比，以发现 CSS 浮动或绝对定位导致逻辑顺序混乱的问题。

4. 标签、表单与文本替代内容

1. 在 take_snapshot 输出中查找按钮、输入框和图像。
2. 确保交互元素具有可访问名称（例如，如果按钮只包含图标，其名称不应只是 ""）。
3. 无关联标签的输入框：确认所有表单输入框都有关联标签。使用 evaluate_script，并采用 references/a11y-snippets.md 中的 “Find Orphaned Form Inputs”代码片段。
4. 检查图像是否有 alt 文本。

5. 焦点与键盘导航

在没有视觉反馈的情况下测试“键盘陷阱”和正确的焦点管理，需要跟踪当前获得焦点的元素。

1. 使用 press_key 工具和 "Tab" 或 "Shift+Tab" 移动焦点。
2. 使用 take_snapshot 捕获更新后的无障碍树。
3. 在快照中找到标记为获得焦点的元素，确认焦点已移至预期的交互元素。
4. 如果打开模态框，焦点必须移入模态框，并在关闭前一直被“限制”在其中。

6. 点击目标与视觉效果

根据 web.dev 的建议，点击目标至少应为 48x48 像素，并留有足够间距。由于无障碍树不会显示尺寸，请使用 evaluate_script，并采用 references/a11y-snippets.md 中的 “Measure Tap Target Size”代码片段。

将快照中的元素 uid 作为参数传递给 evaluate_script。

7. 颜色对比度

要验证颜色对比度，请使用 evaluate_script，并采用 references/a11y-snippets.md 中的 “Check Color Contrast”代码片段。

8. 页面全局检查

使用 references/a11y-snippets.md 中的 “Global Page Checks”代码片段，验证组件测试中经常遗漏的文档级无障碍设置。

故障排查

如果标准无障碍查询失败，或者 evaluate_script 代码片段返回意外结果：

• 视觉检查：如果自动化脚本无法判断对比度（例如，文本位于渐变图像或复杂背景上），请使用 take_screenshot 捕获该元素。虽然模型无法从图像中测量精确的对比度，但可以直观评估可读性并发现明显问题。