# zcode-wallpaper

**Repository Path**: xudemos/zcode-wallpaper

## Basic Information

- **Project Name**: zcode-wallpaper
- **Description**: zcode壁纸
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2026-08-27
- **Last Updated**: 2026-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ZCode 桌面端主题工具

> 支持 **Windows** 与 **macOS**（需已安装 ZCode 桌面端）· 已适配 ZCode 3.14.3

给 ZCode 桌面端换上**自定义壁纸 / 视频动态背景**、半透明面板、霓虹光效、鼠标拖尾的美化工具。
全部功能集成在一个中文菜单脚本里，可随时一键还原官方原版。

## 📦 下载

**当前版本 v1.0，适配 ZCode 3.14.3** —— 请到 [**发行版（Releases）页面**](https://gitee.com/xudemos/zcode-wallpaper/releases) 下载 `ZCode主题工具.zip`，解压即用（步骤见下方快速开始）。

## 效果演示

▶ **[点击观看视频演示（含声音画面操作全程）](docs/demo.mp4)**

<video src="docs/demo.mp4" controls width="100%"></video>

*（Gitee 的 README 不支持内联播放视频：部分客户端会显示上方播放器，若没有请点击链接观看）*

![界面效果](wallpaper/candidates/1fefc93a-0d08-4185-aaea-04770b485dff.png)

## 效果一览

- 自定义壁纸铺满窗口，或 **mp4 视频循环播放的动态背景**（静音自动播放）
- 半透明面板透出壁纸，透明度 13 项参数自由调整（对话区、左侧菜单、悬浮菜单、消息气泡独立控制）
- 次要文字自动提亮、菜单暗化遮罩、文字投影——深色壁纸下文字依然清晰
- 鼠标拖尾光痕、输入框霓虹、按钮呼吸灯、标题流光、消息入场动效（可一键关闭）
- 改壁纸 / 调参数**无需重新打包**，重启 ZCode 即生效
- 菜单按安装状态分显：未安装时只显示安装入口，装好自动解锁全部功能

## 快速开始

### 方式一：直接使用（推荐）

下载仓库里的 **`ZCode主题工具.zip`**，解压后：

- **Windows**：双击 `ZCode主题工具.bat`
- **macOS**：打开「终端」，输入 `bash` 加一个空格，把 `ZCode主题工具Mac.sh` 拖进终端窗口，按回车

安装步骤：

1. 主菜单选 `[1] 安装主题`（Windows 自动申请管理员权限；macOS 需要时输入 sudo 密码；需要已安装 Node.js）
2. 等打包完成后，**完全退出 ZCode**（Windows 含托盘图标；macOS 按 Cmd+Q）
3. 脚本自动完成安装（会自动把壁纸/视频路径本地化为本机路径），重新打开 ZCode 即可

> 说明：本主题按深色界面设计。若你的 ZCode 当前是浅色主题，会自动按深色显示（仅界面表现，不改 ZCode 的设置项）。

### 方式二：源码使用

直接克隆/下载本仓库，运行方式同上，效果相同。

## 使用前提

- Windows 或 macOS + 已安装 ZCode 桌面端
- 已安装 [Node.js](https://nodejs.org)（LTS 版即可，仅「安装主题」功能需要）

## 主菜单

```
[1] 安装主题（首次使用先做这一步；ZCode 升级后重装也用它，自动适配新版本）
[2] 更换壁纸 / 视频背景（图片 jpg/png/webp 或视频 mp4/webm/mkv/mov，拖入即设）
[3] 特效设置（13 项参数，全部中文说明）
[4] 一键还原官方原版（官方包备份保留在 ZCode 目录，可反复还原）
[0] 退出
```

改壁纸 / 调参数后**重启 ZCode** 即生效（主题以外部文件方式加载，无需重新打包）。

## 特效参数（菜单 [2]）

| 参数 | 说明 | 默认 |
|------|------|------|
| 拖尾开关/密度/消散/上限 | 鼠标拖尾光痕四件套 | 开 / 4 / 0.10 / 90 |
| 壁纸明暗 | 0~1，保证文字可读 | 0.42 |
| 对话区透明度 | 决定壁纸可见度，建议 20~30 | 23% |
| 左侧菜单透明度 | 独立控制，想透就调低 | 23% |
| 左侧菜单暗化 | 叠加暗色让菜单文字更清楚 | 0.35 |
| 悬浮菜单实心度 | 弹出菜单越大越实 | 90% |
| 消息气泡实心度 | 历史对话气泡（深蓝灰底白字） | 88% |
| 氛围光强度 / 动效开关 | 右上蓝 + 左下紫氛围光 / 动效总开关 | 0.22 / 开 |

## 目录说明

```
ZCode主题工具.bat        主程序（双击运行）
theme.css               主题样式（可用记事本直接改，改完重启 ZCode）
effects.js              特效配置（拖尾参数、视频背景开关）
wallpaper\              当前壁纸 / 默认视频背景 / 候选壁纸
scripts\js\             内部工具脚本
ZCode主题工具.zip        打包好的直接使用版
使用说明.txt             详细中文说明
```

## 常见问题

- **双击 bat 闪退**：多为安全软件拦截，将目录加入白名单，或用管理员 PowerShell 手动运行。
- **重启后界面全白**：说明 ZCode 用的是浅色主题且主题未安装成功——重新运行工具选 `[1]` 安装（新版会自动切换深色表现并本地化壁纸路径）。
- **换壁纸没生效**：必须完全重启 ZCode（主题文件在启动时加载）。
- **ZCode 升级后主题消失**：正常现象，重新运行工具选 `[1]` 即可（工具会自动识别升级并提示重装）。
- **视频背景卡顿**：换 1080p 及以下的视频素材，或换回静态壁纸。

## 还原

主菜单选 `[4]` 一键还原官方原版（定制包会留存，随时可装回）。

---

仅供学习交流使用，请支持正版软件。