博客搭建与魔改系列教程导航🚥🚥🚥

这一篇单独讲「综合美化模块」:把主题色、卡片透明度、字体、壁纸、布局和特效收进一个弹窗面板,改完即时生效,刷新后保持。适用 Hexo 8.1.2 + Butterfly 5.7.2。

借鉴:Fomalhaut(猕猴桃)。本站改动:面板结构、CSS 变量、持久化与动画降级按本站实现重写,不是原样搬运。

阅读约定:每个代码块上方都标了 文件 与 改法。[Blogroot] 指博客根目录;「新建」是建好文件后整段写入,「追加」是放到文件末尾,「在已有文件的某函数内补全」是在本站已有的同名脚本里改对应位置,不要另建一份。面板外观类样式放 source/css/beauty-panel.css,卡片底色、字号、圆角这类全局魔改放 source/css/custom.css,两者不要混。

综合美化模块到底做了什么

一般的主题换肤,要么改 _config 重新生成,要么在浏览器里用开发者工具临时改两下。综合美化模块把这两件事合在一起:

  • 入口固定:导航栏一个调色盘按钮,右键菜单里也能打开同一个面板。
  • 即时预览:拖滑块、点色点、换字体,页面立刻变化,不刷新。
  • 持久保存:偏好写进 localStorage,下次打开还是你调好的样子。
  • 互不打架:所有外观都收口到一组 CSS 变量和 <html> 上的类名,主题源码一行不用改。

它不是一个单独的插件,而是「一个首屏脚本 + 一份样式 + 一个面板脚本 + 几组特效脚本」拼起来的模块。下面按这个顺序讲,每一步都写明改哪个文件。

开始之前:文件与加载顺序

文件清单

整套模块按职责拆成这些文件,路径都在博客根目录 [Blogroot] 下:

文件职责
source/js/fomal/boot.js首屏同步脚本,读 localStorage 并写 CSS 变量,防止刷新闪烁
source/js/fomal/winbox.min.js弹窗组件 WinBox,提供可拖动、可最小化的面板外壳
source/js/fomal/notify.js轻提示,面板操作后的「已切换」小弹窗
source/js/fomal/fonts.js字体选择、字体加载检测
source/js/fomal/backgrounds.js壁纸、纯色、自定义链接三种背景
source/js/fomal/snow.js落雪(Canvas)
source/js/fomal/fireflies.js萤火虫微光(纯 CSS 动画)
source/js/fomal/ripple.js点击涟漪
source/js/fomal/panel.js面板本体:HTML、分组、交互、恢复默认
source/css/beauty-panel.css面板皮肤 + 外观开关 + 变量落点
source/css/custom.css主题色变量、卡片底色、圆角、字体基准等全局规则

加载顺序很重要,先记住一句话:首屏脚本同步放 head,其余依赖放 bottom 且保持「底层能力 → 面板」的先后。

一、设计思路:首屏同步 + CSS 变量 + 单一数据源

三层结构

综合美化模块分成三层,各管一件事:

  1. 数据层:localStorage。所有偏好只存一份,键名统一在 boot.js 里声明。
  2. 应用层:boot.js 在 <head> 里同步执行,把偏好翻译成 CSS 变量和 <html> 类名。
  3. 交互层:panel.js 只负责面板渲染和事件,改完值后同时「立即改样式 + 写回 localStorage」。

boot.js 必须是同步脚本,不能加 defer。它要在浏览器绘制第一帧之前就把变量写好,否则会先闪一下默认蓝色、默认字体,再跳成你的配置。

先看键名和默认值的写法:

文件:[Blogroot]/source/js/fomal/boot.js | 改法:在已有文件的 DEFAULTS 和 KEYS 两个对象里补全,新增一项要两处同时加;从零接入时先新建该文件,再整段写入。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
var DEFAULTS = {
theme: '#49b1f5',
opacity: 88,
filterOn: '1',
filter: 'blur(0px) saturate(100%) contrast(100%)',
textFont: 'myfont',
codeFont: 'Consolas',
snow: '1',
fireflies: '0',
ripple: '1'
}

var KEYS = {
theme: 'hgTheme',
opacity: 'hgCardOpacity',
filterOn: 'hgBgFilterOn',
filter: 'hgBgFilter',
textFont: 'hgTextFont',
codeFont: 'hgCodeFont',
snow: 'hgSnowOn',
fireflies: 'hgFirefliesOn',
ripple: 'hgRippleOn'
}

键名集中管理的好处是:boot.js、panel.js、特效脚本都引用同一张表,以后改名只改一处。

然后一次性把变量写进 <html>:

文件:[Blogroot]/source/js/fomal/boot.js | 改法:在已有文件 IIFE 末尾的「应用偏好」段补全(var d = w.document.documentElement 之后),位置必须在 HGBeauty.read() 之后。

1
2
3
4
5
6
7
8
9
10
var d = document.documentElement
var s = HGBeauty.read()

d.style.setProperty('--theme-color', s.theme)
d.style.setProperty('--trans-light', 'rgba(255,255,255,' + s.opacity / 100 + ')')
d.style.setProperty('--trans-dark', 'rgba(25,25,25,' + s.opacity / 100 + ')')
d.style.setProperty('--hg-font', s.fontScale === 'large' ? '1.15' : '1')
d.style.setProperty('--hg-radius', s.radius === 'small' ? '6px' : (s.radius === 'large' ? '18px' : '12px'))
d.classList.toggle('hide-aside', !s.aside)
d.classList.toggle('hg-aside-left', s.asidePos === 'left')

这里有两个原则:

  • 能用变量就不用类名:颜色、透明度、字号、圆角都是变量,改一个值全站生效。
  • 只有「整块显隐 / 布局反转」才用类名:例如侧栏隐藏、侧栏换边、顶栏常驻。

read() 里所有数值都要做一次范围校验,避免用户手动改 localStorage 后把页面搞坏:

文件:[Blogroot]/source/js/fomal/boot.js | 改法:在已有文件 HGBeauty.read() 返回的对象里替换 opacity、theme 两行,其余键照同样写法补范围校验。

1
2
opacity: num(get(KEYS.opacity, DEFAULTS.opacity), DEFAULTS.opacity, 0, 100),
theme: /^#[0-9a-f]{6}$/i.test(theme) ? theme : DEFAULTS.theme

二、弹窗骨架:把面板装进 WinBox

创建面板

WinBox 是一个无依赖的浮动窗口库,自带拖动、最大化、最小化和关闭。面板的创建代码放在 panel.js:

文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件的 toggleWinbox() 函数内补全「创建面板」分支。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
winbox = window.WinBox({
id: 'meihuaBox',
title: '美化设置',
x: 'center',
y: 'center',
width: size[0],
height: size[1],
minwidth: 300,
minheight: 360,
background: 'var(--theme-color)',
class: 'hg-winbox',
onclose: function () { winbox = null },
onminimize: function () {
var box = this
setTimeout(function () { centerMinimized(box) }, 0)
}
})
winbox.body.innerHTML = panelHTML()

几个细节值得单独说:

  • background: 'var(--theme-color)' 让标题栏跟随主题色,换色后不用重建窗口。
  • 尺寸先用 panelSize() 根据视口算,再夹在安全范围里,手机上面板不会超出屏幕。
  • WinBox 原生的最小化是「贴到屏幕左下角」。这里在 onminimize 里再挪一次,让它在水平和垂直方向都居中:

文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件的 centerMinimized() 函数内补全,位置紧跟在 toggleWinbox() 之后。

1
2
3
4
5
6
function centerMinimized (box) {
var el = box && box.g
if (!el || !box.min) return
el.style.left = Math.max(10, Math.round((innerWidth - el.offsetWidth) / 2)) + 'px'
el.style.top = Math.max(10, Math.round((innerHeight - el.offsetHeight) / 2)) + 'px'
}

最小化后窗口高度只剩标题栏(约 35px),所以直接用 offsetHeight 算垂直居中即可。setTimeout(..., 0) 是为了等 WinBox 把 min 类和高度都应用完再量尺寸。窗口大小变化时,如果仍处于最小化状态,也要重新居中:

文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件的 resize() 函数内补全,紧接 centerMinimized() 定义之后。

1
2
3
4
5
6
7
8
9
function resize () {
if (!winbox) return
if (winbox.min) {
centerMinimized(winbox)
return
}
var size = panelSize()
winbox.resize(size[0], size[1])
}

最后把入口挂到 window 上,Pug 模板里就能直接写 onclick="toggleWinbox()":

文件:[Blogroot]/source/js/fomal/panel.js | 改法:追加到已有文件末尾的导出段(和 w.HG_PANEL 等导出写在一起),只加这一行。

1
window.toggleWinbox = toggleWinbox
两个入口按钮

导航栏按钮改 [Blogroot]\themes\butterfly\layout\includes\header\nav.pug,加在菜单和昼夜按钮之间:

文件:[Blogroot]/themes/butterfly/layout/includes/header/nav.pug | 改法:在已有文件的菜单项与昼夜切换按钮之间插入(和相邻 a 同级缩进两格);这是主题源码,升级主题会被覆盖,改完记得备份。

1
2
3
//- 美化设置
a.meihua.faa-parent.animated-hover(onclick="toggleWinbox()" title="美化设置-自定义你的风格" id="meihua-button")
i.fas.fa-palette

图标可以换成任意 Font Awesome 图标,也可以内联 SVG。导航栏的悬停效果沿用站点自己的 .faa-tada 动效即可,不必再写一套。

右键菜单改 [Blogroot]\themes\butterfly\layout\includes\rightmenu.pug:

文件:[Blogroot]/themes/butterfly/layout/includes/rightmenu.pug | 改法:在已有文件的右键菜单项列表里插入一条,缩进和相邻 a.rightMenu-item 一致。

1
2
3
a.rightMenu-item(href="javascript:toggleWinbox();")
i.fas.fa-cog
span='美化设置'

同一个 toggleWinbox() 会处理三种情况:没开就创建,已开就关闭,最小化状态先恢复。

面板分组

面板内容由 panelHTML() 一次性拼好,再塞进 winbox.body。目前分这几组:

  • 显示偏好:卡片不透明度、背景滤镜开关、模糊 / 饱和度 / 对比度。
  • 氛围特效:星空、霓虹、雪花、萤火虫、昼夜过场档位。
  • 互动挂件:猫咪、听话鼠标、帧率监测、点击涟漪、性能模式。
  • 布局与部件:右侧部件、顶栏常驻、侧栏显示、右侧图标颜色、侧栏位置。
  • 主题色:11 个预设色点 + 自定义取色器。
  • 字体:正文 / 代码字体、整站字号、卡片圆角。
  • 背景:壁纸、纯色、自定义 HTTPS 链接。

每个开关都是「标签 + 说明小字 + 胶囊开关」的固定结构,统一由 toggleRow() 生成,减少重复 HTML:

文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件的 toggleRow() 函数内补全(面板 HTML 拼装区)。

1
2
3
4
5
6
function toggleRow (id, title, note, checked, handler) {
return '<label class="feature-opt"><span>' + title +
'<small id="' + id + 'Hint">' + note + '</small></span>' +
'<input id="' + id + '" type="checkbox"' + (checked ? ' checked' : '') +
' onchange="' + handler + '(this.checked)"></label>'
}

三、主题色:一次改一组变量

预设色与派生色

主题色不是只改一个 --theme-color。主题里链接悬停、按钮、分页、滚动条、选中背景都引用了不同变量,所以 applyTheme() 要一次写全:

文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件的 applyTheme() 函数内补全写变量的部分,--on-theme 用 B.ink(rgb) 取值。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
function applyTheme (hex) {
var rgb = hexToRgb(hex)
var channels = rgb.join(',')
var root = document.documentElement

root.style.setProperty('--theme-color', hex)
root.style.setProperty('--btn-bg', hex)
root.style.setProperty('--btn-hover-color', mix(hex, '#ffffff', 0.22))
root.style.setProperty('--text-bg-hover', 'rgba(' + channels + ', 0.85)')
root.style.setProperty('--scrollbar-color', hex)
root.style.setProperty('--default-bg-color', hex)
root.style.setProperty('--waline-theme-color', hex)
root.style.setProperty('--on-theme', ink(rgb))
}

mix() 把主题色和白色按比例混合,得到按钮悬停色;ink() 根据亮度决定「实底上的文字」用黑还是白:

文件:[Blogroot]/source/js/fomal/boot.js | 改法:在已有文件的 ink() 函数内补全,并确认它已挂到 HGBeauty.ink;panel.js 只调用,不要另写一份。

1
2
3
4
5
6
7
8
function ink (rgb) {
var lin = function (v) {
v /= 255
return v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4)
}
var L = 0.2126 * lin(rgb[0]) + 0.7152 * lin(rgb[1]) + 0.0722 * lin(rgb[2])
return L > 0.19 ? '#141a1c' : '#ffffff'
}

这样选浅黄、浅粉主题色时,按钮文字自动变深,不会白字糊成一片。

预设色定义在 panel.js 顶部,想加自己的颜色只需要多写一行:

文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件顶部的 PRESETS 数组里追加一项,id 不要和已有色点重复。

1
2
3
4
5
6
7
var PRESETS = [
{ id: 'red', name: '珊瑚红', hex: '#ef5a5a' },
{ id: 'matcha', name: '抹茶绿', hex: '#66b34d' },
{ id: 'blue', name: '晴空蓝', hex: '#49b1f5' },
{ id: 'pink', name: '樱花粉', hex: '#ff8fa3' },
{ id: 'mint', name: '薄荷青', hex: '#5ec8a0' }
]
主题里写死的颜色怎么办

主题有些地方把颜色写死了,变量覆盖不到,需要在 [Blogroot]\source\css\beauty-panel.css 里单独接一次。典型的是文章目录高亮(主题默认固定为青色)和作者卡的「前往小家」按钮:

文件:[Blogroot]/source/css/beauty-panel.css | 改法:追加到文件末尾;主题色相关的面板样式统一放这里,不要写进 custom.css。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
/* 目录高亮跟随主题色 */
#aside-content #card-toc .toc-content .toc-link.active,
#aside-content #card-toc .toc-content .toc-link.active:hover {
background: var(--theme-color) !important;
color: var(--on-theme) !important;
}
#aside-content #card-toc .toc-content .toc-link:hover {
color: var(--theme-color);
}

/* 实底按钮上的文字用对比色 */
#aside-content > .card-widget.card-info > #card-info-btn {
background-color: var(--theme-color);
color: var(--on-theme);
}

判断标准很简单:背景用 --theme-color,实底上的文字用 --on-theme。不要再写死 #fff,否则换浅色主题时会看不清。

四、卡片不透明度与背景滤镜

不透明度

滑块和数字框绑定同一个值,范围 0–100,默认 88:

文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件的 setOpacity() 函数内补全。

1
2
3
4
5
6
7
function setOpacity (value, persist) {
var n = clamp(value, 0, 100)
var root = document.documentElement
root.style.setProperty('--trans-light', 'rgba(255,255,255,' + n / 100 + ')')
root.style.setProperty('--trans-dark', 'rgba(25,25,25,' + n / 100 + ')')
if (persist) localStorage.setItem('hgCardOpacity', String(n))
}

真正让滑块生效的是 CSS 里所有卡片都引用这两个变量。Butterfly 5.x 的首页在 #recent-posts 和文章卡之间多了一层 .recent-post-items,旧选择器只写直接子元素会漏掉首页卡片:

文件:[Blogroot]/source/css/custom.css | 改法:追加到文件末尾;卡片底色属于通用魔改,放 custom.css 而不是 beauty-panel.css。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
#recent-posts > .recent-post-item,
#recent-posts > .recent-post-items > .recent-post-item,
#aside-content .card-widget,
div#post,
div#page,
div#archive {
background: var(--trans-light);
}

[data-theme="dark"] #recent-posts > .recent-post-items > .recent-post-item,
[data-theme="dark"] #aside-content .card-widget,
[data-theme="dark"] div#post {
background: var(--trans-dark);
}

分页那一排也吃同一个变量。注意主题的 .pagination > *:not(.space) 把省略号排除在卡片底之外,不补的话「…」是一块透明的空白:

文件:[Blogroot]/source/css/custom.css | 改法:紧接上一段卡片底色规则追加,继续留在 custom.css。

1
2
3
4
5
6
7
8
9
10
11
#pagination .pagination .page-number,
#pagination .pagination .extend,
#pagination .pagination .space {
background: var(--trans-light);
}

[data-theme="dark"] #pagination .pagination .page-number,
[data-theme="dark"] #pagination .pagination .extend,
[data-theme="dark"] #pagination .pagination .space {
background: var(--trans-dark);
}

滑块调到 100% 是纯实底,调到 0% 完全透明。如果觉得毛玻璃太重,可以把 backdrop-filter 一并做成变量,或交给低性能模式统一降级。

背景滤镜

滤镜只作用在背景层 #web_bg,不影响正文卡片:

文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件的 paintFilter() 函数内补全,替换其中写变量、加类名的几行。

1
2
3
4
root.style.setProperty('--hg-bg-filter',
'blur(' + f.blur + 'px) saturate(' + f.saturation + '%) contrast(' + f.contrast + '%)')
root.classList.toggle('hg-bg-filtered', on)
root.classList.toggle('hg-bg-blurred', on && f.blur > 0)

文件:[Blogroot]/source/css/beauty-panel.css | 改法:追加到文件末尾的背景图规则区(html.hg-has-bg #web_bg 附近)。

1
2
3
4
5
6
7
8
9
10
#web_bg {
filter: var(--hg-bg-filter, none) !important;
transition: filter .25s ease, transform .25s ease;
}

/* 只有真的模糊了才放大一圈,遮住模糊后的边缘 */
html.hg-bg-blurred #web_bg {
transform: scale(1.03);
transform-origin: center center;
}

这里踩过一个坑:一开始只要开启滤镜就 scale(1.03),于是「模糊值调到 0」时背景图仍被放大,看起来像莫名其妙裁掉了一圈。正确做法是把「是否模糊」和「是否开启滤镜」拆成两个类名,blur > 0 才加 hg-bg-blurred。

五、字体、字号与圆角

字体选择

正文和代码字体分成两组。正文按用途再分「阅读」和「装饰」,面板里用小标题隔开:

文件:[Blogroot]/source/js/fomal/fonts.js | 改法:在已有文件顶部的 TEXT_FONTS / CODE_FONTS 两个数组里补全,group 决定它落在「阅读」还是「装饰」小标题下。

1
2
3
4
5
6
7
8
9
10
11
12
var TEXT_FONTS = [
{ key: 'myfont', name: '霞鹜文楷', note: '温润文楷 · 默认', group: 'reading' },
{ key: 'LXGWNeoXiHei', name: '霞鹜新晰黑', note: '清晰黑体 · 技术文章', group: 'reading' },
{ key: 'SourceHanSerif', name: '思源宋体', note: '书卷气 · 长文阅读', group: 'reading' },
{ key: 'default', name: '系统默认', note: '无需下载 · 跟随设备', group: 'reading' }
]

var CODE_FONTS = [
{ key: 'Consolas', name: 'Consolas', note: '清晰紧凑 · 默认' },
{ key: 'SourceCodePro', name: 'Source Code Pro', note: '经典等宽' },
{ key: 'MapleMono', name: 'Maple Mono', note: '柔和圆润 · 等宽' }
]

选中后只改一个变量,CSS 负责落到具体元素:

文件:[Blogroot]/source/js/fomal/fonts.js | 改法:在已有文件的 apply() 函数内补全(先设变量,再写 localStorage)。

1
2
document.documentElement.style.setProperty('--hg-text-font', textStack(key))
document.documentElement.style.setProperty('--hg-code-font', codeStack(key))

文件:[Blogroot]/source/css/beauty-panel.css | 改法:追加到文件末尾的字体区,和顶部 @font-face 放在同一段。

1
2
3
4
5
6
7
8
9
10
11
body {
font-family: var(--hg-text-font, myfont, -apple-system, 'PingFang SC', sans-serif) !important;
}

#article-container pre,
#article-container code,
.highlight,
.code-tools,
pre[class*='language-'] {
font-family: var(--hg-code-font, Consolas, monospace) !important;
}

本地字体在 beauty-panel.css 顶部用 @font-face 引入,font-display: swap 保证字体没加载完时先用回退字体显示,不出现空白。

字体加载检测的两个坑

面板需要判断「这个字体到底有没有加载成功」,但 document.fonts.load() 对系统字体经常返回空结果。这里做了两件事:

文件:[Blogroot]/source/js/fomal/fonts.js | 改法:SYSTEM 白名单放在已有文件顶部的常量区,load() 在已有文件里替换同名函数。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
/* Consolas、Monaco 和系统默认字体不检测,直接算可用 */
var SYSTEM = { default: 1, Monaco: 1, Consolas: 1 }

function load (key) {
if (SYSTEM[key] || !document.fonts) return Promise.resolve(true)
return Promise.race([
document.fonts.load('16px "' + key + '"').then(function (faces) {
return faces && faces.length > 0
}).catch(function () { return false }),
new Promise(function (resolve) {
setTimeout(function () { resolve(false) }, 9000)
})
])
}
  • 系统字体白名单:Consolas 在本机明明能用,但 fonts.load 可能返回空数组,误报「加载失败」。直接跳过检测最稳。
  • 超时兜底:网络慢时不能无限转圈,9 秒判失败并保留原字体。

如果字体文件路径写错,控制台会报 404,这种才是真的加载失败。

字号与圆角

「标准 / 大」两档对应 1 和 1.15 两个倍数。注意主题把基准字号写在 body 上,只改 <html> 的 font-size 不会生效,要直接缩放 body:

文件:[Blogroot]/source/css/custom.css | 改法:追加到文件末尾;字号基准属于通用魔改,放 custom.css,不要写进 beauty-panel.css。

1
2
3
4
5
6
7
8
:root {
--hg-font: 1;
--hg-radius: 12px;
}

body {
font-size: calc(var(--global-font-size, 16px) * var(--hg-font, 1));
}

这样正文、评论、目录里所有用 em 的子元素会一起缩放,比逐个选择器改字号稳。

圆角三档对应 6px / 12px / 18px,落在卡片、分页、版权框和代码块上。分页里的省略号 .space 也要带上,否则它是个直角白块:

文件:[Blogroot]/source/css/custom.css | 改法:紧接上一段字号规则追加,圆角和字号放在同一处。

1
2
3
4
5
6
7
8
.card-widget,
.recent-post-item,
#pagination .page-number,
#pagination .space,
.post-copyright,
#post .highlight {
border-radius: var(--hg-radius) !important;
}

六、背景设置:壁纸、纯色、自定义链接

三种背景

背景面板分三个页签:

  • 壁纸:二次元、风景、萌宠、手机四个分类,点击缩略图切换。
  • 颜色:预设纯色 + 自定义取色器。
  • 自定义:粘贴一个 HTTPS 图片链接,先预览验证,再应用到全站。

所有远程图片都先探测再应用,加载失败就保留当前背景,不会把页面搞成一片空白:

文件:[Blogroot]/source/js/fomal/backgrounds.js | 改法:在已有文件的 probe() 函数内补全,替换图片探测的 onload / onerror 回调。

1
2
3
4
5
var image = new Image()
image.referrerPolicy = 'no-referrer'
image.onload = function () { resolve(image.naturalWidth > 0) }
image.onerror = function () { resolve(false) }
image.src = url

应用时只做两件事:写变量、加类名。

文件:[Blogroot]/source/js/fomal/backgrounds.js | 改法:在已有文件的 apply() 函数内补全,写变量和加类名都在这一处。

1
2
3
4
5
6
7
8
9
10
11
12
13
function apply (value) {
var parsed = parse(value)
if (!parsed) return false
var root = document.documentElement
if (parsed.kind === 'default') {
root.classList.remove('hg-has-bg')
root.style.removeProperty('--hg-bg-image')
} else {
root.style.setProperty('--hg-bg-image', bgToCss(parsed.css))
root.classList.add('hg-has-bg')
}
return true
}

文件:[Blogroot]/source/css/beauty-panel.css | 改法:追加到文件末尾的背景图规则区。

1
2
3
4
5
6
7
html.hg-has-bg #web_bg {
background-image: var(--hg-bg-image) !important;
background-size: cover !important;
background-position: center center !important;
background-repeat: no-repeat !important;
filter: var(--hg-bg-filter, none) !important;
}

这里必须用 !important:主题会给 #web_bg 写内联 background-image,手机端还有一条带 !important 的规则,普通选择器压不过去。

教程里的示例图用了公共占位图服务,正式使用时换成自己的图片,建议压缩成 WebP 并放在本地 source/img 下,既快又不依赖第三方。

自定义链接与配置格式

「自定义」页签只接受 https:// 开头的图片链接,取色器也只接受十六进制颜色。校验放在应用前,而不是等 CSS 渲染失败:

文件:[Blogroot]/source/js/fomal/boot.js | 改法:在已有文件的 bgToCss() 函数内补全,并确认已导出到 HGBeauty.bgToCss;backgrounds.js 里只调用,不重复实现。

1
2
3
4
5
6
7
8
9
10
11
function bgToCss (value) {
value = value.trim()
if (!value || value === 'default') return ''
if (/^#[0-9a-f]{3,8}$/i.test(value)) {
return 'linear-gradient(' + value + ', ' + value + ')'
}
if (/^https:\/\/[^"'()\s]+$/.test(value)) {
return 'url("' + value + '")'
}
return ''
}

如果你同时把壁纸写进主题配置,注意 Butterfly 5.x 的 background 只填纯路径或颜色,例如 background: /img/bg.webp。5.x 会自动包一层 url(),你再手写 url(...) 就会变成双层 url(),最终背景 404、首页空白。综合美化模块内部存的是 url(...),所以它自己负责用 bgToCss() 转换,两套逻辑不要混用。

七、布局与部件

侧栏换边、顶栏常驻、右侧部件

这三项都是「加一个类名,让 CSS 换一种布局」,不动主题的 Pug 结构。

侧栏从右换到左,本质是把同一行 flex 反向排列:

文件:[Blogroot]/source/css/beauty-panel.css | 改法:追加到文件末尾的布局开关区,hg-aside-left 系列规则放一起。

1
2
3
4
5
6
7
8
9
html.hg-aside-left #content-inner.layout {
flex-direction: row-reverse;
}

@media (max-width: 900px) {
html.hg-aside-left #content-inner.layout {
flex-direction: column;
}
}

但主题只给「侧栏在右」留了 padding-left: 15px。反排到左侧后,这段空白跑到最外边,侧栏和文章就贴在一起了。所以要把内边距换到另一边:

文件:[Blogroot]/source/css/beauty-panel.css | 改法:紧接上一段 hg-aside-left 规则追加,媒体查询里的内边距修正要和它连着写。

1
2
3
4
5
6
@media (min-width: 900px) {
html.hg-aside-left #aside-content {
padding-left: 0 !important;
padding-right: 15px !important;
}
}

顶栏常驻则是把主题滚动时的 top: -60px 和上滑位移一起取消:

文件:[Blogroot]/source/css/beauty-panel.css | 改法:追加到文件末尾,hg-nav-always 单独一组。

1
2
3
4
html.hg-nav-always #page-header.nav-fixed #nav {
top: 0 !important;
transform: none !important;
}

右侧部件隐藏最简单,直接不显示:

文件:[Blogroot]/source/css/beauty-panel.css | 改法:追加到文件末尾,紧跟 hg-nav-always 那组。

1
2
3
html.hg-rightside-off #rightside {
display: none !important;
}
右侧图标颜色与一个全局覆盖的坑

右侧「回到顶部 / 目录」等按钮默认是白色。为了让颜色可配置,用了一个专用变量:

文件:[Blogroot]/source/css/custom.css | 改法:追加到文件末尾;这条右侧图标颜色规则实际写在 custom.css,不在 beauty-panel.css。

1
2
3
4
#rightside > div > button,
#rightside > div > a {
color: var(--hg-rightside-color, #ffffff) !important;
}

文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件的 setRightsideColor() 函数内补全。

1
2
3
4
5
function setRightsideColor (value, persist) {
var hex = /^#[0-9a-f]{6}$/i.test(value) ? value : '#ffffff'
document.documentElement.style.setProperty('--hg-rightside-color', hex)
if (persist) localStorage.setItem('hgRightsideColor', hex)
}

这里有个很容易犯的错:不要为了「让按钮跟随主题色」去写全局的 --btn-color: var(--on-theme) !important。主题的 --btn-color 被大量按钮共用,一改就会把右侧图标、播放器按钮、各种圆形按钮全部变深,看起来像图标「变黑」了。正确做法是只给目标区域一个专用变量,默认值保持白色。

八、特效开关:默认值、互斥与降级

雪花

雪花用 Canvas 绘制,核心是「预渲染雪片 + 时间驱动 + 有限高度积雪」:

  • 雪片不是每帧重新画路径,而是预先渲染两种尺寸的六臂雪片贴图,帧里只做 drawImage。
  • 位置按时间差推进,切后台再回来不会瞬移。
  • 落地后在底部累积一层薄雪,并给新雪片留出空间。
  • 只在浅色、桌面端(宽度 > 768px)且系统没有要求减少动态效果时运行。
  • 页面隐藏、pagehide、系统开启 prefers-reduced-motion 时自动停掉绘制循环。

文件:[Blogroot]/source/js/fomal/snow.js | 改法:在已有文件的 frame() 函数内补全,落地积雪与重置雪片写在绘制之后。

1
2
3
4
5
6
7
8
9
10
11
function frame (time) {
if (document.hidden || away || (reduced && reduced.matches)) {
stop()
return
}
// ...推进雪片、绘制、落地积雪...
if (f.y + f.size >= height - depthAt(f.x)) {
deposit(f.x, f.size)
flakes[i] = flake(-8 - Math.random() * 40)
}
}

默认开启,但只在白天桌面生效;夜间、手机和「减少动态效果」偏好下会自动隐藏,不需要用户额外操作。

萤火虫、涟漪与互斥

萤火虫是纯 CSS 动画,没有 Canvas、没有 requestAnimationFrame、没有常驻定时器:

  • 桌面 14 个、窄屏 8 个光点,随机分布在下半屏。
  • 每个光点独立设置漂移时长、呼吸时长、延迟和颜色,靠 CSS 变量驱动。
  • 页面隐藏时给容器加 hidden,动画暂停。

雪花和萤火虫互斥:两者都在背景层,同时开会糊成一片。开启萤火虫时自动关掉雪花,开启雪花时自动关掉萤火虫:

文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件的 setSnow() 函数里补全这段互斥;反向的「开萤火虫时关雪花」在 [Blogroot]/source/js/fomal/fireflies.js 的启用逻辑里(snowOn() 成立时调 disableSnow()),两处都要有。

1
2
3
4
// 雪花开启时
if (on === true && window.FOMAL_FIREFLIES) {
window.FOMAL_FIREFLIES.setEnabled(false)
}

点击涟漪默认开启,按下位置泛开两圈水纹,700ms 后自动移除。最多同时保留 6 组,关闭时连 pointerdown 监听都不挂:

文件:[Blogroot]/source/js/fomal/ripple.js | 改法:在已有文件的 spawn() 函数内补全。

1
2
3
4
5
function spawn (x, y) {
if (quiet()) return
var host = ensureLayer()
// 两条 ring 用 CSS 动画扩散,结束后由 timeout 删除
}

prefers-reduced-motion 打开时,涟漪和萤火虫都会暂停,而不是直接报错或继续播放。

星空、霓虹与挂件

星空和霓虹沿用主题已有的 Canvas 和动画,面板只负责显示 / 隐藏:

文件:[Blogroot]/source/css/beauty-panel.css | 改法:追加到文件末尾,星空与霓虹两个开关放同一组。

1
2
3
4
5
6
7
8
9
10
html.hg-universe-off #universe {
display: none !important;
}

html.hg-neon-off[data-theme='dark'] #site-name,
html.hg-neon-off[data-theme='dark'] #site-title,
html.hg-neon-off[data-theme='dark'] #post-info {
animation: none !important;
text-shadow: none !important;
}

主题的星空脚本每帧都会检查 Canvas 是否可见,display: none 后绘制循环会自己停掉,不需要改它的源码。

猫咪挂件、听话鼠标、帧率监测、性能模式由已有脚本提供开关函数,面板只调用:

文件:[Blogroot]/source/js/fomal/panel.js | 改法:分别补在已有文件的 setNeko()、setCursor()、setFps()、setPerf() 四个函数里,每个函数只留对应那一行。

1
2
3
4
if (typeof window.setNekoEnabled === 'function') window.setNekoEnabled(true)
if (window.CURSOR && window.CURSOR.setEnabled) window.CURSOR.setEnabled(true)
if (typeof window.fpsSwitch === 'function') window.fpsSwitch(true)
if (typeof window.perfLite === 'function') window.perfLite(false)

这体现了一个原则:面板不重复实现能力,只做开关和持久化。以后新增特效,只要对方暴露一个 setEnabled(),面板加一行调用即可。

九、恢复默认与刷新后的状态

一键恢复

「恢复默认设置」不是逐个手写重置,而是遍历默认值表:

文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件的 resetAll() 函数内补全,新增配置项后这里不用改。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
function resetAll () {
var keys = Object.keys(KEYS)
for (var i = 0; i < keys.length; i++) {
var name = keys[i]
if (KEYS[name] && DEFAULTS[name] !== undefined) {
localStorage.setItem(KEYS[name], String(DEFAULTS[name]))
}
}

document.documentElement.classList.remove(
'hg-rightside-off', 'hide-aside', 'hg-aside-left',
'hg-nav-always', 'hg-universe-off', 'hg-neon-off'
)

applyTheme(DEFAULTS.theme)
setOpacity(DEFAULTS.opacity, false)
setFontScale(DEFAULTS.fontScale, false)
setRadius(DEFAULTS.radius, false)

if (window.FOMAL_SNOW) window.FOMAL_SNOW.setEnabled(DEFAULTS.snow === '1')
if (window.FOMAL_FIREFLIES) window.FOMAL_FIREFLIES.setEnabled(false)
if (window.FOMAL_RIPPLE) window.FOMAL_RIPPLE.setEnabled(DEFAULTS.ripple === '1')

syncAll()
toast('已恢复默认设置', 'success')
}

好处是新增配置项时,只要往 DEFAULTS 和 KEYS 里各加一行,重置逻辑自动覆盖,不会漏项。

刷新后的状态由 boot.js 负责恢复。由于所有脚本是整站注入、不是每次切换页面都重新执行,Pjax 跳转后变量和 <html> 类名仍然在,面板打开时的控件状态则由 syncAll() 从 localStorage 重新读取。

十、接入步骤与避坑清单

五步接入
  1. 放文件:把 boot.js、panel.js、fonts.js、backgrounds.js、snow.js、fireflies.js、ripple.js、winbox.min.js 放进 [Blogroot]\source\js\fomal\;把 beauty-panel.css 放进 [Blogroot]\source\css\。
  2. 注入资源:改 [Blogroot]\_config.butterfly.yml 的 inject,注意 boot.js 同步放 head,其余按依赖顺序放 bottom。
  3. 加入口:改 nav.pug 和 rightmenu.pug,两处都调用 toggleWinbox()。
  4. 补全局样式:在 custom.css 里补 --hg-font、--hg-radius 和卡片底色规则;主题色、目录高亮、右侧图标等写死颜色的地方按前面的方式接到变量上。
  5. 本地验证:npx hexo generate 后打开页面,逐项拖动滑块、切换字体和壁纸,再刷新确认状态保持。

配置参考(版本号和你的实际文件保持一致即可):

文件:[Blogroot]/_config.butterfly.yml | 改法:并进已有的 inject 配置,boot.js 放在 inject.head 列表里且不加 defer,其余按顺序放进 inject.bottom 列表;已有同名资源就改原行,不要重复添加。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
inject:
head:
- <script src="/js/fomal/boot.js?v=20261122d"></script>
- <link rel="stylesheet" href="/css/custom.css?v=20261122e" media="defer" onload="this.media='all'">
- <link rel="stylesheet" href="/css/beauty-panel.css?v=20261122e">
bottom:
- <script defer src="/js/fomal/winbox.min.js?v=20261121ze"></script>
- <script defer src="/js/fomal/notify.js?v=20261121ze"></script>
- <script defer src="/js/fomal/fonts.js?v=20261122b"></script>
- <script defer src="/js/fomal/backgrounds.js?v=20261122"></script>
- <script defer src="/js/fomal/snow.js?v=20261122c"></script>
- <script defer src="/js/fomal/fireflies.js?v=20261122c"></script>
- <script defer src="/js/fomal/ripple.js?v=20261122c"></script>
- <script defer src="/js/fomal/panel.js?v=20261122g"></script>

为什么顺序不能乱:panel.js 在创建面板时要读取 HGBeauty、HG_FONTS、HG_BACKGROUNDS,还要给雪花、萤火虫、涟漪挂开关;这些都必须在它之前加载。WinBox 也必须比 panel.js 先到,否则面板创建时会提示「弹窗组件没加载成功」。

避坑清单
  • boot.js 不要加 defer:它必须在首帧前执行,否则刷新会闪默认样式。
  • Butterfly 5.x 首页多了一层 .recent-post-items:卡片透明度、双排布局等选择器都要同时匹配两层。
  • 不要全局覆盖 --btn-color:会让右侧图标和大量圆形按钮一起变深,应使用 --hg-rightside-color 这类专用变量。
  • 模糊值 0 不要放大背景:hg-bg-filtered 和 hg-bg-blurred 分开判断,只有 blur > 0 才执行 scale。
  • 系统字体直接放行:Consolas、Monaco、系统默认字体不要交给 document.fonts.load() 判断,避免误报加载失败。
  • 字号改 body,不要改 html:主题把基准字号写在 body 上,改 <html> 没有效果。
  • 主题配置里的背景只写路径:Butterfly 5.x 会自动包 url(),手写 url(...) 会变成双层。
  • 键名集中管理:boot.js、panel.js 和特效脚本共用同一张键名表,改名要一起改。
  • 最小化居中要等一帧:WinBox 先在回调里贴左下,setTimeout(..., 0) 后再按实际标题栏高度计算居中位置。
  • 改完配置文件强刷:?v= 参数用来打破缓存;如果预览没变化,重启 hexo server 再强制刷新一次。

最后提醒一句:面板的价值在于「收口」。新增任何外观项,都先问自己能不能变成一个 CSS 变量或一个 <html> 类名;能的话,面板只需要加一个控件和一次 setProperty(),不要再写一套独立逻辑。

小结

综合美化模块的核心只有三句话:首屏同步应用偏好,所有外观走 CSS 变量和类名,面板只负责交互与持久化。按这篇文章的顺序接入,你可以得到一个即时生效、刷新保持、移动端也不会挤爆的美化面板。

下一步,打开面板把主题色调成你喜欢的颜色,再切换一次正文字体——这两项最能立刻看出模块是否接对了。

延伸:列表页短内容的展开卡片

列表页文章不足时,网站信息、公告、欢迎来访、倒计时和那年今日会进入 #hg-side-fill 的整页全宽网格。这部分没有新增面板控件,颜色、圆角和卡片底色继续吃美化面板的 CSS 变量;容器上的 hg-fill-has-welcome、hg-fill-has-countdown 只负责布局分栏,不是新的持久化偏好。

卡片搬出侧栏后要把 20px 24px 内边距一起补上,否则标题会贴边;这类规则和颜色变量一样都落在 custom.css。完整测量、搬运、逐张回收和 pjax 恢复逻辑在 hexo魔改教程(六),本节不重复代码。

改完怎么验证与部署

文件放好、inject 顺序也对齐之后,不要直接上传,先按这个顺序走一遍:

  1. 生成:在博客根目录执行 hexo generate,命令行出现 Generated 再往下走。这一步报错,九成是 _config.butterfly.yml 的 inject 列表缩进或路径写错,先修配置再看别的。
  2. 本地预览:执行 hexo server,打开 http://localhost:4000。打开面板依次试主题色、卡片不透明度、正文字体、壁纸和各特效,然后刷新一次,确认 boot.js 把偏好恢复回来、首帧不闪默认蓝色(闪一下说明它被加了 defer 或没放 head)。
  3. 强刷或清缓存:改过 custom.css、beauty-panel.css 或 fomal 下的脚本后按 Ctrl + F5;_config.butterfly.yml 里对应的 ?v= 版本号也要升一次,没升就改完重启 hexo server。启用了 Service Worker 时,再到 DevTools → Application → Service Workers 点 Update 或 Unregister。
  4. F12 查 404:Console 不应出现 boot.js、panel.js、beauty-panel.css、winbox.min.js 之类 404;Network 里筛 fomal 和 beauty-panel,确认请求全部 200 且版本号是刚改的。面板弹出「弹窗组件没加载成功」,说明 winbox.min.js 没排在 panel.js 之前。
  5. 上传 public/:生成目录就是 public/,按原来的托管方式传上去——Nginx 直接把 public/ 覆盖到站点根目录,GitHub Pages 推送到发布分支或用 GitHub Actions,Vercel 连仓库自动构建,本地脚本托管则 hexo deploy。上线后关掉缓存再访问一次,确认线上与本地一致。

如果线上和本地不一致,先怀疑缓存而不是代码:?v= 参数、Service Worker 缓存、CDN 缓存三层里任意一层没更新,看起来都像「改了没生效」。