SuperAPI AI 工具集

avalonia-pro-max/accessibility

编程与开发

查看项目

更新于 11-03 16:15

技能介绍

该技能面向 Avalonia 应用的无障碍(Accessibility)添加与审计,目标为 WCAG 2.2 AA,并兼顾 Windows UI Automation、macOS NSAccessibility 与 Linux AT-SPI。

用途与覆盖范围:为控件补充可被辅助技术识别的名称、说明与角色;组织焦点顺序与键盘遍历;保证可见焦点指示;校验颜色对比度;为表单提供可访问的校验反馈;支持高对比度、动态文字缩放、触摸目标与减少动效。

主要能力:

  1. AutomationProperties:提供 Name、HelpText、AcceleratorKey、AccessibilityView、IsRequiredForForm、LabeledBy、LiveSetting、ItemStatus、AutomationId 等附加属性的使用方式;图标按钮需 Name,装饰元素设 AccessibilityView=Raw,可见标签与输入用 LabeledBy 关联。
  2. 焦点指示:保留 FluentTheme 焦点环,自定义 ControlTheme 时在 :focus-visible 上重加边框,最小 2px、对比度不低于 3:1;:focus-visible 仅在键盘获得焦点时生效,同时保留 :focus 可见提示。
  3. 键盘导航:Tab 顺序默认随逻辑树,可用 TabIndex、IsTabStop 调整;用 KeyboardNavigation.TabNavigation(Continue/Local/Cycle/Once/None)与 DirectionalNavigation 控制面板内遍历与方向键行为;提供助记符(_File)与 KeyBindings、HotKey 快捷键,并同时给出 Ctrl 与 macOS Cmd 组合。
  4. 颜色对比:正文 4.5:1,大号文本 3:1,UI 组件(图标、焦点环、边框)3:1;明暗主题均需校验,并指出 TextMutedBrush、Accent 文本、禁用按钮透明度等常见失败点。状态不能仅靠颜色表达,应颜色+图标+文字并用。
  5. 表单校验:LabeledBy 关联标签、IsRequiredForForm 标记必填,错误文本使用 LiveSetting=Polite 作为实时区域;提交失败时将焦点移到第一个无效字段(c.Focus(NavigationMethod.Tab))。
  6. 实时区域:状态文本用 LiveSetting,Polite 等待空闲播报,Assertive 仅用于错误等重要信息。
  7. 缩放与高对比度:避免视图内固定 FontSize,改用资源与缩放因子;避免文本容器固定高度、无提示的单行截断;测试 100%/150%/200% 系统缩放。Windows 高对比度下 FluentTheme 可适配多数颜色,自定义控件使用系统画刷或注册 HighContrast 主题字典。
  8. 触摸目标:桌面最小 36×36 px,触摸/移动 44×44 px,可通过 Padding 扩大命中区,相邻目标间距不小于 8 px。
  9. 减少动效:动画须提供零时长回退(引向 avalonia-pro-max/motion)。

版本差异(资料明确给出):12.0+ 提供 Linux AT-SPI2 后端(Orca),11.x 无该后端,Linux 屏幕阅读器支持不可用;12.0+ 校验错误通过自动化暴露,TextBox.PlaceholderText 可被屏幕阅读器读取;12.0+ 移除 TopLevel.PlatformSettings,改用 visual.GetPlatformSettings(),11.x 使用 TopLevel.GetTopLevel(this)?.PlatformSettings。12.0+ 新增 Focus Traversal API(IFocusManager 的 FindNextElement、TryMoveFocus、FindFirstFocusableElement,替代 KeyboardNavigationHandler.GetNext;支持可取消的焦点变更;GotFocus/LostFocus 使用 FocusChangedEventArgs),11.x 使用 KeyboardNavigationHandler 与 GotFocusEventArgs。

使用方式:依据 XAML 示例在视图中添加 AutomationProperties 与键盘设置,替换控件主题时重新加入焦点环样式,按对比度与 DPI 要求逐项检查。

测试清单:用 Tab 遍历每个界面确认所有控件可达可操作;启用 Windows Narrator、macOS VoiceOver 或 Orca(Linux 需 Avalonia 12.0+)朗读主要界面;以 200% DPI 运行;切换高对比度;用 Avalonia DevTools 视觉树查找未命名的可操作控件;为待测控件设置 AutomationProperties.AutomationId。

常见错误:仅图标按钮缺 Name;为整洁移除焦点环;把 TextBlock 当可点击标题(应使用 Button.ghost);仅用颜色表示错误;单行截断无提示;KeyBinding 仅挂在 Window 上被 TextBox 吞掉按键;未提供 Win/macOS 双快捷键;对有意义的控件误设 AccessibilityView=Raw;可见标签与输入缺少 LabeledBy。

限制:资料未提供安装命令、包名或独立工具形态,仅以技能说明与代码示例形式给出;收费、平台支持细节与效果数据暂未提供。