dsh-skin-live
dsh-skin-live
把一张图片或一段视频铺满整个 DSH Web 界面 —— 只改背景，不动布局。
插件在页面最底层挂一个固定画布，把应用本身的底色透明化，于是主区域和侧栏共用同一张背景；卡片、输入框、弹层仍留在原位置、原尺寸，只是变成了半透明玻璃。所有参数存在浏览器本地，素材不上传、不联网。
- 图片：
PNG JPG JPEG WebP GIF AVIF BMP SVG
- 视频：
MP4 WebM OGV MOV M4V MKV（静音、循环、自动播放）
- 也可以直接填一个图片 / 视频 URL，素材不用下载到本地
- 四项独立调节：面板不透明度、素材不透明度、模糊、暗化
- 停用或卸载插件后，背景层被移除、主题变量还原，界面回到默认外观
图层原理示意
目录
安装
DSH 自带插件管理器，三种来源都支持。任选一种即可，不需要手改配置文件。
方式一：Web 插件页（推荐，不用命令行）
-
打开 DSH Web 界面（默认 http://127.0.0.1:3080）。
-
左侧栏进入 插件（Plugins）页。
-
在安装输入框里粘贴下面这一行，确认安装：
github:zhaochaorui-study/dsh-skin-live
-
安装完成后插件会默认启用；如果列表里显示未启用，手动打开它的开关。
-
刷新页面（Cmd/Ctrl + R），设置里就会出现「皮肤」。
方式二：命令行
dsh plugin --profile web add github:zhaochaorui-study/dsh-skin-live
发布到 npm 之后，也可以直接用包名：
dsh plugin --profile web add dsh-skin-live
--profile web 是目标 profile 名。桌面版换用 --profile desktop（尚未验证）。
方式三：离线安装包 .tgz
不想联网或想固定版本时，从 Releases 下载 dsh-skin-live-1.0.0.tgz，然后：
dsh plugin --profile web add /绝对路径/dsh-skin-live-1.0.0.tgz
也可以在插件页选择这个本地文件安装。
验证安装
dsh plugin --profile web list | grep dsh-skin-live
dsh --profile web --dump-config | grep -A2 'dsh-skin-live'
预期能看到 dsh-skin-live 这一条依赖，以及一个 id: dsh-skin-live 的加载项。
使用
界面里的路径是 设置 → 皮肤。
- 选择背景 —— 点「选择文件」上传，或把图片 / 视频直接拖进虚线框；也可以在输入框里粘贴素材 URL。
- 调节参数 —— 按下面的表格拖动滑块，画面实时变化。
- 自动保存 —— 参数写入
localStorage，素材写入 IndexedDB，刷新或重启 DSH 后自动恢复。
首版的完整流程就是这三步：安装插件 → 选择背景 → 调整模糊和暗化。
参数说明
| 控件 | 范围 | 作用 |
|---|
| 启用皮肤 | 开 / 关 | 临时关掉背景层并还原主题，素材和参数都保留，随时开回来 |
| 背景来源 | 文件 / URL | 本地文件存进 IndexedDB；URL 每次加载时直接引用 |
| 铺满方式 | 铺满 / 完整 / 拉伸 | 对应 object-fit: cover / contain / fill |
| 面板不透明度 | 0–100% | 只作用于卡片、输入框、弹层等面板表面；0% 为全透明，100% 为当前主题原色 |
| 素材不透明度 | 10–100% | 背景图片 / 视频本身的透明度 |
| 模糊 | 0–40px | 只模糊背景层，文字保持清晰（模糊时自动放大 6% 避免边缘露白） |
| 暗化 | 0–80% | 在背景上叠一层黑色蒙版，深色主题下更好读 |
侧栏属于全局背景画布，所以它跟随背景显示；「面板不透明度」不会把它单独盖掉。
兼容范围
| 环境 | 状态 |
|---|
DSH 0.2.0-rc.2 + Web / PWA | ✅ 已实测 |
DSH Desktop（--profile desktop） | ⚠️ 未验证，按需自行确认 |
| 更早的 DSH 版本 | 未验证；插件依赖 slots / theme / locale 三个客户端服务 |
实现上刻意不声明 peerDependencies，避免 DSH 运行时升级后出现版本互斥拒绝安装；服务缺失或接口变化时，插件会退化为无背景，不会影响主界面正常使用。
主题相关的实现依赖 DSH 的主题服务（theme.overrideTokens）、调色板变量（--dsw-alias-*、--dsw-specific-*）和插槽 / 语言服务，DSH 升级后如果变量被重命名，面板不透明度会回落到主题默认值（不会出现错误颜色）。
卸载与回滚
停用（保留数据）：插件页关掉开关，或在设置里关掉「启用皮肤」——背景立刻还原，参数和素材都还在。
彻底卸载：
dsh plugin --profile web remove dsh-skin-live
然后在插件页确认它已从列表消失，刷新页面。卸载后 localStorage / IndexedDB 里的参数与素材可以手动清理：
// 浏览器开发者工具 Console
localStorage.removeItem('dsh-skin-live:settings:v1');
indexedDB.deleteDatabase('dsh-skin-live:media');
数据与隐私
- 参数：
localStorage 键 dsh-skin-live:settings:v1
- 素材：
IndexedDB 库 dsh-skin-live:media，对象仓库 blobs，键 current
- 插件不发起任何网络请求，也不上报数据。填 URL 时，素材由浏览器按该地址直接加载。
从早期本地版 @local/dsh-skin-live 升级过来时，旧键 @local/dsh-skin-live:settings:v1 和旧库 @local/dsh-skin-live:media 里的内容会被自动沿用并复制一份到新名字下；旧数据不会被删除，方便回退到旧版本。
与其它皮肤插件共存
如果同时装了另一套皮肤系统（例如 @linxin666/dsh-client-ui-skin-center），两边都会改写背景和主题变量，会互相覆盖。建议只保留一套。
本地开发
仓库结构：
.
├── package.json # dsh 清单：bundle patch、client 入口、注入的客户端服务
├── index.js # Host 半边：只提供 Loader 条目，不做事
├── client.js # Client 半边：背景层、主题 token、设置页（全部逻辑）
├── client.test.js # 回归测试（node:test + 最小 DOM/IndexedDB 夹具）
├── cordis.patch.yml # 插件挂载声明
├── locale/ # 设置页文案
└── icon.svg # 插件图标
跑检查：
npm run check # 两个入口的语法检查
npm test # 9 项回归测试
npm pack # 产出可安装的 .tgz
手工 link 到本机 profile 调试、以及从旧版本迁移本机配置的完整步骤，见 INSTALL.md。
设计取舍
- 背景层是
position: fixed; z-index: -1 且 pointer-events: none 的独立节点，挂在 document.body 上 —— 这是既能垫在整个应用之下、又不影响页面原有布局的唯一位置。
- 面板半透明走主题变量覆盖（
theme.overrideTokens），逐个 token 读取当前主题的真实色值再混入透明度；主题没定义的 token 直接跳过，而不是猜一个颜色。
- 所有副作用都挂在
ctx.effect 上，插件卸载时移除 DOM、撤销 token 覆盖、释放对象 URL。
- 插件本体很轻（几十 KB），不带任何素材；皮肤素材由用户自己提供，因此安装包可以保持小体积。
许可
MIT
