Files

T

Serendipity 394613f516 fix: 深色模式入口移至外观分组并移除侧边栏按钮（1.0.6）

- 设置入口 group 改为官方 interface（外观）分组
- 删除侧边栏 ThemeToggle 注入器及组件，设置页成为唯一入口
- verify-toggle.py 改为直接驱动主题状态并校验翻转
- 同步 README 与脚本文档，版本升级 1.0.6

2026-08-08 19:25:27 +08:00

5.5 KiB

Raw Blame History

Halo 深色模式

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

功能特性

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

安装

从 Releases 下载 plugin-dark-mode-<version>.jar。
在 Halo 后台的「插件管理」中上传并安装。
启用插件后，进入「外观 → 深色模式」设置页面调整主题。

使用

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

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

技术原理

插件通过 useDarkMode() 管理 light / dark / auto 三种状态。
深色模式下调用 Dark Reader 的 enable()，浅色模式下调用 disable()。
Dark Reader 会持续监听页面 DOM 变化，因此第三方插件动态渲染的内容也能自动转换。
插件自身只保留设置页所需的最小 UI 变量，不再维护逐页手工 CSS 覆盖。

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

第三方依赖

Dark Reader 4.9.129，MIT License。
构建所需文件位于 third-party/darkreader/，由 ui/package.json 通过本地文件依赖引用。
升级或替换 Dark Reader 构建文件后，请校验 third-party/darkreader/SHA256SUMS： Linux / macOS 使用 sha256sum -c SHA256SUMS，Windows 使用 Get-FileHash -Algorithm SHA256 对比。

开发环境

Halo >=2.25.0
Java 21+（项目使用 --release 21 编译）
Node.js 18+
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/run/halo/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 的翻转。

更新日志

v1.0.6

深色模式设置入口移至 Halo 官方「外观」分组
移除侧边栏底部注入的切换按钮，设置页成为唯一入口
更新运行时验证脚本：直接驱动主题状态，不再依赖侧边栏按钮

v1.0.5

同步设置 color-scheme，缓解深色模式刷新闪烁
增加多标签页主题同步与 useDarkMode 单元测试
侧边栏切换按钮与设置选项支持键盘操作
后端日志改用 Lombok @Slf4j
裁剪 vendored package.json，新增 Dark Reader SHA256SUMS 完整性校验
plugin.yaml 改为安装后由用户手动启用

v1.0.4

改为纯 Dark Reader 引擎，移除手工 CSS 覆盖
移除 Monaco 手动主题同步，暗色转换统一交给 Dark Reader
整理 third-party/darkreader 目录，仅保留构建所需文件

v1.0.3

引入 Dark Reader 通用暗色引擎
保留原有手工 CSS 作为兼容层，覆盖核心页面与第三方插件页面
增加 Monaco 日志查看器主题同步

5.5 KiB Raw Blame History Unescape Escape