fcitx5-m3ui

给 Fcitx5 用的 Material 3 风格候选框, 以界面插件(m3ui)的形式替换 classicui。

特性

• Material 3 圆角面板,深色 / 浅色主题跟随系统。
• 弹簧动画:候选框带轻微回弹从侧边滑入并淡入,高亮块在候选词之间滑动。 刚度、阻尼、方向、距离都可以调。
• 在候选词上右键打开动作菜单,内容取决于输入法提供的动作。拼音有 "忘记候选词 / 置顶为自定义短语 / 从自定义短语中删除"。
• 忘记候选词后不会再出现,包括系统词库和扩展词库里的词(见下文"屏蔽列表")。
• Wayland 和 X11(Xwayland)输入上下文都支持,定位和鼠标处理沿用 classicui。
• 可选的 KWin 辅助脚本:只缩短候选框自己的 KWin 淡出时间。

状态

个人项目,只在 Fedora 44、KDE Plasma 6.7(Wayland)、NVIDIA 显卡、 Fcitx5 5.1.23、拼音引擎上用过。动画、右键菜单、忘记候选词、开机自动启动 在这套环境里都实际用过。

scripts/build.sh 在干净目录里从零完整构建通过过一次(Fedora 44),其他发行版和桌面没有试过, 遇到问题请开 issue。

本插件是 classicui 的分支,需要在 Fcitx5 源码树内构建:Fcitx5 的 Wayland 协议封装不包含在 fcitx5-devel 里。构建用的源码版本必须和已安装的 Fcitx5 一致, Fcitx5 升级后需要重新构建;如果插件加载失败,Fcitx5 会自动退回 classicui, 不会没有输入法。

没有自己的淡出动画:Wayland 下面板没有内容时窗口会被立刻销毁。

构建

需要 Fcitx5 开发文件和 classicui 的依赖(cairo、pango、librsvg、gdk-pixbuf、 wayland-protocols、xcb 相关库)。Fedora 上:

sudo dnf install fcitx5-devel extra-cmake-modules cairo-devel pango-devel \
    gdk-pixbuf2-devel librsvg2-devel wayland-protocols-devel \
    plasma-wayland-protocols-devel systemd-devel libuuid-devel fmt-devel \
    expat-devel iso-codes-devel json-devel xkeyboard-config-devel \
    xcb-util-devel xcb-util-keysyms-devel xcb-util-wm-devel \
    xcb-util-image-devel xcb-imdkit-devel libxkbfile-devel libxkbcommon-x11-devel

然后:

scripts/build.sh      # 下载 Fcitx5、yoga 和 libmonet 源码,叠加 src/,构建 m3ui
scripts/install.sh    # 安装到 ~/.local,不改动 $HOME 以外的任何东西

build.sh 会用 pkg-config 取已安装的 Fcitx5 版本,可以用 FCITX_VERSION 覆盖。 源码是按提交哈希从 GitHub 取的并在取完后校验(标签可以被移动,提交哈希无法伪造), 没有固定提交的版本会被拒绝,除非你自己用 FCITX_COMMIT=<sha> 指定。这个插件跑在输入法进程里, 看得到你打的所有字,所以构建来源值得认真对待。

莫奈取色

候选窗的颜色由 libmonet 从桌面强调色生成(UseMonet=True,默认开), 深浅色跟随系统。输入法进程内不会启动任何子进程:直接复用 Fcitx5 自己监听的 XDG portal (KDE Plasma 6、GNOME 47+ 都有),取不到时回退到默认的粉色。UseMonet=False 回到主题文件里的固定颜色。

使用

手动试用:

FCITX_ADDON_DIRS=$HOME/.local/m3ui/lib64/fcitx5:/usr/lib64/fcitx5 fcitx5 -r -u m3ui

FCITX_ADDON_DIRS 是让 Fcitx5 找到系统目录以外的插件,fcitx5 -r(不带参数) 可以回到原版界面。

开机自动使用:

scripts/enable-autostart.sh
systemctl --user daemon-reload && systemctl --user restart app-org.fcitx.Fcitx5@autostart.service

它会在家目录里写两个覆盖文件(XDG 自启动项和 D-Bus 激活项),只改 Exec 一行。 撤销只需删掉脚本输出的那两个文件。

配置

配置文件是 ~/.config/fcitx5/conf/m3ui.conf,示例见 config/m3ui.conf.example。

键	默认值	含义
Animations	True	动画总开关
Bounce	True	关闭后移动为临界阻尼(无回弹)
SpatialStiffness	2000	移动的弹簧刚度,越大越快
SpatialDamping	62	阻尼比(百分数),越小回弹越明显
EffectsStiffness	3800	淡入的弹簧刚度
SlideDistance	22	滑入距离(像素)
SlideDirection	0	0 从左,1 从右,2 从下
Theme / DarkTheme	m3ui-light / m3ui-dark	themes/ 里的主题

主题是 classicui 主题,在 [InputPanel] 里多了几个键:SurfaceColor、 OutlineColor、HighlightFillColor、PanelRadius、ItemRadius。 SurfaceColor 完全透明时回退到 classicui 的图片绘制,所以原有的 classicui 主题仍然可用(但没有动画)。

屏蔽列表

拼音引擎的"忘记候选词"只会删除你自己打字学到的词,系统词库(sc.dict)和 扩展词库里的词是只读的,忘记之后重新输入仍会出现,当前输入状态里也一样。

所以 m3ui 在你点"忘记候选词"时,会把这个词记到 ~/.local/share/fcitx5/m3ui/blocked-words.txt(一行一个词),并在每次刷新候选 之前把它们从候选列表里摘掉。

• 按候选词的完整文字精确匹配,只隐藏这个词本身。
• 重启不会丢:文件是原子写入的(先写临时文件、fsync 再改名,中途被杀也不会留下写坏的文件), 权限是 600;某次保存失败时这个词在本次运行里仍然隐藏,下次会重试写入。
• 文件被别的程序或手动修改后会自动重新读取,不用重启。
• 只有**通过右键菜单点"忘记候选词"**才会记录。用拼音自带的快捷键(Ctrl+7)忘记的词不会被记录, 这类词如果来自系统词库,下次还会出现。
• 想恢复某个词:删掉文件里对应的一行即可。
• 这是界面层的补充。换回原版 classicui 后,这些词会重新出现。

KWin 淡出(可选,KDE Plasma)

KWin 的"渐隐弹出窗口"特效会把弹出窗口淡出 600 毫秒,候选框也被算作弹出窗口。 kwin/install-fadingpopups-override.sh 会把系统里的这个特效复制到 ~/.local/share/kwin-wayland/effects/ 并打补丁,只对窗口类 fcitx fcitx 生效: 跳过 KWin 的淡入(让 m3ui 自己的弹入动画可见),并把淡出缩短到 90 毫秒 (FADE_OUT_MS 可调)。其他弹出窗口不受影响。如果上游特效的源码变了、补丁对不上, 脚本会直接报错退出。

许可证

LGPL-2.1-or-later,见 NOTICE.md。