AI 驱动的无障碍审查ARIA 角色、焦点管理和色彩对比的自动化检测一、无障碍审查的现状人工审计的困境与自动化突破口前端无障碍Accessibility, a11y的审查工作长期处于听天由命的状态。大多数团队的流程是产品上线前找一个对此有兴趣的开发者手动跑一遍 axe-core 或 Lighthouse然后发现大量问题再在改不完和先上线之间做出妥协。这种模式的根本问题不是缺乏工具而是工具的使用时机和使用频率不对。Lighthouse 和 axe-core 这类规则引擎只能检测约 30% 的 WCAG 标准——主要是语法层面的问题如是否缺少 alt 属性、是否存在重复的 ID。对于语义理解型问题——ARIA 角色是否正确映射、焦点管理是否符合用户预期、色彩对比是否在交互态下依然达标——规则引擎力不从心。AI 在无障碍审查中的核心价值正在于此补全规则引擎无法覆盖的语义理解缺口。LLM 可以理解一个自定义下拉组件的 ARIA 角色是否与交互行为一致可以判断焦点流转路径是否合理可以分析动态样式在不同状态下的色彩对比变化。flowchart LR A[前端代码] -- B[静态规则引擎] A -- C[AI 语义分析] B -- D[语法层面检测br/约占 WCAG 30%] C -- E[语义层面检测br/约占 WCAG 60%] D -- F{自动化覆盖} E -- F F -- G[约 10% 仍需人工审查br/如动画节奏、内容语序] style B fill:#e0e0e0,stroke:#999 style C fill:#4CAF50,stroke:#333,color:#fff style G fill:#FF9800,stroke:#333二、ARIA 角色的语义一致性检测ARIAAccessible Rich Internet Applications规范定义了一组角色、状态和属性用于向辅助技术描述自定义 UI 组件的语义。但是ARIA 的使用极易出错角色声明与实际的交互行为不一致、必需的子角色缺失、属性值超出合法范围等。规则引擎能检测的范围静态规则可以检测以下显式错误角色值是否在合法枚举中某个角色是否缺少必需的属性属性值格式是否符合预期但无法检测以下语义问题声明了rolelistbox的实现是否真的提供了列表选择交互aria-expanded的状态切换是否与实际展开/折叠行为同步自定义 Tab 组件的aria-selected是否与活跃的 Tab 一致AI 检测的 Prompt 工程以下是一段用于 AI 审查的 Prompt 模板聚焦于 ARIA 角色的语义一致性/** * AI 无障碍审查ARIA 角色语义一致性检测 Prompt * 该 Prompt 用于提交给 LLM检测代码中 ARIA 角色的使用是否正确 */ interface AriaReviewResult { id: string; severity: critical | serious | moderate | minor; category: aria-role | aria-property | focus | contrast; element: string; // 问题所在的 DOM 元素描述 description: string; // 问题描述 wcagCriteria: string[]; // 违反的 WCAG 标准编号 suggestion: string; // 修复建议 codeFix: string; // 修复代码示例 } class AriaRoleReviewer { private promptTemplate: string; constructor() { // 审查 Prompt 模板 // 关键明确审查维度、输出格式和判断标准 this.promptTemplate [ 你是一个前端无障碍审查专家。请审查以下组件的 ARIA 角色使用重点关注, , 1. **角色与交互的匹配性**, - 声明 role 是否与用户可执行的交互操作一致, - 例如声明 rolelistbox 但不支持键盘选择则判定为错误, , 2. **角色层级关系**, - 需要父角色的组件是否正确嵌套, - 例如roleoption 必须在 rolelistbox 或 rolegroup 内, , 3. **状态属性的同步性**, - aria-expanded、aria-selected 等属性, 是否在状态变化时同步更新, - 检查事件处理器中是否包含对应的属性更新逻辑, , 4. **aria-label 与可见文本的一致性**, - 当元素有可见文本时aria-label 不应与其冲突, - 当 aria-label 缺失时检查是否有其他文本传递机制, , 请按以下 JSON 格式输出审查结果仅输出 JSON不要其他内容, JSON.stringify( { findings: [ { severity: critical|serious|moderate|minor, element: 包含行号的代码引用, description: 简洁的问题描述≤ 50 字, wcagCriteria: [4.1.2], suggestion: 具体的修复建议, codeFix: 修复后的代码片段, }, ], summary: { totalIssues: 0, criticalCount: 0, overallAssessment: pass|needs-work|fail, }, }, null, 2 ), , 开始审查。, ].join(\n); } /** * 构建审查请求 * param componentCode 待审查的组件代码 * param componentDescription 组件的功能描述帮助 LLM 理解上下文 */ buildReviewRequest( componentCode: string, componentDescription: string ): string { return [ 组件描述${componentDescription}, , tsx, componentCode, , , this.promptTemplate, ].join(\n); } }典型检测案例自定义下拉组件/** * 问题组件自定义下拉选择器 * 该组件存在多处无障碍缺陷需要 AI 审查识别 */ import { useState, useRef, useEffect, type KeyboardEvent } from react; interface DropdownProps { options: string[]; value: string; onChange: (value: string) void; label: string; } // 正确实现完整的 ARIA 角色、焦点管理和键盘交互 function AccessibleDropdown({ options, value, onChange, label }: DropdownProps) { const [isOpen, setIsOpen] useState(false); const [focusedIndex, setFocusedIndex] useState(-1); const listboxRef useRefHTMLUListElement(null); const buttonRef useRefHTMLButtonElement(null); const optionRefs useRef(HTMLLIElement | null)[]([]); // 展开时管理焦点将焦点移到当前选中项或第一项 useEffect(() { if (!isOpen) { setFocusedIndex(-1); return; } const currentIndex options.indexOf(value); const targetIndex currentIndex 0 ? currentIndex : 0; setFocusedIndex(targetIndex); // 延迟聚焦确保 DOM 已更新 const timer requestAnimationFrame(() { optionRefs.current[targetIndex]?.focus(); }); return () cancelAnimationFrame(timer); }, [isOpen, options, value]); /** * 键盘导航处理 * 实现完整的 ARIA listbox 键盘交互模式 * - ArrowDown/ArrowUp: 在选项间移动焦点 * - Enter/Space: 选择当前聚焦项并关闭列表 * - Escape: 关闭列表焦点返回触发按钮 * - Home/End: 跳转到第一个/最后一个选项 */ const handleListboxKeyDown (event: KeyboardEventHTMLUListElement) { switch (event.key) { case ArrowDown: { event.preventDefault(); const nextIndex Math.min(focusedIndex 1, options.length - 1); setFocusedIndex(nextIndex); optionRefs.current[nextIndex]?.focus(); break; } case ArrowUp: { event.preventDefault(); const prevIndex Math.max(focusedIndex - 1, 0); setFocusedIndex(prevIndex); optionRefs.current[prevIndex]?.focus(); break; } case Home: { event.preventDefault(); setFocusedIndex(0); optionRefs.current[0]?.focus(); break; } case End: { event.preventDefault(); const lastIndex options.length - 1; setFocusedIndex(lastIndex); optionRefs.current[lastIndex]?.focus(); break; } case Enter: case : { event.preventDefault(); if (focusedIndex 0) { selectOption(options[focusedIndex]); } break; } case Escape: { event.preventDefault(); setIsOpen(false); // 焦点返回触发按钮 buttonRef.current?.focus(); break; } } }; const selectOption (option: string) { onChange(option); setIsOpen(false); buttonRef.current?.focus(); }; // 生成唯一 ID 用于 aria 属性关联 const listboxId dropdown-listbox-${label.replace(/\s/g, -).toLowerCase()}; return ( div classNamedropdown-container {/* 标签与触发按钮的关联 */} label id{${listboxId}-label} classNamedropdown-label {label} /label {/* 组合框模式button 作为展开触发器 */} button ref{buttonRef} typebutton classNamedropdown-trigger aria-haspopuplistbox aria-expanded{isOpen} aria-labelledby{${listboxId}-label ${listboxId}-button} id{${listboxId}-button} onClick{() setIsOpen((prev) !prev)} {value || 请选择} span aria-hiddentrue classNamearrow {isOpen ? ▲ : ▼} /span /button {/* 列表弹出层仅在展开时渲染 */} {isOpen ( ul ref{listboxRef} rolelistbox id{listboxId} tabIndex{-1} aria-labelledby{${listboxId}-label} aria-activedescendant{ focusedIndex 0 ? ${listboxId}-option-${focusedIndex} : undefined } onKeyDown{handleListboxKeyDown} classNamedropdown-listbox {options.map((option, index) ( li key{option} ref{(el) { optionRefs.current[index] el; }} roleoption id{${listboxId}-option-${index}} aria-selected{option value} // 选项不可聚焦焦点由 listbox 通过 aria-activedescendant 管理 tabIndex{-1} onClick{() selectOption(option)} className{dropdown-option ${ index focusedIndex ? focused : }} {option} {option value ( span aria-hiddentrue classNamecheckmark ✓ /span )} /li ))} /ul )} /div ); } export default AccessibleDropdown;三、焦点管理的自动化检测焦点管理是无障碍审查中最容易被忽视的维度。SPA单页应用中的路由切换、模态框的开关、动态内容的加载都需要显式的焦点管理。而传统规则引擎完全无法检测这类运行时行为。焦点管理的审查流程图flowchart TD A[组件代码分析] -- B{识别交互模式} B -- C[模态框/对话框] B -- D[路由切换] B -- E[动态内容加载] B -- F[表单提交/验证] C -- G{焦点陷阱检查} G --|Tab 无法在模态框内循环| H[缺少焦点陷阱] G --|关闭后焦点未返回| I[焦点归位缺失] D -- J{页面标题检查} J --|标题未更新| K[缺少 document.title 更新] J --|焦点位置检查| L{焦点是否在 body 顶部?} E -- M{通知机制检查} M --|无 aria-live 区域| N[缺少动态内容通知] H -- O[生成修复建议] I -- O K -- O L -- O N -- O焦点陷阱Focus Trap的代码审查/** * 模态框焦点陷阱实现 * AI 审查需要检查 * 1. 打开时焦点是否移入模态框 * 2. Tab 键是否在模态框内循环 * 3. 关闭时焦点是否返回触发元素 * 4. Escape 键是否可关闭 */ import { useEffect, useRef, useState, type ReactNode } from react; interface ModalProps { isOpen: boolean; onClose: () void; title: string; children: ReactNode; } function AccessibleModal({ isOpen, onClose, title, children }: ModalProps) { const modalRef useRefHTMLDivElement(null); const previousFocusRef useRefHTMLElement | null(null); // 管理焦点陷阱内的可聚焦元素 const getFocusableElements (): HTMLElement[] { if (!modalRef.current) return []; const selector [ a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex-1]), ].join(,); return Array.from( modalRef.current.querySelectorAllHTMLElement(selector) ); }; useEffect(() { if (!isOpen) { // 关闭时恢复焦点 previousFocusRef.current?.focus(); previousFocusRef.current null; return; } // 保存打开前焦点元素 previousFocusRef.current document.activeElement as HTMLElement; // 延迟将焦点移入模态框确保 DOM 已渲染 const timer requestAnimationFrame(() { const focusable getFocusableElements(); if (focusable.length 0) { focusable[0].focus(); } else { modalRef.current?.focus(); } }); // 全局键盘事件焦点陷阱 Escape 关闭 const handleKeyDown (event: KeyboardEvent) { if (event.key Escape) { event.preventDefault(); onClose(); return; } if (event.key ! Tab) return; const focusable getFocusableElements(); if (focusable.length 0) { event.preventDefault(); return; } const firstElement focusable[0]; const lastElement focusable[focusable.length - 1]; if (event.shiftKey) { // Shift Tab如果焦点在第一个元素跳转到最后一个 if (document.activeElement firstElement) { event.preventDefault(); lastElement.focus(); } } else { // Tab如果焦点在最后一个元素跳转到第一个 if (document.activeElement lastElement) { event.preventDefault(); firstElement.focus(); } } }; document.addEventListener(keydown, handleKeyDown); return () { cancelAnimationFrame(timer); document.removeEventListener(keydown, handleKeyDown); }; }, [isOpen, onClose]); // 阻止背景滚动 useEffect(() { if (isOpen) { const originalOverflow document.body.style.overflow; document.body.style.overflow hidden; return () { document.body.style.overflow originalOverflow; }; } }, [isOpen]); if (!isOpen) return null; return ( div classNamemodal-overlay onClick{(e) { // 点击遮罩层关闭但点击内容区域不关闭 if (e.target e.currentTarget) { onClose(); } }} div ref{modalRef} roledialog aria-modaltrue aria-labelledbymodal-title tabIndex{-1} // 允许 div 接收焦点 classNamemodal-content h2 idmodal-title classNamemodal-title {title} /h2 div classNamemodal-body{children}/div button typebutton classNamemodal-close aria-label关闭对话框 onClick{onClose} ✕ /button /div /div ); } export default AccessibleModal;四、色彩对比的自动化检测色彩对比和 ARIA 不同它是一个视觉 计算的问题。规则引擎可以检测样式表中的静态颜色值是否满足 WCAG 2.1 的对比度标准普通文本 4.5:1大文本 3:1但面对以下情况则无能为力动态主题切换后的对比度变化、半透明叠加层的组合对比度、hover/focus/active 等交互态的对比度。WCAG 对比度标准速查文本类型AA 级标准AAA 级标准普通文本 18pt4.5:17:1大文本≥ 18pt 或 ≥ 14pt 加粗3:14.5:1UI 组件和图形对象3:1-纯装饰性内容无要求无要求AI 对动态样式的对比度分析AI 审查可以结合代码逻辑推断当 CSS 变量发生变化时如暗色模式切换前景色和背景色的组合是否在所有状态下都能满足对比度要求。审查 Prompt 可以要求 LLM 列出所有可能的颜色状态组合并逐一计算对比度。/** * 色彩对比度计算工具 * 用于 AI 审查结果中的对比度验证 */ interface ContrastResult { foreground: string; // 前景色十六进制 background: string; // 背景色十六进制 ratio: number; // 对比度比值 meetsAA: boolean; // 是否满足 AA 级 meetsAAA: boolean; // 是否满足 AAA 级 context: string; // 使用场景描述 } /** * 计算两个 sRGB 颜色的相对亮度 * 遵循 WCAG 2.1 规范中的相对亮度计算 */ function relativeLuminance(hexColor: string): number { // 将十六进制颜色转换为 RGB 分量0-255 const r parseInt(hexColor.slice(1, 3), 16); const g parseInt(hexColor.slice(3, 5), 16); const b parseInt(hexColor.slice(5, 7), 16); // 将 sRGB 值线性化 // sRGB 到线性 RGB 的转换公式来自 WCAG 2.1 附录 const linearize (channel: number): number { const s channel / 255; return s 0.03928 ? s / 12.92 : Math.pow((s 0.055) / 1.055, 2.4); }; // 相对亮度公式L 0.2126 * R 0.7152 * G 0.0722 * B return ( 0.2126 * linearize(r) 0.7152 * linearize(g) 0.0722 * linearize(b) ); } /** * 计算两个颜色之间的对比度比值 * 公式(L1 0.05) / (L2 0.05)其中 L1 为较亮颜色的相对亮度 */ function contrastRatio(color1: string, color2: string): number { const lum1 relativeLuminance(color1); const lum2 relativeLuminance(color2); const lighter Math.max(lum1, lum2); const darker Math.min(lum1, lum2); return Number(((lighter 0.05) / (darker 0.05)).toFixed(2)); } /** * 检查一组颜色组合是否满足 WCAG 对比度要求 */ function evaluateContrast( pairs: Array{ foreground: string; background: string; context: string; // 如 正文、标题、链接悬停态 isLargeText: boolean; // 是否为大文本≥ 18pt } ): ContrastResult[] { return pairs.map((pair) { const ratio contrastRatio(pair.foreground, pair.background); const aaThreshold pair.isLargeText ? 3 : 4.5; const aaaThreshold pair.isLargeText ? 4.5 : 7; return { foreground: pair.foreground, background: pair.background, ratio, meetsAA: ratio aaThreshold, meetsAAA: ratio aaaThreshold, context: pair.context, }; }); } // 使用示例审查常见的色彩组合 // AI 审查时可以将此结果作为参考依据 const testCombinations [ { foreground: #666666, background: #FFFFFF, context: 次要文本在白色背景, isLargeText: false }, { foreground: #333333, background: #F5F5F5, context: 正文在浅灰背景, isLargeText: false }, { foreground: #1A73E8, background: #FFFFFF, context: 链接文本在白色背景, isLargeText: false }, ]; const results evaluateContrast(testCombinations); // #666 在白色上的对比度约为 5.19:1满足 AA 但不满足 AAA // #333 在浅灰上的对比度约为 8.58:1满足 AAA // 链接蓝在白色上的对比度约为 4.59:1刚好满足 AA五、总结AI 驱动的无障碍审查将检测能力从 30% 的语法层面扩展到 90% 以上的语义层面。在 ARIA 角色检测中AI 可以判断角色声明与实际交互行为的语义一致性在焦点管理中AI 可以识别焦点陷阱、焦点归位和动态内容通知等运行时模式在色彩对比中AI 可以分析动态主题和交互状态下的对比度变化。但需要明确的是AI 审查是规则引擎的补充而非替代。三层审查体系的推荐架构是静态规则引擎axe-core做首层的确定性检测AI 审查做第二层的语义理解检测人工审查做第三层的定性判断。各层各司其职才能构成完整的无障碍质量保障体系。