qt-widget-accessibility-audit

用途

qt-widget-accessibility-audit 用于审计 Qt Widget 和 Qt Quick 应用的无障碍合规性。它借助 QAccessible 接口与平台无障碍 API，检查 QAccessible 接口实现、键盘导航、屏幕阅读器兼容性以及 WCAG 指南的遵循情况。

主要能力

审计 QAccessible 接口实现
检查键盘导航与焦点处理
验证屏幕阅读器兼容性
校验高对比度与颜色可访问性
检查文本缩放支持
审查可访问名称与描述
使用平台无障碍工具进行测试
生成无障碍合规报告

使用方式

输入参数（Input Schema）为对象，包含：

projectPath（字符串，必填）：Qt 项目路径。
auditLevel（枚举，默认 wcag-aa）：可选 basic、wcag-a、wcag-aa、wcag-aaa。
targetPlatform（枚举）：可选 windows、macos、linux，用于聚焦无障碍检查的平台。
checkCategories（数组，默认 ["keyboard", "screen-reader", "visual", "focus", "labels"]）：可选 keyboard、screen-reader、visual、focus、labels、navigation。
includeQml（布尔，默认 true）。

输出参数（Output Schema）为对象，包含：

success（布尔，必填）
complianceLevel（枚举）：none、wcag-a、wcag-aa、wcag-aaa
score（数字）：无障碍评分 0-100
issues（数组，必填）：每项包含 id、severity（critical、major、minor）、category、wcagCriteria、description、file、widget、recommendation
recommendations（字符串数组）

检查内容示例

QAccessible 接口：检查控件是否具有可访问名称（accessibleName() 或 accessibleDescription() 非空）；自定义控件是否实现 QAccessibleInterface。

键盘导航：检查所有交互控件是否可聚焦（focusPolicy 不为 Qt::NoFocus）；检查 Tab 顺序是否逻辑合理（从左到右、从上到下）。

视觉无障碍：检查颜色对比度是否充足（WCAG AA 普通文本对比度 ≥ 4.5）；检查文本是否可缩放（建议使用点大小而非像素大小）。

常见问题与修复示例

缺失可访问名称：为按钮设置 setAccessibleName() 与 setAccessibleDescription()。

不可聚焦控件：将 setFocusPolicy(Qt::NoFocus) 改为 Qt::StrongFocus。

对比度不足：将低对比度样式（如 color: #888888; background: white;）改为符合 WCAG AA 的对比度（如 color: #595959; background: white;）。

QML 无障碍：为 Button 设置 Accessible.name、Accessible.description、Accessible.role，并处理 Keys.onReturnPressed、Keys.onEnterPressed；为 Image 设置 Accessible.name 与 Accessible.role；为焦点指示器设置边框颜色随 activeFocus 变化。

平台工具集成

Windows：使用 Windows Narrator 与 Accessibility Insights 工具验证 UI Automation 树。
macOS：使用 VoiceOver 验证，检查 NSAccessibility 合规性。
Linux：使用 Orca 屏幕阅读器与 Accerciser 检查 AT-SPI 树。

WCAG 指南映射

1.1.1 非文本内容：为图像/图标设置 setAccessibleName()
1.4.3 对比度：使用对比度充足的 QPalette
2.1.1 键盘：setFocusPolicy()、按键处理
2.4.3 焦点顺序：setTabOrder()
2.4.7 焦点可见：样式表中的焦点指示器
4.1.2 名称、角色、值：QAccessible 接口

最佳实践

设置可访问名称：所有交互控件都需要名称
使用语义角色：正确的 QAccessible::Role
支持键盘：所有功能均可通过键盘访问
可见焦点：清晰的焦点指示器
不依赖颜色：不要仅靠颜色传达信息
可缩放文本：使用点大小，支持缩放

限制

资料未提供该技能的收费、价格、具体安装命令、运行环境依赖或性能指标等信息。

技能介绍

用途