HTML中如何使用axe工具检查无障碍合规性-html教程-PHP中文网

axe是javascript库而非html标签，需通过脚本加载后调用axe.run()扫描dom；支持console手动调试、自动化测试集成及按需配置规则集，但仅检查静态结构，无法替代人工辅助技术实测。

html中如何使用axe工具检查无障碍合规性

axe 不是 HTML 内置标签或属性，也不能直接写在 HTML 文件里“使用”。它是一个 JavaScript 库，必须通过脚本加载、在运行时调用，才能对当前页面的 DOM 做无障碍扫描。

在浏览器控制台手动运行 `axe.run()` 最快验证页面

适合开发调试、临时抽查，无需改代码、不依赖构建流程：

打开目标页面（如 login.html），按 F12 打开开发者工具 → 切到 Console 标签页

确认 axe 已加载：输入 typeof axe，返回 "object" 才能继续；否则先执行：

const script = document.createElement('script');<br>script.src = 'https://cdn.jsdelivr.net/npm/axe-core@4.7.0/dist/axe.min.js';<br>document.head.appendChild(script);

等几秒后运行：

axe.run().then(results => console.table(results.violations.map(v => ({ id: v.id, impact: v.impact, description: v.description, nodes: v.nodes.length }))));

注意：若页面含 Shadow DOM 或动态组件（如 CKEditor5），需传入 { shadowDom: true } 选项，否则漏检

在自动化测试中集成 `axe.run()` 需处理异步与上下文

常见于 Jest / Cypress / Mocha 等环境，关键不是“调用了”，而是“等 DOM 渲染完再调”：

anything-to-html

将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。

下载

React/Vue 组件测试中，必须等组件挂载、数据加载、副作用（如 useEffect）执行完毕后再调 axe.run()

Cypress 示例：

cy.get('#main-content').then(() => {<br>  cy.injectAxe();<br>  cy.checkA11y('#main-content', {<br>    runOnly: { type: 'tag', values: ['wcag2aa'] }<br>  });<br>});

Jest + JSDOM 场景下，global.document 和 global.window 必须由 JSDOM 实例提供，且不能复用旧实例（否则缓存导致结果不准）
错误示范：await axe.run() 在组件未 mount 前就执行 → 返回空结果，不代表合规，只代表没扫到东西

`axe.run()` 的 `runOnly` 参数决定查什么，别盲目全量扫

默认跑全部规则（57+ 条），但实际项目中应按需收缩范围，兼顾速度与重点：

WCAG 2.1 AA 合规：用 { runOnly: { type: 'tag', values: ['wcag2aa'] } }
只关注高影响问题：{ runOnly: { type: 'tag', values: ['serious', 'critical'] } }（注意：axe 本身不定义 serious 标签，这是自定义规则集才有的，原生只认 wcag2a/wcag2aa）
排除已知误报项（如某些富文本编辑器内部 iframe）：{ exclude: [['iframe[src*="ckeditor"]']] }
性能提示：扫描整个 document 比限定 selector（如 #app）慢 3–5 倍，尤其含大量表格或列表时