dsh-client-ui-wallpaper

Readme

# dsh-client-ui-wallpaper

[中文](#中文) | [English](#english)

![预置壁纸 / default wallpaper](assets/wallpaper.png)

---

## 中文

### 🎯 用途

给 dsh 的 Web GUI 换壁纸的浏览器端插件。

### 📥 安装

```sh
dsh plugin --profile web add github:tippykafuu/dsh-client-ui-wallpaper
```

```sh
dsh plugin --profile web add link:<本仓库路径>
# 重启 dsh web 生效
```

### 🎨 自定义

```sh
node build-client.mjs                      # 换成 assets/wallpaper.png
node build-client.mjs <图片路径>            # 换成指定图片
```

构图调参在 `styles/wallpaper.css` 的 `:root` 里：

| 变量 | 作用 | 默认值 |
|---|---|---|
| `--dsh-wallpaper-size` | 尺寸，`auto 高度` 表示宽度按比例 | `auto min(78vh, 58vw)` |
| `--dsh-wallpaper-position` | 贴在哪个角 | `right 2.5vw bottom -1vh` |
| `--dsh-wallpaper-tint` | 压在壁纸上的底色浓度，**越大越淡、文字越清楚** | 浅色 `62%`，深色 `70%` |

改完重跑 `node build-client.mjs` 再刷新。

### 🧹 卸载

```sh
dsh plugin --profile web remove dsh-client-ui-wallpaper
# 重启 dsh web 生效
```

### 🧩 扩展

`styles/wallpaper.css` 就是这个插件注入页面的全部内容，改样式直接往里加选择器。

**换构图 / 换浓度**：改上面那三个变量。注意 `.pI_x6G_frame` 和 `.wSkVaW_root` 两条置空规则要
同时保留，只留一条的话，壁纸会在 App 挂载后被盖住。

**让更多区域透出壁纸**：给对应容器的 `background` 加 `transparent !important`，或把它的底色
token 改成半透明（例如左侧栏用的 `--dsw-specific-sidebar-fill`）。左侧栏默认实心是刻意保留的。

**加多张壁纸 / 做切换**：需要往设置页加一项。客户端半边在 `inject` 里声明要用的客户端服务
（如 `slots`、`settingsScope`），在 `apply(ctx)` 里注册设置行；`build-client.mjs` 里把单张图
改成按选项切换的多份 data URI。

**把图片移到外部**：现在图片内联在 bundle 里。想换成外部资源，可以让宿主半边
`lib/index.js` 注册一条 webserver 路由把 `assets/wallpaper.png` 发出去，样式改成指向那个 URL；
代价是插件不再自包含，多一个运行时依赖。

**加宿主侧能力**：`lib/index.js` 是标准的 Cordis 插件，可以 `inject` 宿主服务、注册路由、往
index.html 注入行，和 dsh 自带宿主插件的写法一致。

**改名**：三处要一起改——`package.json` 的 `name`、`build-client.mjs` 生成的 bundle `id`、补丁
行的 `name`。bundle 的 `id` 必须等于包名，`exports["./client"]` 必须指向构建产物，这两条不能破。

### 🗂️ 文件

| 文件 | 用途 |
|---|---|
| `package.json` | 包声明：插件名、`dsh.bundle`、`dsh.client`、客户端入口 |
| `cordis.patch.yml` | 挂载层：把插件行插进 profile 的插件树 |
| `lib/index.js` | 宿主半边，空的 Cordis 插件 |
| `lib/client.js` | 浏览器半边（构建产物，勿手改） |
| `styles/wallpaper.css` | 壁纸样式 |
| `assets/wallpaper.png` | 壁纸原图 |
| `build-client.mjs` | 构建 `lib/client.js` |
| `verify-install.mjs` | 安装自检 |

### 🖼️ 图片声明

`assets/wallpaper.png` 来自互联网，版权归原作者所有，此处仅作示例与个人使用。本仓库的 MIT
许可只覆盖代码，不覆盖该图片；如需商用请自行替换为已获授权的图片。原作者如有异议，提 issue
即可，会立即移除。

### 📜 许可

[MIT](LICENSE)

---

## English

### 🎯 What it does

Changes the wallpaper of the dsh Web GUI.

### 📥 Install

```sh
dsh plugin --profile web add github:tippykafuu/dsh-client-ui-wallpaper
```

```sh
dsh plugin --profile web add link:<path to this repo>
# restart dsh web to take effect
```

### 🎨 Customize

```sh
node build-client.mjs                      # use assets/wallpaper.png
node build-client.mjs <image path>         # use a specific image
```

Composition is tuned in `styles/wallpaper.css`, under `:root`:

| Variable | Purpose | Default |
|---|---|---|
| `--dsh-wallpaper-size` | Size; `auto <height>` keeps the aspect ratio | `auto min(78vh, 58vw)` |
| `--dsh-wallpaper-position` | Which corner it sticks to | `right 2.5vw bottom -1vh` |
| `--dsh-wallpaper-tint` | Tint layered over the image; **higher = fainter wallpaper, clearer text** | light `62%`, dark `70%` |

Re-run `node build-client.mjs` after editing, then reload.

### 🧹 Uninstall

```sh
dsh plugin --profile web remove dsh-client-ui-wallpaper
# restart dsh web to take effect
```

### 🧩 Extending

`styles/wallpaper.css` is everything this plugin injects into the page — add selectors there to change
how it looks.

**Reframe / retint**: change the three variables above. Keep both blanking rules, `.pI_x6G_frame` and
`.wSkVaW_root`; with only one of them the wallpaper is covered again once the app mounts.

**Let more areas show through**: add `transparent !important` to that container's `background`, or make
its fill token translucent (for example `--dsw-specific-sidebar-fill` for the left sidebar, which is
opaque on purpose by default).

**Several wallpapers / a switcher**: this needs a row in Settings. Declare the client services you need
in `inject` (for example `slots`, `settingsScope`), register a settings row inside `apply(ctx)`, and turn
the single image in `build-client.mjs` into several data URIs selected by that option.

**Move the image out of the bundle**: the image is inlined in the bundle today. To serve it externally,
have the host half (`lib/index.js`) register a webserver route for `assets/wallpaper.png` and point the
stylesheet at that URL — at the cost of the plugin no longer being self-contained.

**Add host-side capability**: `lib/index.js` is a plain Cordis plugin. It can inject host services,
register routes and inject rows into index.html, exactly like dsh's own host plugins.

**Renaming**: change three places together — `name` in `package.json`, the bundle `id` that
`build-client.mjs` emits, and `name` in the patch row. The bundle `id` must equal the package name, and
`exports["./client"]` must point at the built file; neither of those can break.

### 🗂️ Files

| File | Purpose |
|---|---|
| `package.json` | Package manifest: plugin name, `dsh.bundle`, `dsh.client`, client entry |
| `cordis.patch.yml` | Mount layer: inserts the plugin row into the profile tree |
| `lib/index.js` | Host half, an empty Cordis plugin |
| `lib/client.js` | Browser half (build output, do not edit by hand) |
| `styles/wallpaper.css` | Wallpaper styles |
| `assets/wallpaper.png` | Source wallpaper image |
| `build-client.mjs` | Builds `lib/client.js` |
| `verify-install.mjs` | Install self-check |

### 🖼️ Image notice

`assets/wallpaper.png` comes from the internet. Copyright belongs to its original author, and it is
included here only as a sample for personal use. This repository's MIT license covers the code only,
not the image — replace it with a licensed image before any commercial use. If the original author
objects, open an issue and it will be removed right away.

### 📜 License

[MIT](LICENSE)

[↑ 回到顶部 / Back to top](#dsh-client-ui-wallpaper)