# 外观与设置

两个入口：

- **右键悬浮球**：快速换图标 / 换背景；
- **DSH 设置 →「悬浮球与外观」**：集中管理，支持纯色预设、上传图片 / GIF / 视频、裁剪、形状和大小。

## 支持项

| 项目 | 支持 | 说明 |
| --- | --- | --- |
| 界面语言 | 跟随 DSH / 中文 / English | 只影响插件页面与快捷窗口文案，不改 DSH 本体语言 |
| 悬浮球图标 | PNG / JPG / JPEG / BMP / GIF / WebP，MP4 / WMV / AVI / MOV / WebM | GIF 逐帧播放；视频按系统解码器播放；也支持纯色球 |
| 图标裁剪 | 图片 / GIF | 上传后弹出和背景一致的选框编辑器；拖动选框、四角按形状等比例缩放、滚轮缩放图片；形状也在这里选择 |
| 最近使用 | 悬浮球图标 / 聊天背景各 12 条 | 点击缩略图直接应用，右上角 `×` 删除；删除当前项时回退到默认 / 无背景 |
| 悬浮球形状 | 圆形 / 圆角方形 / 方形 / 横向长方形 / 竖向长方形 | 圆形、方形为 1:1；横向 1.5:1；竖向 1:1.5；裁剪框和 WPF 窗口同步使用该比例 |
| 悬浮球大小 | 44–84 DIP | 滑块调整短边，窗口按形状比例同步缩放，位置保持中心 |
| 聊天背景 | PNG / JPG / JPEG / GIF / BMP / WebP，或纯色 | 纯色预设不需要上传文件；图片最多 3 秒内刷新 |
| 背景图片显示 | 铺满 / 完整 / 拉伸 | `cover` 裁切填满、`contain` 完整留白、`stretch` 拉伸填充；未设置显示区域时生效 |
| 背景图片位置 | 居中 / 顶部 / 底部 / 左侧 / 右侧 | 对应 `background-position`，配合铺满 / 完整使用 |
| 背景显示区域 | 拖拽选框 + 8 个控制点 | 上传背景后自动打开，也可以点「选取显示区域」；保存为 `chatBackgroundCrop` |
| 消息窗口颜色 | 用户气泡 / AI 卡片 | 自定义背景色；文字颜色按亮度自动切换黑 / 白 |
| 助手名称 | 最多 30 个字符 | 替换 AI 回复标题和输入框里的「给 DeepSeek 发消息…」提示 |

## 行为细节

- 悬浮球图标会**同步到聊天消息里的 AI 头像**：图片 / GIF 用 `<img>`，视频用静音循环 `<video>`，纯色球显示同色底；
- 裁剪参数保存为归一化 `{x,y,w,h}`，不改写原始文件；GIF 对每一帧应用同一个矩形；视频暂不支持裁剪；
- 形状和大小保存在 `appearance.json` 的 `ballShape` / `ballSize`；`ballSize` 是短边，横向长方形窗口宽 = 短边 × 1.5 + 24、高 = 短边 + 24，竖向反之；形状随裁剪保存，大小点「应用」写入并通知悬浮球；
- 背景图片显示方式和位置保存在 `chatBackgroundFit` / `chatBackgroundPosition`；设置显示区域后保存在 `chatBackgroundCrop`，此时优先按选取区域完整显示；
- 最近上传记录保存在 `ballHistory` / `chatBackgroundHistory`，各保留 12 条，文件仍在 `%LOCALAPPDATA%\dsh-quick-chat\media\`；删除记录会同时删除对应媒体文件；
- 聊天消息颜色保存在 `chatUserColor` / `chatAiColor`，留空表示跟随主题；
- 选中的文件会复制到 `%LOCALAPPDATA%\dsh-quick-chat\media\`，原文件移动 / 删除不影响；
- 外观记录在 `%LOCALAPPDATA%\dsh-quick-chat\appearance.json`；
- 聊天背景由 Host 的 `/dsh-quick-chat-appearance` 路由提供给页面，不直接把本地路径交给 WebView2；
- 设置页保存后，悬浮球最多 1 秒内自动重载外观；聊天窗口最多 3 秒内刷新；
- 发送按钮固定使用品牌蓝 `#4d6bfe`，不跟随 DSH 主题 accent 变色；空输入时只降低透明度。

## 渲染细节

- 聊天背景是图片时，AI 回复会自动包一层不透明卡片（用户消息本来就是实色气泡），避免文字压在图上看不清；纯色背景不额外加卡片；
- 图片背景时，整个窗口从顶部深色、中间原图到底部深色渐变；顶栏和底部输入区用同一套渐变磨砂材质（`backdrop-filter`），不再出现纯白色横条；输入框下方也不再留 30px 空白；
- 纯色背景时，整个窗口用该颜色做明暗渐变，顶栏透明、输入框用同色浅色调，不再有白色横条；
- 深色纯色背景（亮度 < 128）会自动切到深色阅读模式：文字、回答卡片、输入框、菜单都变成深色底浅色字，顶栏按钮强制浅色。窗口取消了 `WS_THICKFRAME` 非客户区，缩放改由页面四边 / 四角的透明手柄下发 `dqc-resize-*`，因此不再有 1px 白边；
- 背景图片按原色显示，不叠白色蒙层；图片使用 `cover` 铺满窗口，会按窗口比例裁切；
- 悬浮球不使用 WPF 的矩形 `DropShadowEffect`，因此不会出现方形阴影；需要阴影时由图片自身或圆形边框表现。

## 已知问题

- 设置页提示「当前 Host 还是旧外观接口」：说明 DSH 主进程还没加载 0.12.x 的 schema，重启一次 DSH 后再点「应用」。