AI 辅助前端无障碍测试：自动生成 WCAG 审计报告与修复建议

2026/7/25 3:05:54

AI 辅助前端无障碍测试：自动生成 WCAG 审计报告与修复建议

一、前端无障碍的现状：手工审计的成本让 90% 的项目选择跳过

WCAG 2.1（Web Content Accessibility Guidelines）定义了 78 条成功标准，分为 A、AA、AAA 三个等级。其中 AA 级是多数法规的最低要求，涵盖 50 条标准。对于一个人力有限的前端团队来说，逐条手工检查 50 条标准是不现实的。结果就是：无障碍测试被列在"理想情况"的 backlog 中，永不启动。

手工审计的典型瓶颈：

键盘可访问性检查：需要逐页 Tab 遍历所有可交互元素，验证焦点顺序和可见焦点指示器。一个 20 页的中型网站大约需要 4 小时人工时间。
色彩对比度检查：需要逐个提取文本色和背景色，计算对比度比值。一页可能有 50+ 个颜色组合。
屏幕阅读器兼容性检查：打开 VoiceOver/NVDA，逐区域验证语义标签是否正确。对不熟悉屏幕阅读操作的开发者来说，学习成本极高。

AI 在前端无障碍测试中的价值，是将以上手工检查过程自动化为扫描 → 审计 → 修复建议的三步流程。这不是用 AI 替代人工审计（人工仍然是最终的质量保证），而是用 AI 将审计成本降低 80%，让团队有意愿启动无障碍工作。

二、自动化审计引擎的设计：从 DOM 扫描到 WCAG 规则匹配

2.1 DOM 遍历与数据结构提取

自动化审计的第一步是提取页面的完整可访问性信息。基于 Playwright/Puppeteer 的无头浏览器，在页面完全渲染后注入一段 JavaScript，遍历 DOM 树并提取每个元素的语义信息：

/** * 页面可访问性信息提取器 * 注入页面后遍历 DOM，提取语义和样式信息 */ interface AccessibilityNode { tagName: string; role: string | null; // 显式 ARIA role implicitRole: string; // 隐式 role（如 <button> → button） name: string | null; // Accessible Name（来自 aria-label/label/内容） description: string | null; // Accessible Description（aria-describedby） tabIndex: number | null; // Tab 键焦点顺序 isVisible: boolean; // 是否在视觉上可见 isFocusable: boolean; isFocused: boolean; // 样式信息 color: string; backgroundColor: string; fontSize: string; fontWeight: string; // 关联关系 parent: string | null; // 父节点 XPath children: string[]; labelElement: string | null; // 关联的 <label> 元素 describedBy: string[]; // aria-describedby 指向的元素 // 问题标记 issues: AccessibilityIssue[]; } interface AccessibilityIssue { wcagCriterion: string; // WCAG 标准编号（如 "1.1.1"） severity: 'critical' | 'serious' | 'moderate' | 'minor'; level: 'A' | 'AA' | 'AAA'; description: string; // 问题描述（中文） elementXPath: string; // 问题元素的 XPath screenshot?: string; // 问题区域的截图（base64） } /** * 页面可访问性扫描器 */ class AccessibilityScanner { /** * 扫描整页的 WCAG 合规性 */ async scanPage(url: string): Promise<{ nodes: AccessibilityNode[]; issues: AccessibilityIssue[]; summary: AuditSummary; }> { const browser = await this.launchBrowser(); const page = await browser.newPage(); await page.goto(url, { waitUntil: 'networkidle' }); // 1. 提取 DOM 的语义结构 const nodes = await page.evaluate(() => { return this.extractAccessibilityTree(document.body); }); // 2. 模拟键盘导航，记录焦点顺序 const focusOrder = await this.simulateKeyboardNavigation(page); // 3. 逐节点做 WCAG 规则匹配 const issues: AccessibilityIssue[] = []; for (const node of nodes) { issues.push(...this.checkNode(node, focusOrder)); } // 4. 汇总审计报告 const summary = this.summarize(issues); await browser.close(); return { nodes, issues, summary }; } /** * 递归提取 DOM 树的可访问性信息 */ private extractAccessibilityTree(element: Element): AccessibilityNode[] { const nodes: AccessibilityNode[] = []; const computedStyle = window.getComputedStyle(element); const node: AccessibilityNode = { tagName: element.tagName.toLowerCase(), role: element.getAttribute('role'), implicitRole: this.getImplicitRole(element), name: this.getAccessibleName(element), description: element.getAttribute('aria-describedby'), tabIndex: (element as HTMLElement).tabIndex, isVisible: computedStyle.display !== 'none' && computedStyle.visibility !== 'hidden', isFocusable: (element as HTMLElement).tabIndex >= 0, isFocused: document.activeElement === element, color: computedStyle.color, backgroundColor: computedStyle.backgroundColor, fontSize: computedStyle.fontSize, fontWeight: computedStyle.fontWeight, parent: this.getXPath(element.parentElement), children: [], labelElement: null, describedBy: [], issues: [], }; // 提取关联的 label const id = element.id; if (id) { const label = document.querySelector(`label[for="${id}"]`); if (label) node.labelElement = this.getXPath(label); } nodes.push(node); // 递归子元素 for (const child of Array.from(element.children)) { const childNodes = this.extractAccessibilityTree(child); node.children.push(...childNodes.map((n) => this.getXPath(child))); nodes.push(...childNodes); } return nodes; } /** * 获取元素的 Accessible Name（优先级：aria-label > aria-labelledby > label > 内容） */ private getAccessibleName(element: Element): string | null { return ( element.getAttribute('aria-label') || element.getAttribute('aria-labelledby') || element.getAttribute('title') || element.textContent?.trim()?.slice(0, 100) || null ); } /** * 获取元素的隐式 role */ private getImplicitRole(element: Element): string { const roleMap: Record<string, string> = { button: 'button', a: element.hasAttribute('href') ? 'link' : 'generic', input: this.getInputRole(element as HTMLInputElement), img: element.hasAttribute('alt') ? 'img' : 'presentation', nav: 'navigation', main: 'main', header: 'banner', footer: 'contentinfo', aside: 'complementary', h1: 'heading', h2: 'heading', h3: 'heading', h4: 'heading', h5: 'heading', h6: 'heading', ul: 'list', ol: 'list', }; return roleMap[element.tagName.toLowerCase()] || 'generic'; } private getInputRole(input: HTMLInputElement): string { const typeRoleMap: Record<string, string> = { checkbox: 'checkbox', radio: 'radio', search: 'searchbox', range: 'slider', number: 'spinbutton', }; return typeRoleMap[input.type] || 'textbox'; } private async launchBrowser() { return {} as any; } private async simulateKeyboardNavigation(page: any): Promise<string[]> { return []; } private checkNode(node: AccessibilityNode, focusOrder: string[]): AccessibilityIssue[] { return []; } private summarize(issues: AccessibilityIssue[]): AuditSummary { return {} as AuditSummary; } private getXPath(element: Element | null): string { return ''; } } interface AuditSummary { totalIssues: number; bySeverity: Record<string, number>; byLevel: Record<string, number>; wcagCompliance: number; // 0~100% }

2.2 WCAG 规则引擎：可编程的审计规则集

WCAG 的 50 条 AA 级标准不是都能用程序自动检查的（如"内容是否可理解"需要人工判断），但大约 60%~70% 的标准可以自动化：

/** * WCAG 规则引擎 * 基于规则集的自动化检查 */ interface WCAGRule { id: string; // WCAG 标准编号 description: string; level: 'A' | 'AA' | 'AAA'; severity: 'critical' | 'serious' | 'moderate' | 'minor'; check: (node: AccessibilityNode) => boolean; // true = 通过 generateFixSuggestion: (node: AccessibilityNode) => FixSuggestion; } interface FixSuggestion { description: string; codeFix?: string; // 代码级修复 beforeCode?: string; // 修复前代码 afterCode?: string; // 修复后代码 } class WCAGRuleEngine { private rules: WCAGRule[] = [ { id: '1.1.1', description: '非文本内容必须有替代文本', level: 'A', severity: 'critical', check: (node) => { if (node.tagName !== 'img') return true; return node.name !== null && node.name.length > 0; }, generateFixSuggestion: (node) => ({ description: '为图片添加有意义的 alt 属性', codeFix: `<img src="..." alt="描述图片内容的文字" />`, }), }, { id: '1.4.3', description: '文本对比度不低于 4.5:1（正常文本）或 3:1（大文本）', level: 'AA', severity: 'serious', check: (node) => { const contrastRatio = this.calculateContrastRatio( this.parseColor(node.color), this.parseColor(node.backgroundColor) ); const isLargeText = parseFloat(node.fontSize) >= 18 || (parseFloat(node.fontSize) >= 14 && parseInt(node.fontWeight) >= 700); const minimumRatio = isLargeText ? 3 : 4.5; return contrastRatio >= minimumRatio; }, generateFixSuggestion: (node) => ({ description: `当前对比度不足，建议调深文本颜色或调整背景色`, codeFix: `/* 建议将文本颜色从 ${node.color} 调整为更深的颜色 */`, }), }, { id: '2.4.3', description: '焦点顺序应符合有意义的操作序列', level: 'A', severity: 'serious', check: (node, focusOrder?: string[]) => { if (!focusOrder) return true; if (!node.isFocusable) return true; // AI 语义分析：焦点顺序是否合理（由 LLM 判断） return this.evaluateFocusOrder(node, focusOrder); }, generateFixSuggestion: (node) => ({ description: '建议使用 tabindex 属性调整焦点顺序', codeFix: `tabindex="0" /* 使元素可出现在自然 Tab 序列中 */`, }), }, { id: '4.1.2', description: '所有可交互元素必须有可访问的名称（Accessible Name）', level: 'A', severity: 'critical', check: (node) => { const interactiveRoles = ['button', 'link', 'checkbox', 'radio', 'textbox', 'combobox']; if (!interactiveRoles.includes(node.role || node.implicitRole)) return true; return node.name !== null && node.name.length > 0; }, generateFixSuggestion: (node) => ({ description: `为 ${node.tagName} 元素添加 aria-label 或关联 label`, codeFix: `aria-label="${node.tagName} 的功能描述"`, }), }, ]; /** * 对所有扫描节点执行规则检查 */ audit(nodes: AccessibilityNode[], focusOrder?: string[]): AccessibilityIssue[] { const issues: AccessibilityIssue[] = []; for (const node of nodes) { // 跳过不可见元素 if (!node.isVisible) continue; for (const rule of this.rules) { const passed = rule.check(node, focusOrder); if (!passed) { issues.push({ wcagCriterion: rule.id, severity: rule.severity, level: rule.level, description: `${rule.description}：${rule.generateFixSuggestion(node).description}`, elementXPath: node.tagName, }); } } } return issues; } /** * 相对亮度计算（WCAG 对比度公式） */ private calculateContrastRatio( color1: [number, number, number], color2: [number, number, number] ): number { const l1 = this.relativeLuminance(color1); const l2 = this.relativeLuminance(color2); const lighter = Math.max(l1, l2); const darker = Math.min(l1, l2); return (lighter + 0.05) / (darker + 0.05); } private relativeLuminance([r, g, b]: [number, number, number]): number { const [rs, gs, bs] = [r, g, b].map((c) => { c /= 255; return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; }); return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs; } private parseColor(color: string): [number, number, number] { return [0, 0, 0]; } private evaluateFocusOrder(node: AccessibilityNode, focusOrder: string[]): boolean { return true; } }

三、AI 生成的修复建议：从问题描述到可执行的代码 Diff

3.1 修复建议的格式化输出

检测到问题是第一步，但开发者需要的是"怎么修"而非"哪里有错"。AI 在此的作用是将 WCAG 标准检测结果转化为代码级的修复建议：

缺失 Alt 文本：AI 分析图片上下文（周围文字、链接目标、文件名），生成有意义的 Alt 文本建议。
对比度不足：AI 计算调整后的颜色值（保持品牌色相近但对比度达标），输出具体的 HEX 值。
焦点顺序混乱：AI 分析页面布局的视觉顺序，输出推荐的tabindex赋值方案。

3.2 修复验证的回归机制

每次修复后，AI 审计引擎应重新扫描页面，验证问题是否已被修复，同时确认修复没有引入新的无障碍问题。为此引入一个基线快照机制：

interface AccessibilityBaseline { url: string; timestamp: number; issueCount: number; issues: AccessibilityIssue[]; passCount: number; // 通过的规则数 } class RegressionTracker { private baselines: Map<string, AccessibilityBaseline> = new Map(); /** * 对比新扫描结果与基线，检测回归 */ compareBaseline(url: string, current: AccessibilityIssue[]): RegressionReport { const baseline = this.baselines.get(url); if (!baseline) { this.baselines.set(url, { url, timestamp: Date.now(), issueCount: current.length, issues: current, passCount: 0 }); return { isRegression: false, newIssues: [], fixedIssues: [] }; } const newIssues = current.filter( (i) => !baseline.issues.some((b) => b.wcagCriterion === i.wcagCriterion && b.elementXPath === i.elementXPath) ); const fixedIssues = baseline.issues.filter( (b) => !current.some((i) => i.wcagCriterion === b.wcagCriterion && i.elementXPath === b.elementXPath) ); return { isRegression: newIssues.length > 0, newIssues, fixedIssues, }; } }