用途:该技能用于在 Kilo 的 JetBrains 插件目录 packages/kilo-jetbrains/ 中编写或审查 UI 代码,提供详细的 UI 参考。硬性限制与复用优先索引见该目录的 AGENTS.md,本技能侧重具体做法。
技术选型限制:不要使用 Kotlin UI DSL v2(com.intellij.ui.dsl.builder),所有 UI 布局使用标准 Swing 配合 IntelliJ 平台组件;不要使用 Kotlin Compose 或 intellij.platform.compose,插件 UI 保持现有 Swing 技术栈;不要使用 JCEF(JBCefBrowser),因为它在 JetBrains 远程开发(split 模式)下不可用,前端进程运行在客户端而 JCEF 需要宿主显示。按需求选择 API:布局、表单、面板用标准 Swing 加平台组件替换;工具窗口用 SimpleToolWindowPanel 加 ToolWindow.contentManager;菜单和工具栏用 Action System;对话框继承 DialogWrapper。
样式令牌:UiStyle 是插件内可复用 UI 常量的唯一来源,包含 Gap(DPI 感知的间距)、Colors(主题感知的通用颜色)、Components(小型可复用 Swing 辅助方法)。引入新的可复用颜色、间距、边框、尺寸、字体或辅助方法前,先查 IntelliJ 源码或公开仓库是否已有标准 API 或命名键;存在则直接使用而不复制数值;无合适标准键才加入 UiStyle。会话/聊天 UI 的静态令牌归 SessionUiStyle 管理,包括 SessionLayout、View、RecentSessions、Timeline。通用布局常量放入 UiStyle,会话专属常量放入 SessionUiStyle;不要为存常量而新建字段,直接在调用处引用常量对象;不要通过构造器或方法参数传递样式常量,只有真正可变或测试控制的值才用参数。
主要 UI 规则:有平台等价组件时用平台组件替代原生 Swing;新增用户可见操作时考虑添加指标以便追踪使用;不要显式设置默认 Swing 属性,除非组件默认不同或有可记录的渲染原因,避免无必要地设 isOpaque = false;避免硬编码尺寸、颜色和字号,使用平台样式 API;用户可见字符串放入 *.properties 文件;不添加装饰性辅助函数、包装器或防御性 UI 代码,除非确实提升清晰度或正确性。
平台组件与工具:用 JBLabel、JBTextField、JBTextArea、JBList、JBScrollPane、JBTable、Tree、JBSplitter、JBTabs、JBCheckBox 等替代对应 Swing 组件;运行时颜色用 UIUtil、JBUI.CurrentTheme、NamedColorUtil、JBColor.namedColor、JBColor.lazy;边框用 JBUI.Borders.empty();像素尺寸用 JBUI.scale(px)。另列出 BorderLayoutPanel、JBPanel.withBorder、ContextHelpLabel、HyperlinkLabel、SimpleColoredComponent、ColoredListCellRenderer、ColoredTreeCellRenderer、SimpleTextAttributes、ToolbarDecorator 等通用工具。多行与富文本方面:富 HTML 用 JBHtmlPane;简单多行标签用 JBLabel 加 XmlStringUtil.wrapInHtml();单行会话文本用 PlainLabel,不要用 <html> 文本,因为 Swing 在编辑器标签页分离或重新附着时会重新解析每个 HTML 标签;可滚动/换行 HTML 面板用 SwingHelper.createHtmlViewer();高性能彩色文本片段用 SimpleColoredComponent;纯文本换行用 MultiLineLabel(遗留,不要在新代码使用)。用 HtmlChunk/HtmlBuilder 以编程方式构建 HTML,避免拼接原始 HTML 字符串;简单换行/转义用 XmlStringUtil;可选/可复制标签文本用 JBLabel.setCopyable(true),自动换行用 setAllowAutoWrapping(true);手动创建 JEditorPane 时用 HTMLEditorKitBuilder;单行溢出省略用 SwingTextTrimmer,不要手动截断字符串;HTML 标记可放在 properties 值中。
主题化颜色:不要硬编码运行时颜色,IntelliJ UI 颜色须来自当前主题、组件状态、编辑器配色方案或集中语义命名颜色键。常用语义 API 包括 UIUtil.getLabelForeground()、getContextHelpForeground()、getErrorForeground()、JBUI.CurrentTheme.Label.warningForeground()、NamedColorUtil.getInactiveTextColor()、getBoundsColor()/JBColor.border()、JBUI.CurrentTheme.Link.Foreground.*、UIUtil.getListForeground/Background、getTreeForeground/Background、Popup.BACKGROUND、Validator 错误与警告边框/背景色。依赖运行时状态或活动编辑器配色方案的颜色用 JBColor.lazy { ... };定义或消费语义颜色键用 JBColor.namedColor(...);HTML/CSS 片段用 ColorUtil.toHtmlColor(...) 转换。运行时 UI 代码避免内联 Color(...)、数字 JBColor(...)、Gray.xNN、JBColor.GRAY 和十六进制字面量,例外是在无既有平台键时集中定义带命名键的语义颜色。
主题化字体:不要硬编码字号或字体族;无样式变化时优先组件默认字体;标题用 JBFont.h1() 到 h4();样式变化用 .asBold()、.asItalic()、.asPlain();正文和次要文本用 JBFont.regular()、medium()、small();相对调整现有组件字体用 RelativeFont;渲染器中的错误、灰色文本、快捷键和链接优先 SimpleTextAttributes 的 ERROR_ATTRIBUTES、GRAYED_ATTRIBUTES、SHORTCUT_ATTRIBUTES、LINK_ATTRIBUTES;避免 Font("...")、原始字号和 deriveFont(14f) 等写法。
边框、内边距与间距:边框一律用 JBUI.Borders.empty(top, left, bottom, right),内边距用 JBUI.insets(),二者 DPI 感知且在缩放时自动更新;像素尺寸用 JBUI.scale(int) 保证 HiDPI 缩放;没有平台替代时才用 EmptyBorder、原始 Insets 或 Dimension。依赖主题的边框、内边距、颜色和圆角弧在 Look and Feel 变化时须重新求值,不要为长生命周期组件在构造器中一次性赋值主题边框,优先重写 updateUI() 或订阅 LafManagerListener.TOPIC;可主题化弧度和间距用 JBValue.UIInteger,在布局和尺寸计算时调用 .get(),不要缓存结果;常见间距优先用 JBUI.CurrentTheme 中特定区域的内边距(如 ActionsList.cellPadding()、Toolbar.toolbarButtonInsets()、ToolWindow.headerLabelLeftRightInsets())。其他替代映射包括:手写空内边距用 JBUI.Borders.empty(...),手写内边距用 JBUI.insets(...) 等,手写尺寸用 JBUI.size(...)/JBDimension/JBUI.scale(...),侧边分隔线用 customLineTop/Bottom,组合边框用 compound/merge,简单 BorderLayout 面板用 JBUI.Panels.simplePanel(...)/BorderLayoutPanel,一维多组件行列用 Stack,流畅平台面板用 JBPanel.withBorder(...) 等,单组件对齐包装用 Align。
Stack 一维多组件布局:当多个 Swing 组件应作为一个垂直列或水平行且无视觉装饰时使用 Stack(ai.kilocode.client.ui.layout.Stack),它是透明、无边框、无颜色的 JPanel(null),按插入顺序布局可见子组件。Stack.vertical(gap) 自上而下排列,子组件填满可用宽度并保留有界首选高度,宽度取最大子宽,高度为子高之和加间隙;Stack.horizontal(gap) 自左而右排列,子组件填满可用高度并保留有界首选宽度,宽度为子宽之和加间隙,高度取最大子高。"有界首选"指子组件在栈轴上的首选尺寸被限制在有效 [min, max] 范围;交叉轴上布局跟随容器尺寸。可用工厂和流畅方法如 Stack.vertical().next(header).next(body);构造函数 gap 用于相邻可见子组件的常规间距;gap(size) 仅当下一个添加的组件是下一个可见组件时使用一次性间隙,尾随或中间有隐藏组件时被忽略;持久的前导、尾随或中间空白用 fill(size)、Stack.verticalFiller(size)、Stack.horizontalFiller(size),不要用 Box 或 gap(size)。简单保留式 Swing 行列且子组件应跟随交叉轴尺寸时用 Stack;在可用空间内定位单个子组件用 Align。Stack 不用于内边距、边框、颜色、换行行、弹性胶水或需要宽度感知 HTML 重排的会话组件。Stack 和 Align 会向每个子组件询问最小、首选和最大尺寸,深层无效树每次嵌套都会增长;反复失效并测量的树(如列表渲染器戳记)应在 LayoutPass.measure { ... } 内执行每次布局或尺寸读取,该 pass 内每个容器对每种尺寸只回答一次,且不要在 pass 内更改被测量内容。
Align 单组件对齐包装:当单个 Swing 组件需在可用空间中定位且不添加视觉装饰时使用 Align(ai.kilocode.client.ui.layout.Align),它是透明、无边框、无颜色的 JPanel(null),按独立的水平(HAlign)和垂直(VAlign)模式布局其唯一子组件。CenterShrinkPanel 已被移除,可直接用 child.align(HAlign.CENTER, VAlign.CENTER) 替代。对齐模式:TRACK 使子组件始终填满可用空间并忽略其 min/preferred/max,包装器在该轴上仅报告内边距、尺寸贡献为零;FIT 使子组件填满可用空间但限制在有效 [min, max] 范围内,并尊重子组件的 min/preferred/max;LEFT/TOP、CENTER、RIGHT/BOTTOM 分别在对应边缘或居中放置有界首选尺寸的子组件,空间不足时收缩到可用空间以避免溢出。"有界首选"同样指首选尺寸被限制在有效 [min, max] 范围。可通过 Component 上的工厂扩展调用,如 child.align(HAlign.LEFT, VAlign.TOP)、child.align(HAlign.CENTER, VAlign.CENTER)、child.align(HAlign.TRACK, VAlign.CENTER) 等。资料在此处被截断,后续内容暂未提供。