# super-wallpaper

**Repository Path**: jares/super-wallpaper

## Basic Information

- **Project Name**: super-wallpaper
- **Description**: 超级壁纸
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-06-10
- **Last Updated**: 2026-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 超级壁纸 · Super Wallpaper

一款把**动态壁纸**（视频 / 网页 / 图片 / GIF / 本地动态壁纸）真正"沉"到 Windows 桌面图标**之下**的桌面应用。

不同于传统"把窗口盖在最上面"的伪壁纸，本工具通过 Win32 API 把壁纸窗口挂载到桌面系统的 `WorkerW` 层级（图标层之下的那一层），因此：

- 桌面图标可正常点击、右键菜单正常弹出；
- 任务栏、开始菜单、`Win + D` 显示桌面均不受影响；
- 壁纸窗口不拦截鼠标，体验与系统原生壁纸一致。

> 平台：仅支持 **Windows**（依赖 `WorkerW` 层级挂载与 Win32 API）。
> 详细功能说明与后续规划见 [`功能文档.md`](./功能文档.md)。

---

## ✨ 功能特性

- **真·桌面层级**：壁纸窗口挂在桌面图标之下，不挡图标、不挡任务栏。
- **多类型内容**：支持视频、图片、GIF、网页 URL、本地 HTML。
- **本地动态壁纸**：内置多款纯前端动态壁纸（极光 / 时钟 / 每日一言 / 星空 / 雨滴 / 渐变流体 / 数字雨），零网络依赖。
- **每日精选**：壁纸库对接 Bing 每日图片，点击即换。
- **填充模式**：填充（铺满裁剪无黑边）/ 拉伸 / 适应。
- **水印**：可配置文字、颜色、字号、透明度、位置（玻璃质感卡片，任何亮暗背景都清晰）。
- **记忆恢复**：自动记住上次壁纸与显示配置，重启后恢复。
- **系统托盘**：左键切换主窗口，右键菜单（显示主窗口 / 动态壁纸开关 / 设置 / 退出），与主窗口同款深色主题。
- **开机启动 / 自动更新**：支持开机自启与增量更新（见原规划）。

---

## 🧱 技术栈

| 层 | 技术 |
| --- | --- |
| 桌面壳 | Electron（主进程 + 预加载脚本） |
| 前端 UI | Vue 3 + Vue Router + Vite + SCSS |
| 原生绑定 | [koffi](https://github.com/kofi/koffi)（FFI 调用 `user32` / `kernel32` Win32 API） |
| 图片处理 | sharp（历史烘焙能力，当前水印为 DOM 叠加方案） |

---

## 📁 目录结构

```
super-wallpaper/
├── electron/wallpaper/         # Electron 主进程 / 壁纸引擎
│   ├── main.js                 # 入口：窗口创建、IPC、托盘
│   ├── tray.js                 # 系统托盘（自定义深色菜单）
│   ├── preload.js              # 上下文隔离的 API 桥接
│   ├── modules/
│   │   ├── wallpaper.js        # 壁纸窗口工厂：内容识别/填充/水印/持久化
│   │   ├── wallpaper-engine.js # Win32 WorkerW 挂载（koffi）
│   │   └── UpdateController.js  # 更新控制
│   ├── html/                   # 壁纸渲染页 & 本地动态壁纸
│   │   ├── wallpaper-media.html  # 图片/视频媒体页（object-fit + 水印）
│   │   ├── wallpaper-{aurora,clock,quote,stars,rain,fluid,matrix}.html
│   │   └── tray.html / update.html / ...
│   ├── static/                 # 图标、字体、更新页样式
│   └── windows/                # 主窗口 / 主页窗口
├── src/                        # Vue 前端（主窗口 UI）
│   ├── views/home/             # 壁纸库（每日精选 + 本地动态壁纸 + 网页）
│   ├── views/custom/           # 设置页（填充模式 / 水印 / 本地·网络图片）
│   └── ...
├── 功能文档.md                  # 功能说明与规划
└── README.md
```

---

## 🚀 开发 & 构建

本项目使用 **pnpm**（单仓库）。

```bash
# 安装依赖
pnpm install

# 启动前端开发服务器（Vite，端口 5173，支持热更新）
pnpm dev

# 启动 Electron 主进程（修改主进程代码后需重启此命令）
pnpm electron:dev
```

> 注意：前端（`pnpm dev`）与 Electron 主进程（`pnpm electron:dev`）是两个独立终端，需同时运行。

```bash
# 打包为 Windows 安装包（输出到 dist/）
pnpm electron:build
# 或
pnpm build
```

---

## ⚙️ 工作原理（简述）

1. Electron 创建一个无边框、透明、不可激活、不在任务栏的 `BrowserWindow`，覆盖所有显示器。
2. 通过 koffi 调用 `FindWindowEx` / `SendMessageTimeout(0x052C)` / `SetParent` / `SetWindowPos`，把该窗口挂到桌面 `Progman → WorkerW` 层级（图标之下）。
3. 媒体内容（图片/视频）由 `wallpaper-media.html` 渲染，按 `object-fit` 铺满；水印以 DOM 叠加，配置经 `executeJavaScript` 强制落地。
4. 心跳每 10s 检测 `WorkerW` 是否存活，失效自动重挂（应对显示器插拔 / 系统主题切换）。

---

## 🗒️ 使用说明

- **换壁纸**：打开主窗口 → 壁纸库 → 点击每日精选图片或本地动态壁纸卡片；也可在设置页选择本地/网络图片。
- **调样式**：设置页可改填充模式、水印（文字/颜色/字号/透明度/位置）。
- **托盘**：右键托盘图标打开菜单（显示主窗口 / 开关动态壁纸 / 设置 / 退出）。
- **网页壁纸**：壁纸库顶部输入框填入 `https://...` 地址即可。

---

## 📌 说明

- 水印层目前作用于图片 / 视频壁纸；本地 HTML 动态壁纸按设计不叠水印。
- 图标位于 `electron/wallpaper/static/images/`（运行态 `icon.png`，打包 `icon.ico` / `favicon.ico`）。
- 本地工具目录 `.workbuddy/` 与截图目录 `.screenshots/` 已在 `.gitignore` 中忽略，不纳入版本库。