docs: 按 Halo 官方插件 README 风格重写
This commit is contained in:
@@ -1,67 +1,93 @@
|
||||
# dark-mode
|
||||
# Halo 深色模式
|
||||
|
||||
Halo 2.25 暗色模式插件 — 为 Halo 后台管理面板提供深色/浅色模式切换，支持跟随系统、手动切换和偏好记忆。
|
||||
为 Halo 后台管理面板提供深色/浅色模式切换，内置 Dark Reader 通用暗色引擎，支持手动切换、跟随系统与偏好记忆。
|
||||
|
||||
## 功能
|
||||
## 功能特性
|
||||
|
||||
- ☀️/🌙 **三种模式**：浅色、深色、跟随系统
|
||||
- 💾 **偏好持久化**：自动记忆用户选择（localStorage），刷新不丢失
|
||||
- 🖥️ **系统偏好跟随**：切换系统外观时自动响应
|
||||
- 🔍 **Dark Reader 引擎**：内置成熟的开源暗色转换引擎，自动分析页面 CSS 与 DOM，第三方插件页面的黑字/白底也能自动转换
|
||||
- 🧩 **侧边栏注入**：切换按钮自动出现在侧边栏底部（UserProfileBanner 上方）
|
||||
- ⚙️ **设置页面**：提供详细的模式选择界面（菜单 → 偏好设置 → 深色模式）
|
||||
- 📦 **零后端依赖**：纯前端实现，不需要后端 API
|
||||
- **三种模式**：浅色、深色、跟随系统
|
||||
- **偏好持久化**：自动记忆用户选择（localStorage），刷新不丢失
|
||||
- **系统偏好跟随**：切换系统外观时自动响应
|
||||
- **Dark Reader 引擎**：自动分析页面 CSS 与 DOM，覆盖 Halo 核心页面和第三方插件页面
|
||||
- **侧边栏一键切换**：切换按钮自动出现在侧边栏 UserProfileBanner 上方
|
||||
- **设置页面**：在「偏好设置 → 深色模式」中详细选择显示模式
|
||||
- **零后端依赖**：纯前端实现，不需要额外后端 API
|
||||
|
||||
## 安装
|
||||
|
||||
1. 从 Releases 下载 `plugin-dark-mode-<version>.jar`。
|
||||
2. 在 Halo 后台的「插件管理」中上传并安装。
|
||||
3. 启用插件后，侧边栏底部会出现深色模式切换按钮。
|
||||
|
||||
## 使用
|
||||
|
||||
安装并启用后，可以直接点击侧边栏按钮在深色和浅色模式之间切换，也可以进入设置页面选择固定模式：
|
||||
|
||||
| 配置项 | 可选值 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| 主题模式 | `light` | 始终使用浅色模式 |
|
||||
| 主题模式 | `dark` | 始终使用深色模式 |
|
||||
| 主题模式 | `auto` | 跟随系统外观自动切换 |
|
||||
|
||||
## 技术原理
|
||||
|
||||
- 插件通过 `useDarkMode()` 管理 `light` / `dark` / `auto` 三种状态。
|
||||
- 深色模式下调用 Dark Reader 的 `enable()`，浅色模式下调用 `disable()`。
|
||||
- Dark Reader 会持续监听页面 DOM 变化，因此第三方插件动态渲染的内容也能自动转换。
|
||||
- 插件自身只保留切换器与设置页所需的最小 UI 变量，不再维护逐页手工 CSS 覆盖。
|
||||
|
||||
## 第三方依赖
|
||||
|
||||
- [Dark Reader](https://github.com/darkreader/darkreader) `4.9.129`，使用 [MIT License](https://github.com/darkreader/darkreader/blob/main/LICENSE)。
|
||||
作为插件的暗色转换引擎，构建所需文件已整理到 `third-party/darkreader/`，构建时由 `ui/package.json` 通过本地文件依赖引用。
|
||||
- [Dark Reader](https://github.com/darkreader/darkreader) `4.9.129`，[MIT License](https://github.com/darkreader/darkreader/blob/main/LICENSE)。
|
||||
- 构建所需文件位于 `third-party/darkreader/`，由 `ui/package.json` 通过本地文件依赖引用。
|
||||
|
||||
## 开发环境
|
||||
|
||||
- Java 21+（Halo 插件编译要求；本机开发使用 JDK 25 + `--release 21`）
|
||||
- Halo `>=2.25.0`
|
||||
- Java 21+（项目使用 `--release 21` 编译）
|
||||
- Node.js 18+
|
||||
- pnpm
|
||||
- Docker（`haloServer` 开发服务器需要）
|
||||
|
||||
## 快速开始
|
||||
## 从源码构建
|
||||
|
||||
仓库使用标准 Gradle 结构，并提交了 Gradle Wrapper。
|
||||
|
||||
Linux / macOS：
|
||||
|
||||
```bash
|
||||
# 启用插件并启动 Halo 开发服务器
|
||||
./gradlew haloServer
|
||||
./gradlew clean build
|
||||
```
|
||||
|
||||
# 前端开发（watch 模式）
|
||||
Windows：
|
||||
|
||||
```powershell
|
||||
.\gradlew.bat clean build
|
||||
```
|
||||
|
||||
构建产物位于 `build/libs/plugin-dark-mode-<version>.jar`。
|
||||
|
||||
## 前端开发
|
||||
|
||||
```bash
|
||||
cd ui
|
||||
pnpm install
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
## 构建
|
||||
常用检查命令：
|
||||
|
||||
```bash
|
||||
# 完整构建（后端 + 前端）
|
||||
./gradlew build
|
||||
```
|
||||
|
||||
构建完成后，插件 JAR 文件位于 `build/libs/`，可直接在 Halo 后台安装。
|
||||
|
||||
## 前端命令
|
||||
|
||||
```bash
|
||||
cd ui
|
||||
|
||||
pnpm dev # 开发构建（watch）
|
||||
pnpm build # 生产构建
|
||||
pnpm type-check # TypeScript 类型检查
|
||||
pnpm lint # Lint（oxlint + eslint）
|
||||
pnpm prettier # 代码格式化
|
||||
pnpm test:unit # 单元测试
|
||||
pnpm build # 生产构建
|
||||
```
|
||||
|
||||
## 项目结构
|
||||
|
||||
```text
|
||||
├── build.gradle # 根构建（BOM 2.25.0, DevTools 0.8.0）
|
||||
├── build.gradle # 根构建配置
|
||||
├── settings.gradle # 包含 :ui 子项目
|
||||
├── gradle/wrapper/ # Gradle Wrapper
|
||||
├── src/
|
||||
│ └── main/
|
||||
│ ├── java/run/halo/darkmode/
|
||||
@@ -70,16 +96,17 @@ pnpm test:unit # 单元测试
|
||||
│ └── plugin.yaml # 插件清单
|
||||
│
|
||||
├── third-party/
|
||||
│ └── darkreader/ # Dark Reader 4.9.129（MIT）
|
||||
│ └── darkreader/ # Dark Reader 构建产物（MIT）
|
||||
│
|
||||
└── ui/
|
||||
├── package.json # 通过 file:../third-party/darkreader 引用 Dark Reader
|
||||
├── package.json # 前端依赖
|
||||
├── vite.config.ts # Vite 配置
|
||||
└── src/
|
||||
├── index.ts # definePlugin 入口
|
||||
├── darkreader-engine.ts # Dark Reader 通用暗色引擎
|
||||
├── injector.ts # ThemeToggle 侧边栏注入器
|
||||
├── injector.ts # 侧边栏切换器注入
|
||||
├── composables/
|
||||
│ ├── useDarkMode.ts # 核心状态管理（模块级单例）
|
||||
│ ├── useDarkMode.ts # 主题状态管理（模块级单例）
|
||||
│ └── useSystemPreference.ts # 系统偏好监听
|
||||
├── components/
|
||||
│ └── ThemeToggle.vue # 侧边栏切换按钮
|
||||
@@ -90,6 +117,28 @@ pnpm test:unit # 单元测试
|
||||
└── variables.css # 插件自身 UI 变量
|
||||
```
|
||||
|
||||
## 测试
|
||||
|
||||
```bash
|
||||
./gradlew test
|
||||
```
|
||||
|
||||
运行时验证脚本位于 `scripts/verify-toggle.py`，用于检查主题切换、localStorage 持久化以及 Dark Reader 注入状态。
|
||||
|
||||
## 更新日志
|
||||
|
||||
### v1.0.4
|
||||
|
||||
- 改为纯 Dark Reader 引擎，移除手工 CSS 覆盖
|
||||
- 移除 Monaco 手动主题同步，暗色转换统一交给 Dark Reader
|
||||
- 整理 `third-party/darkreader` 目录，仅保留构建所需文件
|
||||
|
||||
### v1.0.3
|
||||
|
||||
- 引入 Dark Reader 通用暗色引擎
|
||||
- 保留原有手工 CSS 作为兼容层，覆盖核心页面与第三方插件页面
|
||||
- 增加 Monaco 日志查看器主题同步
|
||||
|
||||
## 许可证
|
||||
|
||||
[GPL-3.0](./LICENSE) © LHY
|
||||
Reference in New Issue
Block a user