14款内置主题背后是什么：Amethyst Mod Manager主题系统与自定义外观开发指南

Amethyst Mod Manager 是一款 Linux 原生的游戏 Mod 管理器，它内置了一套灵活的主题系统：十余款开箱即用的外观调色板（Dark、Amethyst、Cyberpunk、OLED 等），以及一套面向开发者/玩家的自定义主题机制，让你可以用图形化编辑器从零打造属于自己的外观。本文带你弄清这些主题背后的实现原理，并给出一份完整的自定义外观开发指南。

一、快速上手：在哪里切换 Amethyst Mod Manager 主题

对普通用户来说，整个过程不需要写任何代码：

1. 打开Settings（设置）→ User Interface（用户界面）。
2. 在主题预览网格（theme gallery）里点击你喜欢的主题色块。
3. 界面会即时换肤并自动保存选择。

切换动作由 settings_view.py 里的_on_theme_changed完成——它同时做两件事：调用save_appearance_mode持久化你的选择，再调用apply_theme让整窗立即生效。

💡 小贴士：Qt 界面默认使用名为amethyst的“签名主题”（近黑底 + 紫色强调色），它的设计灵感就来自应用本身的名字。

二、内置主题一览：13 款调色板 + 自定义机制

所有内置主题都集中放在 src/themes/ 目录下，一个主题 = 一个.py文件。下表是应用随附的主题调色板（外加 1 套自定义 JSON 机制，即第“14”项能力）：

三、一个主题文件里到底藏着什么

打开任意主题文件（以 amethyst.py 为例），每个模块只需导出三个东西：

• NAME：人类可读的名称，显示在设置下拉框里。
• CTK_APPEARANCE：声明该主题是"light"还是"dark"，用于驱动内置 CustomTkinter 控件。
• PALETTE：一个{颜色键: "#hex"}字典，覆盖整个应用用到的每一处颜色。

这些键是按“角色”分组的，语义清晰，例如：

• 背景层：BG_DEEP、BG_PANEL、BG_HEADER、BG_ROW…
• 强调色：ACCENT、ACCENT_HOV、TEXT_ON_ACCENT
• 文本：TEXT_MAIN、TEXT_DIM、TEXT_OK/TEXT_ERR/TEXT_WARN
• 语义按钮：BTN_DANGER/BTN_SUCCESS/BTN_WARN/BTN_INFO…
• 状态高亮：文件冲突FILE_WIN/FILE_LOSE、插件循环状态、跨面板冲突高亮等。

⚠️ 铁律：每个键必须在所有主题文件中都存在。缺一个键，切到该主题时对应 UI 就会破相。官方源码注释也反复强调了这一点。

四、主题是如何被加载与自动发现的

主题发现逻辑全部在 src/themes/init.py 中：

• load_palettes()用pkgutil扫描 src/themes/ 下的每一个.py模块，只要它带有一个PALETTE字典就会被收录，theme_id 就是去掉.py的文件名（如dark、light）。
• 容错优先：格式错误的主题文件（缺PALETTE/NAME或导入报错）会被跳过并打印警告，而不会让应用崩溃。
• 扫描完内置主题后，它还会合并load_custom_palettes()读到的用户 JSON 主题。
• load_display_names()则收集每个主题的显示名；get_ctk_appearance()读取每个主题声明的明/暗模式，缺失时安全回退到"dark"。

在 Qt 端，调色板数据被 theme_qt.py 直接复用——它把这份“与工具无关”的颜色字典翻译成一份 QSS 样式表，而不是重复维护一套颜色。其中还内置了实时换肤的巧妙机制：给控件样式里的颜色值嵌入一个 CSS 注释标记（@amm-theme:KEY），当主题变更时可精准替换对应角色，无需重建整个界面。

五、自定义外观开发指南（从零打造主题）

这里有两条路径，按需选择。

方式 A：贡献一个内置 Python 主题

适合熟悉代码、想让主题随应用分发的人。按 src/themes/init.py 顶部注释的“四步法”：

1. 复制一个现有文件（如dark.py）为新文件，例如solarized.py。
2. 修改NAME常量和PALETTE里的色值。
3. 保留全部键——一个都不能少。
4. 保存即可，主题会在启动时被自动发现，无需改动其他代码。

方式 B：用图形化编辑器制作 JSON 自定义主题（推荐新手）

这是官方为普通玩家准备的路径，完全可视化：

1. 在Settings → User Interface里点击 “Edit / Create Theme…”，打开全屏主题编辑器（入口见 settings_view.py 的_open_theme_editor）。
2. 选一个“Start from”基础主题（任意内置或已有自定义主题）。
3. 颜色按角色分组展示；改一个基础色，其 hover/深色调变体会自动联动重算（配色数学逻辑在 theme_editor_groups.py）。
4. 右侧是实时预览面板（theme_preview.py），按钮、输入框、列表、进度条都会即时反映你的修改。
5. 点Save / Save As落盘。

保存时，主题以 JSON 形式写入用户配置目录（遵循 XDG 规范，见 config_paths.py）：

~/.config/AmethystModManager/themes/<主题名>.json

JSON 结构非常简洁（详见 custom.py 的 schema）：

{ "NAME": "My Theme", "CTK_APPEARANCE": "dark", "PALETTE": { "BG_DEEP": "#101010", "ACCENT": "#8b5cf6" } }

• 自定义主题的 id 带custom:前缀命名空间，永远不会和内置 id 冲突。
• 用Save As会基于名字去重（my-theme→my-theme-2），保证不会覆盖已有主题。
• 因为保存在 App 包外，应用更新后你的自定义主题依旧保留，还能当作单个文件分享。

六、常见问题排查

• 切到某主题后出现“破相”/空白色：多半是某个PALETTE键缺失或色值非法，回到该主题文件核对键是否齐全。
• 我的 JSON 主题没出现在列表里：确认文件位于~/.config/AmethystModManager/themes/，且含非空PALETTE字典；格式错误的文件会被跳过并在日志里打印警告。
• 想让浅色主题的 hover 更深：编辑器在非“Fine tune”模式下会根据源主题明暗自动决定变体变浅还是变深，放心用图形化模式调整即可。

小结

Amethyst Mod Manager 的主题系统把“外观”抽象成了一份与工具无关的调色板字典：内置 13 款.py主题开箱即用 + 1 套图形化 JSON 自定义机制，靠启动时自动发现和容错加载保证稳定。无论你是只想换个皮肤的玩家，还是想动手开发新主题的开发者，都能在 src/themes/ 与主题编辑器里找到清晰、低门槛的入口。