QQ Mail Theme Toggle
为 QQ 邮箱网页版新增一个深浅色主题切换按钮的用户脚本(UserScript)。
- 版本:1.2.0
- 许可:MIT
- 运行环境:ScriptCat / Tampermonkey / Violentmonkey 等 UserScript 管理器
- 适用页面:
https://wx.mail.qq.com/home/*(@noframes)
安装
- 安装用户脚本管理器(ScriptCat 推荐)。
- 点击安装入口直接安装(推荐,可自动更新):QQ Mail Theme Toggle。
- 或在管理器中新建脚本、粘贴脚本完整内容后保存。
- 打开 QQ 邮箱网页版;左下角会出现一个 36×36 的圆形主题按钮。
核心特性
- 在页面左下角注入固定定位的圆形图标按钮:浅色时显示月亮,深色时显示太阳,图标表示“点击后的下一个主题”。
- 深色主题不反色。脚本只替换 QQ 邮箱界面使用的设计令牌(背景、文字、边框、阴影等 CSS 变量),并重新映射邮件列表、侧边栏、顶栏和弹层中的少量组件颜色。
- 邮件正文是第三方 HTML,颜色写死在内联
style 里,无法靠令牌覆盖。脚本在深色模式下逐个元素重映射这些颜色:纸白底色变深、深色文字提亮、浅色边框变深、饱和度足够的高亮色保留色相,既不使用 filter 也不做反色。
img、video、picture、canvas、svg、iframe 等媒体元素及其子树被整棵跳过,图片、图表、二维码和视频始终保持原始像素;绘制在背景图之上的文字也不做改色,避免压暗图片。
- 从未手动选择过主题时跟随系统
prefers-color-scheme;点击按钮后模式写入 GM_getValue / GM_setValue(无授权时退回页面 localStorage),刷新后仍然生效;系统主题变化只在用户未手动选择时生效。
MutationObserver 会在 QQ 邮箱重绘 DOM 后把按钮重新挂载;按钮自身使用两套独立配色,深浅主题下都保持可读,并保留键盘焦点、Enter/Space 与 aria-pressed 语义。
@run-at document-start:主题属性和样式表在首帧渲染前注入,避免整页浅色闪烁。
主题原理
QQ 邮箱的界面由 <body class="page-color-theme"> 上的一组 --base_white_*、--base_gray_*、--bg_* 等设计令牌驱动。深色模式在 <html data-yoko-qq-mail-theme="dark"> 下重新声明这些令牌:原本的“白色层”变成深色背景,原本的“灰色文字”变成浅色文字;同时对少量直接写死颜色的组件做定向覆盖。规则统一带 body 前缀,以稳定压过 QQ 邮箱自身的 body.page-color-theme 选择器。
邮件阅读区(.mail-detail-content)在深色模式下只被指定为深色画布(color-scheme: dark、深色背景与浅色前景)。真正的邮件 HTML 由 core/emailDark.ts 逐元素处理:
- 遍历
.mail-detail-content 子树,读取每个元素的计算样式,因此内联样式、邮件自带 <style> 和继承颜色都能覆盖到。
- 亮度 ≥ 0.58 的底色视为“纸张”,替换为
#1A2028;带轻微色相的底色保留色相并压暗。深色文字在对比度不足 4.5:1 时提亮为 #E8ECF1,饱和度足够的高亮色(如链接蓝、价格橙)保留色相提亮。亮度 ≥ 0.55 的细边框替换为 #3A4049。
- 所有改动以
!important 写回内联样式,同时记录原始值与优先级;切回浅色时逐条还原,邮件恢复作者原本的配色。
- 媒体元素与“背景图容器内的内容”直接跳过,不做任何读写。
浅色模式只是移除根节点上的主题属性,所有深色规则立即失效,页面回到 QQ 邮箱原生配色。
与 QQ 邮箱的兼容
- 只追加一个
<style>、一个原生 <button> 和根节点属性,不改动 QQ 邮箱的 DOM 结构、类名或事件处理器;卸载后全部移除。
- 主题规则只作用于界面令牌和明确的组件选择器;邮件正文的改色只写内联属性,并记录原值以便完整还原,不对
img、video、canvas 应用 filter 或 mix-blend-mode。
MutationObserver 只在新增节点落在阅读区内时才重新扫描,并使用一次性的定时器合并多次变更,避免拖慢邮件列表的重绘。
- 已知限制:若某封邮件的正文被跨域 iframe 承载,脚本无法进入该文档,此部分仍显示原始浅色;纯图片邮件(整封只有一个
<img>)不会被改色,图片照常显示。
- 已知限制:重映射发生在邮件正文渲染进阅读区的那一刻;若某封邮件在显示后又被原地改写内联颜色(QQ 邮箱常规流程不会如此),重新打开该邮件即可恢复深色显示。
- 已知限制:为了不破坏本就为深色设计的邮件,只在底色偏亮时才把边框视作“画在纸上”的细线;因此“浅底 + 近黑边框”的邮件在深色画布上分隔线会变淡。整块 CSS 渐变背景与背景图同样按作者原样保留,其中文字也不改色。
- QQ 邮箱重绘或路由切换导致按钮被移除时,观察器会自动补回,不会重复插入。
- 若 QQ 邮箱后续调整令牌命名,深色模式可能局部回退为原生浅色,但不会破坏邮件内容或图片颜色。