# 10 — 颜色选项块、取色器、翻转，以及音频两条路互斥

Status: resolved
Type: task

## 需求（用户原话）

> 翻转是wallpaper engine自带的属性，我们也要加上，背景音乐选择我们可以选择在 project.json 中添加一个 使用自定义音乐 框选项，为真时展示 音频文件路径，隐藏 背景音乐选择，反之则相反。另外补充一下这些控件的细节

附三张官方面板细节图：取色器弹层、显示颜色选项展开后的四个滑杆、壁纸预设切换的下拉。

## ① 翻转：WE 自带的属性

`翻转` **不在** `project.json` 的属性表里——它是 WE 对网页壁纸自带的一行。同理的还有
`显示颜色选项` 与它展开后的 `亮度 / 对比度 / 饱和度 / 色调偏移`。面板现在把它们长在
**color 属性所在的位置**上，顺序天然与官方一致：

```
主题配色（作者的 color 属性） → 翻转 → 显示颜色选项 → [亮度/对比度/饱和度/色调偏移] → ───
```

四个滑杆都是 0–100、默认 50（= 不改变），只在「显示颜色选项」勾上时出现。

**效果落在 `body` 上**：翻转 = `transform: scaleX(-1)`，颜色选项 = CSS `filter`
（`brightness/contrast/saturate/hue-rotate`）。作用在 body 才能连背景图一起处理，
只改 `#spine-container` 会漏掉背景。

由此带来一个必须记住的副作用：**面板与取色器挂到 `<html>` 下，不能挂在 body 里**。
body 上一旦有 `transform` / `filter`，就会给 `position: fixed` 的后代造出新的包含块，
面板会跟着壁纸一起被翻转、被调色。

## ② 使用自定义音乐：两条路互斥

`project.json` 新增 `use_custom_audio`（bool，默认 false），并把两个音源属性做成互斥条件：

| 属性 | condition |
| --- | --- |
| `audio_file` / `audio_file_note` | `use_custom_audio.value == true` |
| `bgm` / `bgm_note` | `use_custom_audio.value == false` |

运行时同步改掉音源优先级：原来是无条件「自填 URL > bgm > 预设默认」，现在是

```ts
const picked = state.useCustomAudio ? state.audioSource : bgmSource(preset);
const source = picked || preset.audioOptions.source;
```

两条都空时仍回落本壁纸默认音源——否则开关一打开就彻底没声音了。

### 这会让发布产物变化，是有意为之

`general.properties` 因此与线上已发布版本（workshopid 3604974793 / version 3）不再逐字段相同。
`tools/checks/diff-project.mts` 会报 13 处差异，逐条核对过，**全部**来自这次新增：
`use_custom_audio`、四处 `condition`、以及随之顺延的 `index`/`order`。顶层键序未变，没有夹带别的改动。

（ADR 0005 里"构建产物必须与线上逐字段一致"那条约束，到此完成了它的历史使命——它是为了防止
重构过程中**意外**改动产物，不是禁止有意的功能更新。下次上传就是一个新版本。）

## ③ 控件细节

**取色器弹层**（点「主题配色」的色块弹出）：调色板 3×5 + 明度/饱和度方块 + 色相条 +
十六进制输入 + 确认/取消。挂在 `<html>` 下，理由同上。开在色块**左侧**——面板本身贴右边缘，
往右开就出屏了。

**下拉**：用 `color-scheme: dark` 让原生 select 的弹出层也走深色，与官方那个深色高亮当前项的
下拉一致，没有自己造一套下拉控件。

## 验证

`tools/checks/verify-panel.mts` 扩到 8 组断言，全部通过：

- 行序逐字比对：主题配色 / 翻转 / 显示颜色选项 / 显示作者信息 / 壁纸预设切换 / 音频音量调整 / 使用自定义音乐 / 背景音乐选择
- 勾「显示颜色选项」→ 出现四个滑杆（共 5 个 range）；亮度落到 `body.style.filter`、翻转落到 `body.style.transform`
- 面板与取色器都在 `document.documentElement` 下（不会被 body 的滤镜波及）
- 取色器：15 个色块、有 SV 方块与色相条、十六进制有值、底部确认/取消；确认后写回 `schemecolor`（`r g b` 浮点）并关闭
- `使用自定义音乐` 开 → 音频文件路径出现、背景音乐选择消失；关 → 反过来
- 重置 / 取消 / 确认三种语义

其余回归全绿：`pnpm check`、调试服与浏览器冒烟、四档自包含包 `file://`、静态托管预览、
6 组渲染与重构前逐像素相同、预设引用解析一致。