add-statusbar-widget
在 IDEA 状态栏添加图标 / 文字 widget,含 Consumer 类型陷阱
- License 许可
- MIT
- 最近更新
- 2026-08-05
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- add-statusbar-widget
- description
- 在 IDEA 状态栏添加图标 / 文字 widget,含 Consumer 类型陷阱
03 SKILL.md 正文
/add-statusbar-widget — 添加状态栏组件
在 IDEA 主窗口底部状态栏添加一个 widget。本项目的标准实现是 IconPresentation + 单击切换,避免弹二级菜单(用户最在意的是"
看一眼就知道开关状态")。
Usage
/add-statusbar-widget [WidgetName]
WidgetName— 不带Widget后缀,例如SkillInspectorStatusBar、SkillModeIndicator。
Information Needed
- Widget ID — 与
plugin.xml中<statusBarWidgetFactory id="..."/>一致;project 范围全局唯一。 - 展示形态 —
IconPresentation(项目首选)/TextPresentation/MultipleTextValuesPresentation。 - 状态来源 — 一般是
PersistentStateComponent设置(参考SkillInspectorSettings)。 - 点击行为 — 切换(toggle)/ 弹菜单 / 跳转设置 / 触发 Action。
Files to Create/Modify
1. Factory:src/main/java/dev/dong4j/idea/skill/inspector/statusbar/{Name}WidgetFactory.java
public class {Name}WidgetFactory implements StatusBarWidgetFactory {
public static final String ID = "{WidgetId}";
@Override
@NotNull
public String getId() {
return ID;
}
@Override
@NotNull
public String getDisplayName() {
return SkillInspectorBundle.message("statusbar.{xxx}.display.name");
}
@Override
public boolean isAvailable(@NotNull Project project) {
return true;
}
@Override
@NotNull
public StatusBarWidget createWidget(@NotNull Project project) {
return new {Name}Widget(project);
}
@Override
public void disposeWidget(@NotNull StatusBarWidget widget) {
widget.dispose();
}
}
2. Widget:src/main/java/dev/dong4j/idea/skill/inspector/statusbar/{Name}Widget.java
项目首选范式:图标 + 单击切换
public class {Name}Widget implements StatusBarWidget, StatusBarWidget.IconPresentation {
private final Project project;
private StatusBar statusBar;
public {Name}Widget(@NotNull Project project) {
this.project = project;
}
@Override
@NotNull
public String ID() {
return {Name}WidgetFactory.ID;
}
@Override
public void install(@NotNull StatusBar statusBar) {
this.statusBar = statusBar;
}
@Override
public void dispose() {
statusBar = null;
}
@Override
@Nullable
public WidgetPresentation getPresentation() {
return this;
}
@Override
@NotNull
public Icon getIcon() {
return SkillInspectorSettings.getInstance().isXxxEnabled()
? AllIcons.General.InspectionsEye
: AllIcons.General.InspectionsPowerSaveMode;
}
@Override
@Nullable
public String getTooltipText() {
return SkillInspectorBundle.message(
SkillInspectorSettings.getInstance().isXxxEnabled()
? "statusbar.tooltip.enabled"
: "statusbar.tooltip.disabled"
);
}
/**
* ⚠️ 关键陷阱:返回类型必须是 com.intellij.util.Consumer,
* 不能用 java.util.function.Consumer,否则 IDE 不会把它识别为点击回调,
* 单击图标完全无响应(且不报错,最容易被坑)。
*/
@Override
@NotNull
public Consumer<MouseEvent> getClickConsumer() {
return event -> toggle();
}
private void toggle() {
SkillInspectorSettings settings = SkillInspectorSettings.getInstance();
settings.setXxxEnabled(!settings.isXxxEnabled());
refresh();
}
private void refresh() {
if (statusBar != null && !project.isDisposed()) {
statusBar.updateWidget(ID());
}
}
}
关键约束(务必逐条核对):
Consumer<MouseEvent>必须 importcom.intellij.util.Consumer:用java.util.function.Consumer不会编译失败但点击完全无响应——这是状态栏 widget 最常见的坑,IDE 默默吞掉。refresh()必须先判project.isDisposed():用户关项目时 widget 还在执行回调会抛Cannot access disposed project。dispose()必须把statusBar置 null:之后不要再调它。- 优先用
AllIcons内置图标:如AllIcons.General.InspectionsEye、AllIcons.General.InspectionsPowerSaveMode,自动适配浅色 / 深色主题;自定义图标参考/add-icon。 - 图标对要有强对比:开 / 关两个状态用户必须一眼区分,不要用"颜色相近的两只眼睛"。
备选:MultipleTextValuesPresentation(弹下拉菜单)
如果一定要弹菜单(例如多 profile 切换),实现 getPopup() 返回 JBPopup,参考 com.intellij.openapi.wm.impl.status.widget。本项目 V1
已经从该模式精简到"单击切换",新增 widget 优先用 IconPresentation。
3. 注册:src/main/resources/META-INF/plugin.xml
<extensions defaultExtensionNs="com.intellij">
<statusBarWidgetFactory id="{WidgetId}"
implementation="dev.dong4j.idea.skill.inspector.statusbar.{Name}WidgetFactory"/>
</extensions>
参考:
<!-- 状态栏开关:id 必须与 SkillInspectorStatusBarWidgetFactory.getId() 一致,
否则 verifyPluginStructure 会报错 -->
<statusBarWidgetFactory id="SkillInspectorStatusBar"
implementation="dev.dong4j.idea.skill.inspector.statusbar.SkillInspectorStatusBarWidgetFactory"/>
关键约束:
- plugin.xml 的
id必须等于 FactorygetId()返回值:不一致会被./gradlew verifyPlugin直接拦下。
4. 国际化
statusbar.{xxx}.display.name=My Widget
statusbar.tooltip.enabled=My Widget enabled (click to disable)
statusbar.tooltip.disabled=My Widget disabled (click to enable)
5. 设置联动
如果点击行为是切换设置,确保 SkillInspectorSettings(或同形 service)已经存在该开关。否则先走 /add-setting。
设置变更时通知所有 widget:在 setXxxEnabled() 内不需要主动调用,当前 widget 通过自身 refresh() 即可;如果有第三方组件需要联动,可以走
MessageBus 或 ApplicationManager.getApplication().getMessageBus() 发布主题。
Build & Verify
./gradlew compileJava
./gradlew verifyPlugin # 必跑,shortName / id 错位会被发现
./gradlew runIde
# IDE 状态栏右键 → "Status Bar Widgets" → 确认你的 widget 在列表里且可勾选
# 单击 widget → 图标 / tooltip 应立刻切换
Troubleshooting
- 单击没反应:99% 是
Consumer<MouseEvent>import 错了——核对是com.intellij.util.Consumer而不是java.util.function.Consumer。 - 状态栏没看到 widget:右键状态栏 → "Status Bar Widgets" 把它勾上;首次需要重启 IDE 实例。
verifyPluginStructure报widget id mismatch:plugin.xml 的id与 FactorygetId()不一致。- 图标在深色主题下看不清:换
AllIcons同语义图标,或为自定义图标提供_dark.svg变体(详见/add-icon)。 statusBar.updateWidget抛 NPE:install还没回调时就触发了 refresh,加if (statusBar != null) ...。
参考代码
- Factory:
src/main/java/dev/dong4j/idea/skill/inspector/statusbar/SkillInspectorStatusBarWidgetFactory.java - Widget:
src/main/java/dev/dong4j/idea/skill/inspector/statusbar/SkillInspectorStatusBarWidget.java - 设置联动:
src/main/java/dev/dong4j/idea/skill/inspector/settings/SkillInspectorSettings.java
04 同仓库更多 Skills
unused-reference-resource
Use this skill when `references/` contains files that are never linked from the body.
short-description
too short
security-sensitive-path
Use this skill when verifying detection of sensitive paths like `.env` or `~/.ssh` in the body.
security-secret
Use this skill when verifying detection of leaked secret patterns in the body.
security-prompt-injection
Use this skill when verifying detection of prompt-injection phrases such as "ignore previous instructions".
security-dangerous-command
Use this skill when verifying detection of dangerous shell commands in the body.