Skip to content

[FEATURE] 添加基础无障碍(A11Y)支持 - 键盘导航与屏幕阅读器兼容性 #94

Description

@yunshenwuji

The problem/use-case that the feature addresses

作为一名依赖屏幕阅读器和键盘导航的视障开发者,我目前无法有效使用 WSL Dashboard。该应用缺少基础的无障碍支持,具体表现为:

  • 无键盘导航:无法通过 Tab/Shift+Tab 或方向键访问和激活 UI 元素,所有操作只能依赖鼠标
  • 无屏幕阅读器支持:按钮、状态指示器和交互控件没有可访问的标签或角色,导致它们对 NVDA、Windows 讲述人等辅助技术完全不可见
  • 无焦点指示器:使用键盘导航时,无法判断当前哪个元素获得了焦点

这对视障用户造成了严重的使用障碍。对于依赖 WSL 进行日常开发工作的视障开发者来说,这意味着他们无法享受到 WSL Dashboard 带来的便捷管理体验。

Description of the feature

考虑到 WSL Dashboard 是基于 Slint UI 框架 构建的,而该框架本身已经内置了无障碍基础设施,建议分阶段实现基础的无障碍支持:

第一阶段:基础键盘导航(最低可用的无障碍)

  • 启用所有交互元素(按钮、标签页、菜单项)的 Tab/Shift+Tab 顺序遍历
  • 确保所有可点击元素都可以通过 Enter 或 Space 键激活
  • 为键盘聚焦的元素添加清晰可见的焦点指示器
  • 在列表视图和标签栏中支持方向键导航

第二阶段:屏幕阅读器基础支持

  • 在 Cargo.toml 中启用 Slint 的 accessibility cargo 功能标志
  • 为所有交互元素添加 accessible-role 属性:
    • 按钮 → accessible-role: button
    • 标签页 → accessible-role: tab,容器用 accessible-role: tab-list
    • 状态指示器 → accessible-role: status
    • 复选框/开关 → accessible-role: check-boxswitch
    • 文本输入框 → accessible-role: text-input
  • 添加 accessible-label 属性,为所有控件提供人类可读的名称
  • 为动态状态添加 accessible-value(例如发行版的"运行中"/"已停止"状态)
  • 确保状态变化能被屏幕阅读器及时播报

需要重点覆盖的 UI 元素:

  1. 侧边栏导航标签(首页、网络、USB、设置等)
  2. 发行版卡片(名称、状态、WSL 版本、资源使用情况)
  3. 操作按钮(启动、停止、终止、重启、注销)
  4. 快捷操作(打开终端、VS Code、文件资源管理器)
  5. 设置面板(所有开关、下拉菜单、输入字段)
  6. 系统托盘菜单(如技术上可行)
  7. 状态指示器徽章(运行中/已停止)

Alternatives you've considered

目前视障用户只能退而求其次,使用以下替代方案:

  • 原始 wsl.exe 命令行工具:功能完整但效率低很多,需要记忆大量命令参数
  • 其他 WSL 管理器:但大多数同类工具同样缺乏无障碍支持
  • 手动 PowerShell 命令:用于端口转发、USB 设备管理等高级操作

这些替代方案都无法提供 WSL Dashboard 为视力正常用户带来的直观、高效的管理体验。目前没有发现本仓库中有相关的已开放或已关闭的无障碍功能请求。

Additional information

技术背景:
由于 WSL Dashboard 使用 Slint 框架,Slint 已经内置了完整的无障碍支持,实现成本相对较低:

  1. 只需启用 accessibility 功能标志
  2. .slint UI 组件中添加可访问性属性
  3. Slint 会自动处理平台特定的无障碍 API 集成(Windows 上自动对接 UI Automation)

参考文档:

测试建议:

  • 使用 NVDA(Windows 免费开源屏幕阅读器)进行测试
  • 使用 Windows 内置讲述人进行测试
  • 仅使用键盘(Tab、Shift+Tab、Enter、Space、方向键)完整导航整个应用
  • 验证所有状态变化都能被屏幕阅读器播报

协助意愿:
如果无障碍功能开始实现,我很乐意作为视障用户帮忙测试,或者为屏幕阅读器用户的体验提供更具体的反馈和建议。

感谢考虑这个请求!WSL Dashboard 是一款非常棒的工具,如果能让所有人都用上它,那就更好了。

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions