中文输入法候选窗「纯黑背景」配置说明
机器环境：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.js，ibus 只负责把候选词算出来发过来）。它的外观完全由 Shell 主题 CSS 决定。

本机 ibus 的启动参数是 ibus-daemon --panel disable --xim，即禁用了 ibus 自带的 GTK 面板，候选窗交给 Shell。所以：

改 ibus 的配置（~/.config/ibus/…）没有用；
该改的是 Shell 主题里 .candidate-popup-* 这几条 CSS 规则。
本机当前使用的 Shell 主题由会话模式决定：

bash
cat /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 里，可以抽出来查看（只读，不改动系统文件）：

bash
gresource extract /usr/share/gnome-shell/theme/Yaru/gnome-shell-theme.gresource
/org/gnome/shell/theme/Yaru/gnome-shell.css > /tmp/yaru-light.css
grep -n “candidate-” -A 8 /tmp/yaru-light.css
二、本机实际做了什么（完整步骤，可在别的机器复现）
2.1 确认环境

bash
cat /etc/os-release | head -3 # Ubuntu 20.04.6 LTS
gnome-shell --version # GNOME Shell 3.36.9
ps -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。

bash
mkdir -p ~/.local/share/gnome-shell/extensions/ime-black@feng.local
三个文件（内容见下节），作用是把一段 CSS 作为 application stylesheet 叠加到系统 Yaru 主题之上——它只覆盖候选窗相关规则，菜单、面板等其余界面保持原样。

2.3 三个文件的内容
metadata.json

json
{
“uuid”: “ime-black@feng.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.js（GNOME 3.38 及更早的写法，用 imports. 老式 API）

js
const 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.css

css
/* 候选窗本体：背景 + 边框 + 指向光标的箭头，全部纯黑 */
.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 启用并让它生效

bash

1) 写入「已启用」列表（也就是设置里的开关）

gnome-extensions enable ime-black@feng.local

2) 确认状态

gnome-extensions info ime-black@feng.local # 状态: ENABLED
gsettings get org.gnome.shell enabled-extensions

→ [‘ime-black@feng.local’]

两种生效方式：

重新登录 / 重启后：Shell 启动时自动按上面的列表加载，无需任何额外操作（这是常态，装完就不用管了）。
当前会话立即生效（不想重新登录）：GNOME 3.36 允许通过 Shell 自己的 D-Bus Eval 调用同一套 API：

bash
gdbus 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-black@feng.local/ime-black.css”); M.loadTheme(); “ok”’
本机就是这么让它立即生效的。注意：Eval 在新版 GNOME（约 41+）默认被禁用（需要 unsafe mode），那时改用「重新登录」或 gnome-extensions disable/enable 即可。

2.5 验证
切到拼音输入源（Super+Space），在任意输入框里打几个字母，例如 nihao，候选窗出现。
截图后统计像素，确认背景确实是纯黑而不是深灰：

bash
gnome-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-color
3.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-black@feng.local/ime-black.css

gnome-extensions disable ime-black@feng.local
gnome-extensions enable ime-black@feng.local
这两条命令会让扩展重新执行 enable()，从而重新读取 CSS 文件并刷新主题，不需要重新登录。

四、还原 / 卸载
临时关掉（保留文件，随时再打开）：

bash
gnome-extensions disable ime-black@feng.local

候选窗立刻恢复系统原样（白底深字）

gnome-extensions enable ime-black@feng.local # 想再变黑就执行这句
彻底删除：

bash
gnome-extensions disable ime-black@feng.local

↑ 实测会自动把 ime-black@feng.local 从 org.gnome.shell enabled-extensions 里移除，

不需要再手动改 gsettings，也不会影响你已启用的其它扩展

rm -rf ~/.local/share/gnome-shell/extensions/ime-black@feng.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。

bash
gnome-shell --version # 例如 GNOME Shell 42.9

把 metadata.json 里的 “shell-version”: [“3.36”] 改成 [“42”]

（写主版本号即可；写成 “42.9” 也行）

不改的话，扩展会被判定为「过期（OUT_OF_DATE）」而拒绝加载，候选窗会悄悄变回白色。

2）GNOME 45 及以后：extension.js 必须改写成 ESM 写法。

45 版起删除了 imports. 老式 API，老 extension.js 会直接报错。用下面这份替换 extension.js（metadata.json 里的 shell-version 也要同步改成新版本号）：

js
import 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）升级后验证一遍：

bash
gnome-extensions info ime-black@feng.local # 期望：状态 ENABLED、无 error
journalctl --user -b | grep -i ime-black # 有报错就看这里
然后在输入框里打几个字母，看候选窗是否仍是纯黑。若是白的，多半就是 shell-version 没改或扩展报错。

4）如果候选窗样式在新版里不生效（通常是 GNOME 改动了候选窗的 CSS 类名或属性）：

bash

重新抽出新版主题 CSS，搜索候选窗规则，看类名是否还叫 candidate-popup-*

cat /usr/share/gnome-shell/modes/*.json | grep -i stylesheet
gresource extract <新主题.gresource> <路径/gnome-shell.css> > /tmp/new.css
grep -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-black@feng.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-black@feng.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 f=imports.ui.main.getThemeStylesheet(); f ? f.get_path() : “null”’
附：关键文件清单
路径 作用
~/.local/share/gnome-shell/extensions/ime-black@feng.local/metadata.json 扩展声明（uuid / 名称 / shell-version）
~/.local/share/gnome-shell/extensions/ime-black@feng.local/extension.js 启用/禁用时挂载或卸载样式表
~/.local/share/gnome-shell/extensions/ime-black@feng.local/ime-black.css 颜色都在这里面，微调就改它
~/.local/share/gnome-shell/extensions/ime-black@feng.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