IntelliJ 平台 UI 无障碍实战指南键盘、焦点、标签与屏幕阅读器评审【免费下载链接】intellij-communityIntelliJ IDEA IntelliJ Platform项目地址: https://gitcode.com/GitHub_Trending/in/intellij-community本指南基于 IntelliJ 社区版仓库中的 Agent 技能文档 .agents/skills/ui-accessibility/SKILL.md 展开面向在 IntelliJ 系 IDE 中创建、修改或评审 UI含插件 UI的开发者。读完本文你将掌握基于 Swing 与 Kotlin UI DSL 的无障碍元数据规范、键盘与焦点遍历的评审工作流以及使用屏幕阅读器和 UI Inspector 的验证方法可直接用于日常代码评审与自测。适用场景与核心原则该技能适用于在基于 IntelliJ 的 IDE 中创建、修改或评审 UI 的工作包括插件 UI。需要特别强调的是如果某项工作只是碰巧有 UI 表面而核心工作并不在 UI 本身则不适用本技能。也就是说判断依据是工作是否直接作用于 UI 层。技能覆盖的范围包括Swing 与 Kotlin UI DSL 及其他 UI 栈的无障碍期望键盘使用、屏幕阅读器、焦点、标签的评审与验证检查动态反馈、对比度、缩放与本地化等维度。以 WCAG 2.2 作为首要的无障碍标准对应文档声明IntelliJ 平台专属的 API、工具与期望则以上游 JetBrains IntelliJ Platform 无障碍指南为源头。本文所有 API 类名均出自该技能文档实际使用时以你所依赖的 IntelliJ Platform SDK 版本为准。Swing 与 Kotlin UI DSL 的无障碍细节无障碍上下文细节仅与基于 Swing 的 UI 相关Kotlin UI DSL 构建出的仍是 Swing 组件因此同样适用。核心思路是尽量依赖 Swing/Kotlin UI DSL 的默认行为只在明确违反规范或缺失屏幕阅读器信号时才进行定制。可访问名称、角色与状态为自定义 Swing 组件与自定义渲染器提供正确的可访问名称accessible name、角色role、状态/值state/value以及属性变更通知property-change notifications。可访问名称通常可以从组件文本、工具提示文本或JLabel.setLabelFor()推断而来。仅在推断结果缺失、含糊或错误时才设置或覆盖可访问名称。不要把组件角色包含进可访问名称。对于复杂自定义组件应组合可见标题、副标题、图标含义以及其他理解组件所需的可见部分。仅在隐式元数据缺失、不足或错误时才修改AccessibleContext及其属性。赋值方式的选择若只是把某个已知的值赋给一个属性优先直接使用component.getAccessibleContext().accessibleName ...或accessibleDescription ...。当以下场景出现时使用AccessibleContextUtil才更有价值从另一个组件复制元数据组合多个可访问字符串避免重复的描述设置可访问父级accessible parent为屏幕阅读器规范化多行文本。不要预防性添加无障碍属性不要预先preemptively添加无障碍属性或触发无障碍事件。当名称、角色、状态、值、焦点行为与事件已由 Swing/Kotlin UI DSL 默认正确提供时应依赖默认行为只有在修复具体的规范违规或缺失的屏幕阅读器信号时才定制。accessibleDescription 的谨慎使用accessibleDescription仅在少数情况下使用当 UI 中已存在、但相关组件获得焦点时不会被读出的补充文本如注释、横幅、提示、警告或内联说明需要被传达时。不要凭空发明一段与可见标签/状态重复的独立描述。角色与状态的选择纯文本内容使用AccessibleRole.LABEL可编辑或可选择的文本字段/文本区域使用AccessibleRole.TEXT。按行为匹配具体按钮角色PUSH_BUTTON、RADIO_BUTTON、TOGGLE_BUTTON或HYPERLINK。当自定义状态如 checked、selected、expanded、editable未被正确暴露时覆盖可访问状态当状态、选择、值、文本变化需要向辅助技术播报时触发可访问属性变更事件。从零开发自定义组件的参考策略对于从零开始的自定义组件先研究相似的 Swing 组件实现了哪些Accessible*接口如AccessibleAction、AccessibleText、AccessibleSelection、AccessibleValue再手动选择需要实现的接口避免遗漏或过度实现。播报与屏幕阅读器感知屏幕阅读器会自动播报焦点组件的可访问属性变化。对于焦点组件之外的重要变化或无法用现有属性变更机制表达的变化使用AccessibleAnnouncerUtil.announce()。当代码依赖播报支持时先检查AccessibleAnnouncerUtil.isAnnouncingAvailable()。ScreenReader.isActive()仅用于极少数必须针对屏幕阅读器用户做出不同行为的场景。默认情况下UI 应对所有用户表现一致。其他 UI 栈的同等目标对于 Compose、JCEF 或其他非 Swing UI应使用该栈自身的语义、焦点、键盘与测试机制实现相同的无障碍目标——即可访问的名称、角色、状态、键盘可达性与可测试性而不是生搬 Swing 的 API。评审工作流在完成代码更改前检查 UI该技能明确要求在完成代码更改前按下述清单检查 UI。这些检查点同时适用于对话框、弹出窗口、工具窗口与内嵌面板等所有可聚焦界面。键盘操作与焦点顺序检查项要求纯键盘操作仅用键盘即可完成全部操作焦点顺序可预测焦点不会被困住可聚焦性只有可交互组件可被键盘聚焦聚焦后可被 Space 或 Enter 激活Tab / ShiftTabTab移动到下一个可聚焦组件ShiftTab移动到上一个适用于所有可聚焦界面焦点顺序焦点停留点focus stop遵循视觉布局顺序焦点指示器每个焦点停留点都显示焦点指示器且不被裁剪或遮挡Escape关闭对话框与弹出窗口从工具窗口退出时若该路径符合预期则把焦点还给编辑器重新定义遍历的危险信号任何重新定义遍历行为的代码都视为提示你验证遍历循环的信号重点关注focusTraversalKeysEnabled false一个Tab/ShiftTab键绑定或一个消费该键的组件自定义的FocusTraversalPolicy。一旦发现上述情况走一遍整个循环并确认三件事每个交互控件都可达顺序与布局一致焦点既能向前也能向后退出循环。Tab 被占用的修复建议如果当前Tab被用于移动焦点之外的用途推荐的修复方式是把该行为迁移到非遍历键上让Tab与ShiftTab专用于遍历。仅在符合平台约定且用户已形成预期的场景保留Tab覆盖——例如在打开的补全弹出窗口中用Tab完成补全——并且把该覆盖严格限定在那一状态内。非交互元素与动态内容非交互的标签与面板默认不可聚焦除非关键重要信息在屏幕阅读器下无法获得此时才可用ScreenReader.isActive()门控该行为。新的弹出窗口、模态对话框与动态内容要么自动获得焦点要么有键盘路径可达。不要在用户与列表或下拉框交互时意外移动焦点。容器组件列表、树、表格支持项之间的方向键导航。重要的动态反馈如校验结果、搜索结果、后台任务完成必须被播报或可通过其他方式到达。视觉与本地化颜色不是唯一信号对比度、焦点可见性与字体/UI 缩放保持可用。用户可见的无障碍文本通过消息 bundle 本地化。这与仓库 AGENTS.md 中用户可见字符串属于*.properties用于本地化的规范一致说明无障碍文本同样走平台的消息资源体系。UI 适配 IDE 缩放级别。验证方法如何证明无障碍达标该技能给出了一套不依赖自动工具的验证流程纯键盘走查仅用键盘走查整个 UI。屏幕阅读器实测在可行时用受支持的屏幕阅读器测试——Windows 上为 NVDA 或 JAWSmacOS 上为 VoiceOver。UI Inspector 检查用 UI Inspector 查看可访问名称、描述、角色与状态。启用 Show Accessibility Issues 来调查可疑问题或验证自定义 UI 行为常规验证通常不需要开启。焦点顺序清单当键盘遍历在范围内时按Tab顺序列出焦点停留点并与视觉布局顺序比对记录任何覆盖遍历的键及其实际行为。评审备注在代码评审或最终说明中明确陈述检查了哪些无障碍路径、哪些仍属于人工检查项。在仓库中的实践入口该技能是当前仓库 Agent 技能体系的一员可在以下位置找到配套上下文技能主文档.agents/skills/ui-accessibility/SKILL.md即本文的原始依据技能索引.agents/skills/INDEX.md其中对该技能的一行概括为 Review IntelliJ UI accessibility for keyboard, focus, and labels.可用于快速定位仓库总体规范AGENTS.md其中明确了用户可见字符串必须放入*.properties以便本地化以及代码评审前运行相关测试的流程要求。使用建议将该技能用于 UI 相关改动新增对话框、自定义渲染器、重构焦点遍历逻辑、接入 Compose/JCEF 界面等的提交前自检对于与 UI 无关的改动如纯逻辑修复无需套用本检查清单。在完成验证后务必在评审说明中注明已覆盖的无障碍路径与仍需人工验证的部分保证无障碍检查的可追溯性。【免费下载链接】intellij-communityIntelliJ IDEA IntelliJ Platform项目地址: https://gitcode.com/GitHub_Trending/in/intellij-community创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考