Configuration.zh CN

配置

语言： English · 简体中文

Seekey 读单个 INI 文件。设置也可以在命令行覆盖。大多数人只会动几个键。

配置从哪来

查找顺序（先匹配的优先）：

1. 命令行的 --config <path>（最高优先级）
2. --xdg：$XDG_CONFIG_HOME/seekey/config.ini，通常是 ~/.config/seekey/config.ini
3. <cwd>/seekey.ini —— 你运行 seekey 的目录下的项目级文件
4. 内置默认值（不读也不写文件）

只有传入 --xdg 才会使用 XDG 配置。安装生成的 desktop 文件会传这个参数， 因此从应用菜单启动时固定使用用户配置；直接运行 seekey 仍保留项目目录行为。

普通运行、打印和校验时，显式传入的 --config 路径必须已经存在；路径写错会直接 报错，而不是悄悄使用默认值。--init-config、--config-gui 和 --config-tui 可以有意指向新路径，并在保存时创建它。没有选中任何文件时，--validate-config 同样会报错。

想一次性引导一个 XDG 配置？./seekey --init-config --xdg 会写一次 ~/.config/seekey/config.ini。

管理配置文件

./seekey --print-config         # 显示生效配置 + 来源
./seekey --validate-config      # 校验配置并退出
./seekey --init-config          # 用当前设置生成 ./seekey.ini
./seekey --init-config --force  # 覆盖已有文件
./seekey --init-config --xdg    # 一次性引导 ~/.config/seekey/config.ini
./seekey --config-tui           # 在终端里交互式编辑
./seekey --config-gui           # 在图形菜单里编辑

--print-config 会打印头部显示配置来源：

# source: file
# path: /home/you/project/seekey.ini
[general]
...

仓库里有完整注释的示例：seekey.ini.example。

命令行覆盖

大多数设置可以在命令行设置（覆盖文件值）。完整列表运行 ./seekey --help。常用项：

参数	作用
--config <path>	用这个配置文件
--matugen <path>	用这个 matugen colors.json
--xdg	使用 $XDG_CONFIG_HOME/seekey/config.ini
--config-gui / --config-tui	打开带实时浮层预览的编辑器
--no-layer-shell	强制降级窗口模式
--debug-input	把原始输入事件打到 stderr
--duration <ms>	气泡可见时长（100–10000）
--typing-idle <ms>	结束一段打字的停顿（100–5000）
--typing-display full|masked|off	控制是否显示普通输入文字
--fade-ms <ms>	淡出时长（0–3000；0 = 立即）
--margin <px>	底边距
--margin-horizontal <px>	侧边距（align=center 时忽略）
--max-items <n>	屏上最大气泡数（1–20）
--align left|center|right	气泡行对齐
--disappear instant|fade	移除动画
--layer-shell auto|required|off	layer-shell 模式
--theme <name>	主题预设
--merge-repeats / --no-merge-repeats	重复键堆成 "x3"
--merge-modifiers / --no-merge-modifiers	合并修饰键气泡
--show-mouse / --no-mouse	显示鼠标点击/滚动
-V、--version	打印版本
-h、--help	打印帮助

常用设置（大多数人只需要这些）

[general]
duration-ms=1200          # 气泡可见多久
typing-idle-ms=650        # 下一个字符开新气泡前的停顿
typing-display=full       # full / masked / off
fade-ms=180               # 淡出时长（0 = 立即）
margin=96                 # 底边距（layer-shell 模式）
margin-horizontal=0       # 侧边距
max-items=5               # 同时最多气泡数
layer-shell=auto          # auto / required / off
theme=default             # default, nord, dracula, catppuccin, monokai, light, matugen
merge-repeats=true        # "Ctrl+C x3" 而不是三个单独气泡
merge-modifiers=true      # "Ctrl" → "Ctrl+C" 而不是两个气泡
show-mouse=false          # 鼠标气泡默认关

[style]
align=right               # right / center / left
disappear=fade            # fade / instant

每个键的类型、范围、默认值见 Configuration-Reference.zh-CN。颜色、主题、按键图标见 Themes-and-Icons.zh-CN。

按键气泡怎么分组

两个行为决定你看到的样式：

• merge-repeats —— 重复按同一个组合会堆进一个气泡并计数：[ Ctrl+C ] → [ Ctrl+C x3 ]，而不是三个气泡。
• merge-modifiers —— 只含修饰键的气泡（[ Ctrl ]）在你接着按非修饰键时会被原地扩展成 [ Ctrl+C ]，而不是新开一个气泡。
• 打字分组 —— 连续字符键会收进一个文字气泡（[ hello world ]）。停顿超过 typing-idle-ms 后，下一个字符开新气泡。

输入文字隐私

typing-display 控制普通字符输入，但不会隐藏快捷键：

• full 保持原有的文字拼接行为。
• masked 在一段连续输入期间只显示固定的 <若干字符> 气泡；标签不会随 输入增长，因此不会暴露字符数量。
• off 不为普通字符创建气泡；Ctrl+C 等快捷键、修饰键、方向键、Enter 和其他非文字键仍会显示。

GUI/TUI 预览会真实反映这个设置。处于 masked 或 off 时， --debug-input 也不会输出普通字符事件。Seekey 仍需从 evdev 读取按键来判断 事件类型；该设置控制的是显示和调试输出，并不关闭输入设备访问。

文件格式注意

• 以 # 或 ; 开头的行是注释。
• 段落是 [general]、[style]、[icons]。
• 布尔值是 true / false。
• 颜色接受 GTK CSS：#rrggbb、命名 CSS 颜色、或 alpha(#rrggbb, 0.86)。
• 任何颜色字段都能用 @matugen:<role> —— 见 Matugen-Integration.zh-CN。

缺失、旧版和损坏配置

• 隐式/项目配置不存在时不是错误，会使用内置默认值。--config 指向不存在的 文件时也可把它作为之后的保存位置。
• 默认 Matugen 缓存不存在时会忽略；显式传给 --matugen 的路径必须存在且是 有效 JSON。
• CLI 解析后会再次解析 --theme matugen，因此直接启动浮层会使用生成配色； --init-config 保存时仍保留动态的 @matugen: 引用。
• INI 语法错误、非法布尔值、越界数字、未知主题、未知 typing-display 模式和 过长字符串都会明确报错， 不再静默截断或转换。
• 0.2.0 曾使用的 [style] window-width / window-height 仍能读取；保存后会 规范到 [general]。
• GUI/TUI 保存时会保留注释、未知键和未修改的 @matugen: 引用。原本缺省、 继承主题的颜色仍保持缺省，因此之后修改 theme 会正常生效；从 [icons] 删除的覆盖也不会在保存后重新出现。
• 显式 --matugen 路径会继续传给编辑器预览，以及从 GUI 启动的按键浮层。