前言
这次 AudioDock 1.2 版本更新带来了大家期待已久的换肤功能，——你只需要让 AI 写一个 JSON 文件，就能自定义桌面端大部分界面元素，包括 Header、播放器、首页、详情页，甚至连歌词对齐方式、封面渲染样式、黑胶唱针都可以控制。这篇文章就来详细讲讲怎么用、怎么写、要注意什么。
正文
一、插件是什么
UI 主题插件本质上是一个 JSON 文件，遵循我们公开的 UI 主题插件（JSON）标准 v1^[1]^（下文简称"标准"）。它的设计原则有几个：
- • 部分覆盖：缺省的键自动回退到应用默认，你只写想改的项就行。
- • 未知键保留：你写了一个当前版本 app 还不支持的键？不会报错、不会剥离，会留在存储里，等升级到支持该键的新版 app 后自动生效。
- • 向前兼容：已经发布的键名和语义永远不变，老主题永远不会失效。
- • schemaVersion 机制：未来如果出现破坏性变更，会通过
meta.schemaVersion 字段做版本约束，保证旧主题在新版 app 上仍然可用。
目前 桌面端（desktop）已经支持，移动端（mobile）的支持正在路上，会尽快跟进。
二、五步上手
-
- 打开 设置 → 插件中心 → UI 插件。
-
- 点页面里的 「下载示例主题」 按钮，拿到
audiodock-ui-theme.sample.json。
-
- 用任意编辑器打开 JSON，照着自己的喜好改颜色、改模糊半径、改歌词对齐等参数。最好的方法是告诉 AI ，让豆包网页版等 AI 工具帮你修改！
-
- 把改好的 JSON 文件拖进页面上传区，app 会自动校验 schema 并导入。
-
- 在主题列表里点 「启用」，立即生效。
如果校验失败，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": { /* ... */ } }
}
四、可控的组件命名空间
目前支持四个命名空间，每个下面都有一组固定键：
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 模式下生效）
五、几条关键规则
写主题的时候，请务必遵守以下契约（这是为了保证你的主题在以后升级的版本里持续可用）：
-
meta.schemaVersion 必须等于 app 当前版本号**。当前 = 1。上传更高版本会被拒绝。
-
- 任何键都不要删、不要改名、不要改语义。扩展只能"加"，不能"改"。
-
- 颜色值接受任意合法 CSS 颜色：包括
#xxx、#xxxxxx、rgb/rgba、hsl/hsla，以及 linear-gradient(...) 等渐变。
-
- 尺寸类键只接受非负数字（px），范围
0 ~ 10000。
-
- 枚举型键只接受允许列表里的字符串，比如
coverStyle 只能是 square 或 vinyl。
-
- 比例型键只接受
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"
}
}
}
}
完整示例可以直接在 设置 → 插件中心 → UI 主题 → 下载示例主题 拿到，编辑后重新上传即可。
最后
UI 主题插件是 AudioDock 在"个性化"方向迈出的第一步，目标是让每位用户都能用自己的方式打扮自己的客户端。我们非常欢迎社区作者贡献主题——只要遵循标准写出的 JSON，就是一份可以永久使用的主题。
后续我们会持续扩充 components 的命名空间和键位表，也会在 移动端（mobile） 跟进支持。如果你做出了漂亮的主题，欢迎通过 GitHub Issue / 公众号留言分享，我们会在社区里推荐。
完整规范文档：https://github.com/NasDock/AudioDock/blob/master/docs/ui-theme-schema.md
今天的分享就这些了，感谢大家的阅读，如果文章中存在错误的地方欢迎指正！
