声仓 1.2 版本 UI 主题插件使用说明!开启你的个性主题吧!

前言

这次 AudioDock 1.2 版本更新带来了大家期待已久的换肤功能，——你只需要让 AI 写一个 JSON 文件，就能自定义桌面端大部分界面元素，包括 Header、播放器、首页、详情页，甚至连歌词对齐方式、封面渲染样式、黑胶唱针都可以控制。这篇文章就来详细讲讲怎么用、怎么写、要注意什么。

正文

一、插件是什么

UI 主题插件本质上是一个 JSON 文件，遵循我们公开的 UI 主题插件（JSON）标准 v1^[1]（下文简称"标准"）。它的设计原则有几个：

• 部分覆盖：缺省的键自动回退到应用默认，你只写想改的项就行。
• 未知键保留：你写了一个当前版本 app 还不支持的键？不会报错、不会剥离，会留在存储里，等升级到支持该键的新版 app 后自动生效。
• 向前兼容：已经发布的键名和语义永远不变，老主题永远不会失效。
• schemaVersion 机制：未来如果出现破坏性变更，会通过 meta.schemaVersion 字段做版本约束，保证旧主题在新版 app 上仍然可用。

目前 桌面端（desktop）已经支持，移动端（mobile）的支持正在路上，会尽快跟进。

二、五步上手

1. 打开 设置 → 插件中心 → UI 插件。

2. 点页面里的 「下载示例主题」 按钮，拿到 audiodock-ui-theme.sample.json。

3. 用任意编辑器打开 JSON，照着自己的喜好改颜色、改模糊半径、改歌词对齐等参数。最好的方法是告诉 AI ，让豆包网页版等 AI 工具帮你修改！

4. 把改好的 JSON 文件拖进页面上传区，app 会自动校验 schema 并导入。
5. 在主题列表里点 「启用」，立即生效。

如果校验失败，app 会提示具体原因；颜色格式不对、尺寸超出范围、枚举值不在允许列表里都会被单独忽略，不会让整个主题报废。

三、JSON 标准结构

一个完整的主题 JSON 长这样：

{  "meta": {    "name": "Midnight Glass",    "author": "your-name",    "version": "1.0.0",    "schemaVersion": 1,    "description": "半透明深色玻璃风示例",    "homepage": "https://github.com/you/midnight-glass"  },  "light": { "global": { /* ... */ }, "components": { /* ... */ } },  "dark":  { "global": { /* ... */ }, "components": { /* ... */ } }}

meta 段：主题元信息。name 必填，schemaVersion 必填且必须等于 app 当前支持的版本号（当前 = 1），其它字段可选。

light / dark 段：分别对应浅色模式和深色模式。整个段可缺省，缺省时该模式完全回退到默认主题。

global 段：影响全局，会注入到 antd 的 token 体系，包括 colorPrimary、colorBgBase、colorText、colorBorder、borderRadius、fontFamily 等。

components 段：按命名空间区分的局部样式，映射到一组 --ad-* CSS 变量，对应界面上的 Header、播放器、首页、详情页。

四、可控的组件命名空间

目前支持四个命名空间，每个下面都有一组固定键：

header — 顶部导航栏

• background：Header 背景（颜色或渐变）
• blur：背景模糊半径（px）
• textColor：文本颜色
• activeColor：焦点/激活态背景
• border：通用边框/分隔线

player — 底部播放器

• background / blur / textColor
• progressColor：播放进度条颜色
• controlColor：播放控件颜色

home — 首页

• background：首页背景
• cardBackground / cardHoverBackground：卡片背景及悬停态
• titleColor：标题颜色

detail — 详情页（最丰富）

• background / blur / controlsBackground / controlsTextColor
• lyricsAlign：枚举 left / center / right，控制歌词对齐
• lyricsColumnRatio：0-1 的小数，歌词栏占全屏宽度比例（封面占 1 - 比例）
• lyricsFontSize：常规歌词字号（px），当前行自动 +2px
• coverStyle：枚举 square / vinyl，封面渲染样式（vinyl 为黑胶唱片）
• tonearm：枚举 none / basic，黑胶唱针装饰（仅 vinyl 模式下生效）

五、几条关键规则

写主题的时候，请务必遵守以下契约（这是为了保证你的主题在以后升级的版本里持续可用）：

1. meta.schemaVersion 必须等于 app 当前版本号。当前 = 1。上传更高版本会被拒绝。
2. 任何键都不要删、不要改名、不要改语义。扩展只能"加"，不能"改"。
3. 颜色值接受任意合法 CSS 颜色：包括 #xxx、#xxxxxx、rgb/rgba、hsl/hsla，以及 linear-gradient(...) 等渐变。
4. 尺寸类键只接受非负数字（px），范围 0 ~ 10000。
5. 枚举型键只接受允许列表里的字符串，比如 coverStyle 只能是 square 或 vinyl。
6. 比例型键只接受 0 ~ 1 范围的数字，比如 lyricsColumnRatio。

不合法的值会被 app 单独忽略并提示 warning，不会让整个主题失效。

六、一个完整的玻璃风示例

下面这段是内置的 Midnight Glass 示例主题（节选 dark 模式），演示了怎么覆盖全局颜色 + Header + Player + Home + Detail 的关键项：

{  "meta": {    "name": "Midnight Glass (Sample)",    "author": "AudioDock",    "version": "1.0.0",    "schemaVersion": 1,    "description": "半透明深色玻璃风示例"  },  "dark": {    "global": {      "colorPrimary": "#7c5cff",      "colorBgBase": "#0d0d12",      "colorText": "#e6e6eb",      "colorTextSecondary": "#9a9aa5",      "colorBorder": "rgba(255,255,255,0.12)",      "borderRadius": 10    },    "components": {      "header": {        "background": "rgba(20,20,28,0.55)",        "blur": 24,        "textColor": "#e6e6eb",        "activeColor": "#7c5cff",        "border": "rgba(255,255,255,0.10)"      },      "player": {        "background": "rgba(20,20,28,0.55)",        "blur": 24,        "textColor": "#e6e6eb",        "progressColor": "#7c5cff",        "controlColor": "rgba(255,255,255,0.12)"      },      "home": {        "background": "rgba(20,20,28,0.45)",        "cardBackground": "rgba(255,255,255,0.05)",        "cardHoverBackground": "rgba(255,255,255,0.10)",        "titleColor": "#e6e6eb"      },      "detail": {        "background": "rgba(20,20,28,0.45)",        "blur": 20,        "controlsBackground": "rgba(255,255,255,0.08)",        "controlsTextColor": "#ffffff",        "lyricsAlign": "center",        "lyricsColumnRatio": 0.6,        "lyricsFontSize": 18,        "coverStyle": "vinyl",        "tonearm": "basic"      }    }  }}

从示例里能看到几个常用写法：

• 毛玻璃背景：用 rgba(..., 0.55) + blur: 24 实现半透明 + 高斯模糊。
• 主色统一：colorPrimary 和各命名空间的 activeColor / progressColor 用同一个值，整套配色就协调了。
• 封面变成黑胶：detail.coverStyle: "vinyl" + tonearm: "basic"，播放时唱针摆入贴盘、暂停时抬起。
• 歌词占屏幕六成：lyricsColumnRatio: 0.6，左 40% 给封面，右 60% 给歌词。

完整示例可以直接在 设置 → 插件中心 → UI 主题 → 下载示例主题 拿到，编辑后重新上传即可。

最后

UI 主题插件是 AudioDock 在"个性化"方向迈出的第一步，目标是让每位用户都能用自己的方式打扮自己的客户端。我们非常欢迎社区作者贡献主题——只要遵循标准写出的 JSON，就是一份可以永久使用的主题。

后续我们会持续扩充 components 的命名空间和键位表，也会在 移动端（mobile） 跟进支持。如果你做出了漂亮的主题，欢迎通过 GitHub Issue / 公众号留言分享，我们会在社区里推荐。

完整规范文档：docs/ui-theme-schema.md^[2]

今天的分享就这些了，感谢大家的阅读，如果文章中存在错误的地方欢迎指正！

往期精彩推荐

• 声仓 Beta 版本更新计划说明！
• 声仓，让声音触手可及！
• BookDock 正式发布！附详细安装教程！
• 更多精彩文章欢迎关注我的公众号

引用链接

[1] UI 主题插件（JSON）标准 v1: https://github.com/mmdctjj/AudioDock[2] `docs/ui-theme-schema.md`: https://github.com/mmdctjj/AudioDock/blob/main/docs/ui-theme-schema.md