UI Guidelines 组件落地专题

UI、通知与用户体验 已经覆盖 Dialog、Notification、Status Bar Widget 等插件 UI 主入口。本章把官方 UI Guidelines 中更细的规则落到插件工程实践：组件选择、文案、大小写、窗口尺寸、验证错误、空状态和无障碍。

核对日期：2026-06-18。

先选平台模式，再选控件

插件 UI 的第一步不是画界面，而是判断用户正在做什么：

用户目标	推荐模式	避免
执行命令	Action / menu / toolbar / popup	在设置页放“运行”按钮
修改偏好	Settings + Kotlin UI DSL	自定义配置文件编辑器
临时输入并确认	DialogWrapper	原生 JDialog
长期查看列表或状态	Tool Window	高频弹窗或常驻 notification
选择文件/类/路径	平台 chooser / text field built-in button	手写文件浏览器
展示无结果状态	Empty state + 1-2 个动作	空白面板或满屏说明
后台状态	Progress + Notification / Status Bar	阻塞 EDT 的 modal dialog

官方 User Interface Components 明确建议使用 IntelliJ Platform 自定义 Swing 组件。它们能自动适配 IDE 主题、字体、缩放和行为；Settings 和 Dialog 这类表单从 2021.3 起优先使用 Kotlin UI DSL。

组件选择速查

场景	推荐组件/模式	规则
单个立即动作	Button	标签用 imperative verb，Title Capitalization，通常不超过 5 个词
跳转文档或次要操作	Link	不用按钮占主要视觉层级
输入任意短文本	Input field	标签是名词并以冒号结尾；placeholder 不能代替 label
历史输入或有限值	Combo box / drop-down	能枚举值时不用自由输入框
多行或长文本	Text area / expandable text field	提供合理最小高度
表格/列表相关动作	Toolbar button	多个相关按钮不要堆在表格旁边
危险且不常用动作	Split button 或二级按钮	默认按钮不应执行不可恢复危险动作
搜索	Search field	不用普通 text field 加自定义 icon
密码或 token	JBPasswordField / sensitive storage	不在普通 XML state 中保存明文

DevKit 检查 Plugin DevKit | Code | Undesirable class usage 可以提示普通 Swing 类的 IntelliJ Platform 替代组件。运行时可用 UI Inspector 查看 IDE 内部已有 UI 使用的组件、边距和 accessible properties。

文案规则

官方 Writing Short and Clear 的核心要求是：短、清楚、从用户角度写。

实践规则：

• 用简单现在时，一个句子只表达一个意思。
• 去掉实现视角词，例如 “internal provider failed”。
• 不写 “please click”“you can specify” 这类多余指令。
• 避免 “General”“Advanced”“Options” 这类空泛分组；无法删除时换成更具体名称。
• 错误消息描述用户目标和解决方式，不暴露内部异常栈。
• 链接文字说明目的，不写只有 “Learn more” 的孤立链接。

对比：

不推荐	推荐
Invalid Git Executable. Error running git.exe.	Cannot run "git.exe". The file is not found.
Specify endpoint URL	Endpoint URL:
Click Browse to select a file	File:
An error occurred while executing provider	Cannot analyze the current file

大小写规则

官方 capitalization 规则对跨平台 IDE 很重要。

Title Capitalization 用于：

• Buttons。
• Menus。
• Tooltips 中的 action 名称。
• 表格、popup、message box、dialog 的 header。
• UI control group header。

Sentence capitalization 用于：

• Text field、checkbox、radio button、combo box 等控件 label。
• Combo/list/tree/table item。
• Link。
• Alt+Enter popup 中的 quick fix 和 intention action。
• Notification header/body。
• Error message、tooltip、status description、instruction。

示例：

Button: Check for Updates
Checkbox: Enable analysis on save
Link: Configure proxy
Intention: Convert to block body
Notification: Analysis completed
Error: The port number should be between 0 and 65535

输入框、placeholder 和默认值

Input field 只在无法枚举最可能值时使用。若需要保留历史输入，使用 combo box；若是搜索，使用 search field；若是路径，使用带 browse built-in button 的 field。

Label 规则：

• 短且描述性强。
• 名词形式，通常以冒号结尾。
• Sentence capitalization。
• 多个字段的 label 长度尽量接近，减少视觉空洞。
• disabled field 的 label 也应 disabled。

Placeholder 规则：

• Sentence capitalization。
• 不加句号和省略号。
• 用户开始输入时隐藏，而不是 focus 时隐藏。
• 可用于说明 optional 或默认值。
• 不用 placeholder 展示示例；示例放在 field 下方 context help。
• 不把 placeholder 当 label。

窗口尺寸

官方 Window Sizes 给出对话框默认尺寸：

尺寸	建议大小	适合场景
Small	350 x 250	竖向堆叠的少量控件
Medium	500 x 350	两列短 label、2-3 列表格、长输入框
Large	750 x 525	4 列以上表格、master-detail、含代码片段的两列布局
Extra Large	1000 x 700	三列以上或复杂 Settings 类页面

Popup：

• action/options 竖向列表最小宽度 200 px。
• 内容丰富 popup 用 medium 500 px 或 large 750 px。
• popup 最大宽高建议不超过屏幕的 80%，超出时使用 scrollbar。

Tool Window：

• vertical tool window 默认宽度为 IDE 宽度的 20%，最小 200 x 500。
• horizontal tool window 默认高度为 IDE 高度的 20%，最小 500 x 200。

不要为了让窗口“看起来紧凑”把内容压到无法阅读。复杂内容优先设置内部组件最小尺寸，而不是硬编码整个窗口尺寸。

验证错误

官方 Validation Errors 的原则是：尽量不让用户输入无效数据。能约束的值用 combo、slider、数字过滤、默认值或 context help，不要等用户提交后报错。

验证策略：

场景	时机	展示
非法字符、过大值	输入时	field 红色 + tooltip
需要完整输入后才能判断	focus loss 或提交	tooltip
简单表单必填项	禁用确认按钮直到填写完整	通常不显示错误
复杂表单必填项	提交时	高亮全部错误，focus 第一个错误
远程连接校验	提交时	field tooltip 或 inline error
多页设置复杂值	重开设置或使用该值时	tooltip、inline、notification 或 Problems 页

Kotlin UI DSL 示例：

textField()
    .validationOnInput {
        val value = it.text.toIntOrNull()
        if (value == null || value !in 0..65535) {
            error("The port number should be between 0 and 65535")
        } else {
            null
        }
    }

错误消息写法：

• 写问题和可行解决方式。
• 使用具体对象名、路径和值。
• 用 “Cannot”“Incorrect”“Should be” 替代 “Failure”“Invalid”“Must” 等生硬词。
• 不把异常类名直接展示给普通用户。
• 能贴近字段展示就不要弹全局 dialog。

Empty State

Tool Window、list、tree、table、master-detail 空状态不能留白。官方建议包含：

1. 为什么为空。
2. 一到两个开始动作。
3. 可选帮助链接。

文案模式：

No rules added.
Add Rule...

规则：

• 使用当前 UI 中已有实体名，不引入新概念。
• 一般只给 1-2 个动作，3 个以上会增加选择成本。
• 如果动作打开 dialog 或 popup，用省略号。
• 空状态中使用 sentence capitalization。
• 如果空状态动作和 toolbar action 重复，通常隐藏无关 toolbar action。
• table/list/tree 的空状态用 inline help，Tool Window/master-detail 可加带问号 icon 的帮助链接。

Accessibility

最低可访问性要求：

• 所有功能可只用键盘操作。
• Tab / Shift+Tab 不产生 keyboard trap。
• popup、dialog 或动态内容出现时，focus 移动合理且不打断用户当前操作。
• 所有可交互控件都有 accessible name。
• 自定义组件设置正确 accessible role、state 和 description。
• 状态变化需要 screen reader 感知时触发 property change 或使用 AccessibleAnnouncerUtil.announce()。
• 用 NVDA、JAWS 或 VoiceOver 至少抽测关键流程。
• 用 UI Inspector 检查 accessible properties 和运行 accessibility audit。

Accessible name 不应包含 role 本身：

Correct: Password
Incorrect: Password text field

复杂组件的 accessible name 应包含用户可见的关键信息，例如标题、状态、图标含义。非交互 label/panel 通常不应 focusable；只有 screen reader 用户需要读取重要信息时，才根据 ScreenReader.isActive() 调整。

插件 UI QA 清单

发布前至少检查：

• 亮色、暗色、高对比主题。
• 100%、150%、200% 缩放。
• 小屏幕和多显示器。
• 键盘-only 流程。
• screen reader 基础流程。
• Settings 搜索能找到插件设置。
• Dialog 默认按钮、focused button、Esc/Enter 行为正确。
• 所有后台任务有进度和取消。
• 错误贴近发生位置，通知不刷屏。
• UI 文案符合 capitalization 和 sentence/title 用法。
• mkdocs 或文档截图中说明的 UI 与当前实现一致。

参考来源

• UI Guidelines
• User Interface Components
• Accessibility
• Window Sizes
• Writing Short and Clear
• Capitalization
• Validation Errors
• Button
• Input Field
• Empty State