Matugen Integration.zh CN

Matugen 集成

语言： English · 简体中文

Matugen 能从一张壁纸生成 Material You 配色。seekey 可以在启动时通过在 seekey.ini 里引用这些颜色来采用它们。

生成 colors.json

只有配置了模板，Matugen 才会生成 Seekey 所需的 JSON。创建 ~/.config/matugen/templates/seekey-colors.json：

{
  "colors": {
    "surface": "{{colors.surface.default.hex}}",
    "on_surface": "{{colors.on_surface.default.hex}}",
    "outline": "{{colors.outline.default.hex}}",
    "outline_variant": "{{colors.outline_variant.default.hex}}"
  }
}

在 ~/.config/matugen/config.toml 注册模板。把 /home/you 换成真实的家目录； 使用绝对路径可以避免不同版本对路径展开方式的差异：

[config]

[templates.seekey]
input_path = '/home/you/.config/matugen/templates/seekey-colors.json'
output_path = '/home/you/.cache/matugen/colors.json'

从壁纸生成调色板：

matugen image /path/to/wallpaper.jpg --mode dark --source-color-index 0

用法

当 colors.json 可用时，可直接在 GUI 根菜单选择 使用 Matugen 配色。 GUI/TUI 的主题选择器中也有 matugen 预设，命令行可使用 --theme matugen。

这个预设等价于在颜色字段中使用 @matugen:<role> 引用 Matugen 角色：

[style]
foreground=@matugen:on_surface
background=@matugen:surface@0.86
border-color=@matugen:outline
placeholder-foreground=@matugen:on_surface@0.74

@matugen:<role> 语法会被解析成 matugen colors.json 里的 hex 值。可选的 @<float> 后缀把结果包进 alpha(<hex>, <float>)：

@matugen:surface         → #1a1a1a
@matugen:surface@0.86    → alpha(#1a1a1a, 0.86)
@matugen:missing_key     → 渲染前使用静态主题回退色

解析器会保留未知角色；渲染前 Seekey 会把仍未解析的颜色引用替换为当前 主题的静态回退颜色，因此不完整或写错的调色板不会生成无效 GTK CSS。

GUI/TUI 保存时会保留原始 @matugen: 引用，而不是写入当时解析出的 hex。 即使编辑器打开期间 colors.json 发生变化，或把配置另存到新路径，引用仍会 保持动态；在编辑器里手动改过的颜色则会按预期保存成静态覆盖。

seekey 去哪找 colors.json

解析顺序（先匹配的优先）：

1. 命令行的 --matugen <path>
2. $MATUGEN_COLORS 环境变量
3. $XDG_CACHE_HOME/matugen/colors.json（matugen 默认）
4. ~/.cache/matugen/colors.json（回退）

显式命令行路径也会传给 GUI/TUI 的预览，以及 GUI 中通过启动按键浮层 创建的进程。

换壁纸后重新加载

seekey 不会自动监视 JSON。对一张新壁纸跑完 matugen 后，重启 seekey 应用新配色：

pkill seekey && seekey &

JSON 加载失败

隐式默认文件缺失或无效时，Seekey 会向 stderr 输出一条警告，并使用静态 默认配色。显式指定的 --matugen 路径采用严格检查，无法加载时会终止启动。 Matugen 集成完全可选；没有安装 Matugen 时 Seekey 仍可正常运行。