Halo 深色模式

为 Halo 后台管理面板提供深色/浅色模式切换，内置 Dark Reader 通用暗色引擎，支持手动切换、跟随系统与偏好记忆。

功能特性

三种模式：浅色、深色、跟随系统
偏好持久化：自动记忆用户选择（localStorage），刷新不丢失
系统偏好跟随：切换系统外观时自动响应
Dark Reader 引擎：自动分析页面 CSS 与 DOM，覆盖 Halo 核心页面和第三方插件页面
官方外观分组：设置入口位于 Halo「外观」分组，与主题、菜单、插件同组
设置页面：在「外观 → 深色模式」中详细选择显示模式
零后端依赖：纯前端实现，不需要额外后端 API

已知问题

部分富文本编辑器可能与 Dark Reader 动态分析冲突：文章 / 页面编辑页中的富文本编辑器（例如 ProseMirror、TipTap 等）在 Dark Reader 动态模式下可能出现卡顿或卡死。请在「外观 → 深色模式 → 编辑页 Dark Reader」中选择「编辑页使用浅色纸面」。该选项仍保留编辑页外围的 Dark Reader 深色效果，仅将已识别的编辑工作区恢复为浅色纸面；使用 Markdown 等不受影响的编辑器时，也可以选择「编辑页也使用 Dark Reader」。
浏览器 Dark Reader 扩展可能产生冲突：如果浏览器同时安装并启用了 Dark Reader 扩展，请在扩展中关闭当前站点的处理，避免浏览器扩展与插件内置引擎重复转换。
刷新时可能出现极短闪白：Dark Reader 样式注入是异步的，页面刷新瞬间可能短暂显示浅色，插件通过同步 color-scheme 尽量缓解，但无法完全消除。

使用

安装并启用后，进入「外观 → 深色模式」设置页面选择显示模式：

配置项	可选值	说明
主题模式	`light`	始终使用浅色模式
主题模式	`dark`	始终使用深色模式
主题模式	`auto`	跟随系统外观自动切换

截图预览

以下截图展示插件在 Halo 后台的实际效果。

插件信息界面

插件模式选择界面

文章写作界面展示

仪表盘界面展示

主题界面展示

技术原理

插件通过 useDarkMode() 管理 light / dark / auto 三种状态。
深色模式下调用 Dark Reader 的 enable()，浅色模式下调用 disable()。
Dark Reader 会持续监听页面 DOM 变化，因此第三方插件动态渲染的内容也能自动转换。
编辑页通过严格的路由范围标记识别文章和页面编辑器；选择「编辑页使用浅色纸面」时，由插件 CSS 只恢复编辑工作区的浅色纸面，左侧导航和页面外围仍由 Dark Reader 处理。
插件自身只保留设置页和编辑工作区局部样式所需的 CSS，不维护全站逐页手工颜色覆盖。

说明：Dark Reader 的样式注入是异步的，刷新瞬间仍可能存在极短闪白；插件通过同步设置 color-scheme 缓解，但无法完全消除。

第三方依赖

Dark Reader 4.9.129，MIT License。
构建所需文件位于 third-party/darkreader/，由 ui/package.json 通过本地文件依赖引用。

vendored 依赖溯源

third-party/darkreader/ 取自 Dark Reader 开源仓库源码构建，版本标记为 4.9.129；官方 npm 最新发布版本为 4.9.128。
本仓库 bundler（darkreader.js / darkreader.mjs）与官方 4.9.128 存在差异（体积与内容不同），属源码在官方 4.9.128 之后的一版构建；类型声明 index.d.ts 与官方一致，许可证同为 MIT。
为保障供应链可复现，git 仅跟踪构建所需文件，并以 third-party/darkreader/SHA256SUMS 作为完整性锚点。

SHA256SUMS 生成与校验

校验（核对某文件是否与记录一致）：
- Linux / macOS：cd third-party/darkreader && sha256sum -c SHA256SUMS
- Windows：Get-FileHash darkreader.js -Algorithm SHA256，与 SHA256SUMS 中对应条目比对
重新生成（替换构建产物后必须更新）：
- Linux / macOS：cd third-party/darkreader && sha256sum darkreader.js darkreader.mjs package.json index.d.ts LICENSE > SHA256SUMS
- Windows：对 darkreader.js / darkreader.mjs / package.json / index.d.ts / LICENSE 分别执行 Get-FileHash -Algorithm SHA256，按 SHA256SUMS 的行格式（<hash> <文件名>）写回

升级 / 替换

从 Dark Reader 官方构建产物或 npm tarball 重新生成上述 6 个文件后，务必重新生成 SHA256SUMS；ui/package.json 中的本地依赖路径无需改动。

开发环境

Halo >=2.25.0
Java 21+（项目使用 --release 21 编译）
Node.js 20.19+（Vite 8 要求）
pnpm
Docker（haloServer 开发服务器需要）

从源码构建

仓库使用标准 Gradle 结构，并提交了 Gradle Wrapper。

Linux / macOS：

./gradlew clean build

Windows：

.\gradlew.bat clean build

构建产物位于 build/libs/plugin-dark-mode-<version>.jar。

前端开发

cd ui
pnpm install
pnpm dev

常用检查命令：

pnpm type-check   # TypeScript 类型检查
pnpm lint         # Lint（oxlint + eslint）
pnpm build        # 生产构建

项目结构

├── build.gradle              # 根构建配置
├── settings.gradle           # 包含 :ui 子项目
├── gradle/wrapper/           # Gradle Wrapper
├── src/
│   └── main/
│       ├── java/top/liuhangyv/darkmode/
│       │   └── DarkModePlugin.java    # 插件主类（极简骨架）
│       └── resources/
│           └── plugin.yaml            # 插件清单
│
├── third-party/
│   └── darkreader/           # Dark Reader 构建产物（MIT）
│
└── ui/
    ├── package.json          # 前端依赖
    ├── vite.config.ts        # Vite 配置
    └── src/
        ├── index.ts                   # definePlugin 入口
        ├── darkreader-engine.ts       # Dark Reader 通用暗色引擎
        ├── composables/
        │   ├── useDarkMode.ts         # 主题状态管理（模块级单例）
        │   └── useSystemPreference.ts # 系统偏好监听
        ├── views/
        │   └── SettingsView.vue       # 设置页面
        └── styles/
            ├── index.css              # 样式入口
            └── variables.css          # 插件自身 UI 变量

测试

./gradlew test

运行时验证脚本位于 scripts/verify-toggle.py，用于直接驱动主题状态，并检查 data-halo-theme、localStorage、Dark Reader 注入与 color-scheme 的翻转。

应用市场

插件页：https://www.halo.run/store/apps/app-cpno4kjh
发布者页：https://www.halo.run/store/publishers/lhy0125

更新日志

各版本详细变更见 CHANGELOG.md。

联系

遇到问题或想反馈建议，欢迎通过 GitHub Issues 提交，或直接发邮件至 3364451258@qq.com。