中文输入法候选窗「纯黑背景」配置说明机器环境Ubuntu 20.04.6 LTS / GNOME Shell 3.36.9 / X11 会话输入法ibus 1.5.22 ibus-libpinyin拼音改动日期2026-09-29当前状态已生效候选窗纯黑底 白字并会在每次登录后自动保持全程未修改任何系统文件也不需要 root 权限上图改前白底深字 #FAFAFA下图改后纯黑底白字 #000000。橙色选中项保留 Ubuntu 风格。一、原理为什么改的是 GNOME Shell 主题而不是 ibus 配置本机的中文候选窗不是 ibus 画的而是 GNOME Shell 自己画的对应代码 js/ui/ibusCandidatePopup.jsibus 只负责把候选词算出来发过来。它的外观完全由 Shell 主题 CSS 决定。本机 ibus 的启动参数是 ibus-daemon --panel disable --xim即禁用了 ibus 自带的 GTK 面板候选窗交给 Shell。所以改 ibus 的配置~/.config/ibus/…没有用该改的是 Shell 主题里 .candidate-popup-* 这几条 CSS 规则。本机当前使用的 Shell 主题由会话模式决定bashcat /usr/share/gnome-shell/modes/ubuntu.json→ “stylesheetName”: “Yaru/gnome-shell.css”→ “themeResourceName”: “theme/Yaru/gnome-shell-theme.gresource”即 Yaru 浅色 Shell 主题与「设置 → 外观」里的 GTK 主题 Yaru-dark 是两回事候选窗原样式为位置 原值候选窗背景 / 箭头 #FAFAFA候选窗边框 rgba(0, 0, 0, 0.35)候选词文字 #3D3D3D继承 stage 默认色候选序号 #242424选中项高亮 #E95420翻页按钮 白底 #FFFFFF / 边框 #CCCCCC主题 CSS 打包在 gresource 里可以抽出来查看只读不改动系统文件bashgresource extract /usr/share/gnome-shell/theme/Yaru/gnome-shell-theme.gresource/org/gnome/shell/theme/Yaru/gnome-shell.css /tmp/yaru-light.cssgrep -n “candidate-” -A 8 /tmp/yaru-light.css二、本机实际做了什么完整步骤可在别的机器复现2.1 确认环境bashcat /etc/os-release | head -3 # Ubuntu 20.04.6 LTSgnome-shell --version # GNOME Shell 3.36.9ps -eo args | grep -E ‘ibus|fcitx’ # ibus-daemon --panel disable --xim …ibus engine # libpinyin当前引擎gsettings get org.gnome.desktop.input-sources sources→ [(‘xkb’, ‘cn’), (‘ibus’, ‘libpinyin’)] index 0英文布局, index 1拼音要点候选窗必须是 Shell 画的这一条路径–panel disable GNOME否则要改的对象完全不同例如用 fcitx5 时是改 ~/.config/fcitx5/conf/classicui.conf 和主题。2.2 创建用户级扩展目录GNOME Shell 的用户扩展放在 ~/.local/share/gnome-shell/extensions//不需要 root。bashmkdir -p ~/.local/share/gnome-shell/extensions/ime-blackfeng.local三个文件内容见下节作用是把一段 CSS 作为 application stylesheet 叠加到系统 Yaru 主题之上——它只覆盖候选窗相关规则菜单、面板等其余界面保持原样。2.3 三个文件的内容metadata.jsonjson{“uuid”: “ime-blackfeng.local”,“name”: “IME 纯黑候选窗”,“description”: “把中文输入法ibus/libpinyin候选窗背景改为纯黑色、文字改为白色。通过 application stylesheet 叠加在系统 Yaru 主题之上只影响候选窗其余界面不变。禁用该扩展即可还原。”,“shell-version”: [“3.36”],“version”: 1}注意uuid 必须与目录名完全一致shell-version 里要包含 gnome-shell --version 的主次版本号这里是 3.36否则扩展会被标记为「过期」而不加载。uuid、name、description、shell-version 四项缺一不可。extension.jsGNOME 3.38 及更早的写法用 imports. 老式 APIjsconst Main imports.ui.main;const ExtensionUtils imports.misc.extensionUtils;let _stylesheet null;function init() {}function enable() {_stylesheet ExtensionUtils.getCurrentExtension().dir.get_child(‘ime-black.css’).get_path();Main.setThemeStylesheet(_stylesheet);Main.loadTheme();}function disable() {_stylesheet null;Main.setThemeStylesheet(null);Main.loadTheme();}ime-black.csscss/* 候选窗本体背景 边框 指向光标的箭头全部纯黑 */.candidate-popup-boxpointer {-arrow-background-color: #000000;-arrow-border-color: #000000;-arrow-box-shadow: 0 1px 4px rgba(0, 0, 0, 0.7);}/* 文字改白色原主题是深灰字黑底上会看不见 */.candidate-popup-content,.candidate-popup-text,.candidate-label {color: #ffffff;}/* 候选序号略暗一点保持层级 */.candidate-index {color: #b8b8b8;}/* 选中项保留 Ubuntu 橙色高亮 */.candidate-box:selected,.candidate-box:hover {background-color: #e95420;color: #ffffff;}/* 翻页按钮‹ ›跟随黑底否则黑窗里会留两块亮灰按钮 */.candidate-page-button {color: #ffffff;background-color: #000000;border-color: #333333;box-shadow: none;text-shadow: none;icon-shadow: none;}.candidate-page-button:hover,.candidate-page-button:focus {color: #ffffff;background-color: #1f1f1f;border-color: #4a4a4a;box-shadow: none;}.candidate-page-button:active {color: #ffffff;background-color: #2f2f2f;border-color: #4a4a4a;box-shadow: none;}.candidate-page-button:insensitive {color: #6a6a6a;background-color: #000000;border-color: #262626;box-shadow: none;text-shadow: none;icon-shadow: none;}2.4 启用并让它生效bash1) 写入「已启用」列表也就是设置里的开关gnome-extensions enable ime-blackfeng.local2) 确认状态gnome-extensions info ime-blackfeng.local # 状态: ENABLEDgsettings get org.gnome.shell enabled-extensions→ [‘ime-blackfeng.local’]两种生效方式重新登录 / 重启后Shell 启动时自动按上面的列表加载无需任何额外操作这是常态装完就不用管了。当前会话立即生效不想重新登录GNOME 3.36 允许通过 Shell 自己的 D-Bus Eval 调用同一套 APIbashgdbus call --session --dest org.gnome.Shell --object-path /org/gnome/Shell–method org.gnome.Shell.Eval‘const M imports.ui.main; M.setThemeStylesheet(“/home/feng/.local/share/gnome-shell/extensions/ime-blackfeng.local/ime-black.css”); M.loadTheme(); “ok”’本机就是这么让它立即生效的。注意Eval 在新版 GNOME约 41默认被禁用需要 unsafe mode那时改用「重新登录」或 gnome-extensions disable/enable 即可。2.5 验证切到拼音输入源SuperSpace在任意输入框里打几个字母例如 nihao候选窗出现。截图后统计像素确认背景确实是纯黑而不是深灰bashgnome-screenshot -f /tmp/ime.png用 python3-gi 读像素GdkPixbuf统计候选窗区域内 #000000 占比本机的实测数据候选窗区域主色 其它界面时钟/日历菜单改前 #FAFAFA 占 75.9% #FAFAFA/#FFFFFF改后 #000000 占 78.7% #FAFAFA/#FFFFFF未变→ 只有候选窗变了Shell 其余界面没被波及。三、微调颜色3.1 各颜色对应的规则想改的位置 CSS 选择器 属性候选窗背景含指向光标的箭头 .candidate-popup-boxpointer -arrow-background-color候选窗边框 .candidate-popup-boxpointer -arrow-border-color外阴影 .candidate-popup-boxpointer -arrow-box-shadow拼音串 / 辅助文字 .candidate-popup-text color候选词文字 .candidate-popup-content继承给子元素、.candidate-label color候选序号1 2 3 … .candidate-index color选中项 / 鼠标悬停项 .candidate-box:selected、.candidate-box:hover background-color翻页按钮 ‹ › .candidate-page-button另有 :hover / :focus / :active / :insensitive 四个状态 background-color、color、border-color3.2 常用改法直接替换对应行css/* 想用深灰而不是纯黑 */-arrow-background-color: #1a1a1a;/* 想用半透明黑能透出后面的内容 */-arrow-background-color: rgba(0, 0, 0, 0.85);/* 黑底在深色窗口上分不出边界时加一条可见边框 */-arrow-border-color: #4a4a4a;/* 序号更亮 / 更暗/.candidate-index { color: #ffffff; } /或 #808080 *//* 选中项换颜色GNOME 蓝 / 保留 Ubuntu 橙 */.candidate-box:selected, .candidate-box:hover { background-color: #3584e4; }3.3 改完怎么生效bash文件~/.local/share/gnome-shell/extensions/ime-blackfeng.local/ime-black.cssgnome-extensions disable ime-blackfeng.localgnome-extensions enable ime-blackfeng.local这两条命令会让扩展重新执行 enable()从而重新读取 CSS 文件并刷新主题不需要重新登录。四、还原 / 卸载临时关掉保留文件随时再打开bashgnome-extensions disable ime-blackfeng.local候选窗立刻恢复系统原样白底深字gnome-extensions enable ime-blackfeng.local # 想再变黑就执行这句彻底删除bashgnome-extensions disable ime-blackfeng.local↑ 实测会自动把 ime-blackfeng.local 从 org.gnome.shell enabled-extensions 里移除不需要再手动改 gsettings也不会影响你已启用的其它扩展rm -rf ~/.local/share/gnome-shell/extensions/ime-blackfeng.local还原后系统回到未改动状态——因为整个过程没有碰过 /usr/share 下的任何文件可以用 ls -la /usr/share/gnome-shell/theme/Yaru/gnome-shell-theme.gresource 确认其修改时间仍是 2021 年。五、将来升级系统的注意事项1大版本升级后例如 Ubuntu 20.04 → 22.04 / 24.04第一件事是改 shell-version。bashgnome-shell --version # 例如 GNOME Shell 42.9把 metadata.json 里的 “shell-version”: [“3.36”] 改成 [“42”]写主版本号即可写成 “42.9” 也行不改的话扩展会被判定为「过期OUT_OF_DATE」而拒绝加载候选窗会悄悄变回白色。2GNOME 45 及以后extension.js 必须改写成 ESM 写法。45 版起删除了 imports. 老式 API老 extension.js 会直接报错。用下面这份替换 extension.jsmetadata.json 里的 shell-version 也要同步改成新版本号jsimport Main from ‘resource:///org/gnome/shell/ui/main.js’;import {Extension} from ‘resource:///org/gnome/shell/extensions/extension.js’;export default class ImeBlackExtension extends Extension {enable() {const cssPath this.dir.get_child(‘ime-black.css’).get_path();Main.setThemeStylesheet(cssPath);Main.loadTheme();}disable() {Main.setThemeStylesheet(null);Main.loadTheme();}}这份 ESM 代码是在 GNOME 45 的官方接口上写的本机3.36无法实测。若升级后发现 Main.setThemeStylesheet 在新版里被移除见下面第 4 条的备选方案。3升级后验证一遍bashgnome-extensions info ime-blackfeng.local # 期望状态 ENABLED、无 errorjournalctl --user -b | grep -i ime-black # 有报错就看这里然后在输入框里打几个字母看候选窗是否仍是纯黑。若是白的多半就是 shell-version 没改或扩展报错。4如果候选窗样式在新版里不生效通常是 GNOME 改动了候选窗的 CSS 类名或属性bash重新抽出新版主题 CSS搜索候选窗规则看类名是否还叫 candidate-popup-*cat /usr/share/gnome-shell/modes/*.json | grep -i stylesheetgresource extract 新主题.gresource 路径/gnome-shell.css /tmp/new.cssgrep -n “candidate” -A 10 /tmp/new.css把 ime-black.css 里的选择器/属性名按新版实际内容对应改一下即可。绝大多数情况下 .candidate-popup-boxpointer -arrow-background-color 这套命名是稳定的GNOME 3.36 → 4x 一直沿用。5备选方案若某天这条扩展机制走不通了安装官方扩展 gnome-shell-extension-user-theme然后把 ime-black.css 的内容改成一份完整的 Shell 主题放在 ~/.themes/名字/gnome-shell/gnome-shell.css在本机 20.04 上该包不在 apt 索引里所以当时没走这条路。或者直接改系统主题的 gresource 文件并重新打包——但这会影响登录界面等全局外观且会被系统升级覆盖升级后需重做不推荐。6其它不会被影响的点放心升级输入源配置org.gnome.desktop.input-sources与输入法本身不受本改动影响。GTK 应用的主题Yaru-dark也不受影响——候选窗属于 Shell 主题与 GTK 主题相互独立。.candidate-page-button 那几个按钮状态悬停/按下/禁用也都单独覆盖过升级 GNOME 后若按钮样式回退成亮灰按第 4 条同样方式补一下即可。六、常见问题排查现象 排查候选窗还是白的 gnome-extensions info ime-blackfeng.local 看状态若是 OUT_OF_DATE 改 shell-version若是 ERROR 看 journalctl --user -b | grep -i ime-black改了 CSS 没变化 执行 gnome-extensions disable/enable确认改的是 ~/.local/share/gnome-shell/extensions/ime-blackfeng.local/ime-black.css黑底上看不清文字 确认 color 被设成 #ffffff原主题是深灰字只改背景不改字色会「黑底黑字」黑窗在深色窗口上分不出边界 给 -arrow-border-color 设一个可见的颜色例如 #4a4a4a菜单/面板也变黑了 不该发生本方案只覆盖 .candidate-popup-* 与 .candidate-page-button与菜单用的 .popup-menu-boxpointer 是两条独立规则。若真出现检查 ime-black.css 是否被误改想确认「现在到底加载了哪个样式表」 GNOME 3.36 可用gdbus call --session --dest org.gnome.Shell --object-path /org/gnome/Shell --method org.gnome.Shell.Eval ‘let fimports.ui.main.getThemeStylesheet(); f ? f.get_path() : “null”’附关键文件清单路径 作用~/.local/share/gnome-shell/extensions/ime-blackfeng.local/metadata.json 扩展声明uuid / 名称 / shell-version~/.local/share/gnome-shell/extensions/ime-blackfeng.local/extension.js 启用/禁用时挂载或卸载样式表~/.local/share/gnome-shell/extensions/ime-blackfeng.local/ime-black.css 颜色都在这里面微调就改它~/.local/share/gnome-shell/extensions/ime-blackfeng.local/README.md 同目录简要说明~/文档/中文输入法候选窗纯黑-说明.md 本文档~/文档/ime-before-after.png 改前/改后对比图系统侧只读位置不要改路径 说明/usr/share/gnome-shell/modes/ubuntu.json 会话模式指定用哪套 Shell 主题/usr/share/gnome-shell/theme/Yaru/gnome-shell-theme.gresource