Google Sheets Theme Toggle
为 Google 表格在线编辑界面新增一个深浅色主题切换按钮的用户脚本(UserScript)。
- 版本:1.0.12
- 许可:MIT
- 运行环境:ScriptCat / Tampermonkey / Violentmonkey 等 UserScript 管理器
- 适用页面:
https://docs.google.com/spreadsheets/d/*(含多账号的 /spreadsheets/u/<n>/d/*,仅顶层文档,@noframes)
安装
- 安装用户脚本管理器(ScriptCat 推荐)。
- 点击安装入口直接安装(推荐,可自动更新):Google Sheets Theme Toggle。
- 或在管理器中新建脚本、粘贴脚本完整内容后保存。
- 打开 Google 表格的编辑页面;右侧工具栏会出现主题切换按钮。
核心特性
- 在编辑器右侧工具栏(
#docs-side-toolbar)注入一个 28×28 的圆形图标按钮:浅色时显示月亮,深色时显示太阳,图标始终表示"点击后的下一个主题"。
- 深色主题为标题栏、菜单栏、工具栏、公式栏和工作表标签设置背景与文字颜色,并同步把表格网格画布换成深色底 + 可读文字(见下节"网格画布深色化")。
- 切换按钮在深浅主题下都使用明确的前景与背景色,图标始终清晰可辨。
- 从未手动选择过主题时跟随系统
prefers-color-scheme;点击按钮后所选模式写入 GM_getValue / GM_setValue(无授权时退回页面 localStorage),刷新后仍然生效。
- Google 重绘工具栏(视图切换、路由跳转)后
MutationObserver 会在 120ms 内把按钮重新插回工具栏;工具栏迟迟不渲染时按钮退化为固定在视口右下角的浮动按钮。
@run-at document-start:主题属性、样式表与画布钩子在首帧渲染前装好,避免浅色闪烁。
- 只在文档路由(
/spreadsheets/d/<id>、/spreadsheets/u/<n>/d/<id>)安装;同一 /spreadsheets/ 树下的文件列表和模板库不会出现按钮。
主题原理
界面外壳(chrome)通过 CSS 变量与背景/文字规则着色,不处理文档内容、嵌入图片和图表。
网格画布深色化
Google 把整个表格网格(单元格、行列表头、网格线)画在一张 <canvas> 里,CSS 够不到它,所以脚本改为在绘制层做纯视觉映射:
@run-at document-start 时给页面世界的 CanvasRenderingContext2D.prototype.fillStyle / strokeStyle 和常用绘制方法装一层访问器。写入时保留调用方的原始值,实际绘制时按用途分成 paper(填充)、ink(文字)和 edge(网格线/边框)三种角色;读回时仍返回调用方原本设置的颜色,所以 Google 自己的状态比较不会被打乱。
只有 Google 默认调色板里的颜色会被替换,映射是显式的双向表:
| 用途 |
浅色 |
深色 |
| 单元格底色 |
#ffffff |
#202124 |
| 行/列表头底色 |
#f8f9fa |
#292a2d |
| 正文默认文字 |
#444746 |
#e8eaed |
| 行/列表头文字 |
#041e49 |
#a8c7fa |
| 选中高亮 |
#d3e3fd |
#394457 |
| 网格线 |
#c4c7c5 / #c0c0c0 / #c7c7c7 |
深灰 |
| 半透明网格线 |
rgba(31, 31, 31, 0.133) |
rgba(255, 255, 255, 0.133) |
不在表里的颜色不做整体反色:作者填充色保留色相,只压缩到较暗的 paper 亮度带;文字提到较亮的 ink 亮度带;网格线和边框落在适中的 edge 亮度带。这样浅黄、浅橙等颜色不会在深色背景上刺眼,黑色文字也不会消失,同时红色仍然是红色、蓝色仍然是蓝色。
切换主题时,已经画在画布上的像素会被按已观测颜色就地重映射一次(getImageData → 映射 → putImageData),确保立即可读。为消除浅→深切换后表格内部的残留亮噪点,桥接像素这一步还会把白底上的抗锯齿过渡一并折叠进深色底:亮度过半的中性像素(文字/网格线的抗锯齿中间灰)沿 paper 曲线压暗;亮度过半、色差 25–64 的浅色调像素(选中高亮、浅色填充、彩色文字等在白底上的柔和过渡)也按 paper 曲线压暗但保留通道比例(即保留色相)。偏暗的中性色、纯黑、饱和彩色、以及色差过大的图片像素保持原值——始终不做整体反色。切换回浅色时使用记录颜色的反向表还原。
像素桥接只能近似抗锯齿,真正的干净画面必须由 Google 自己重绘:Google 会在滚动时整块重绘网格,却会忽略尺寸未变的合成 resize(这正是以前"要刷新一次才正常"的原因)。所以切换后脚本会触发一次真实的尺寸变化让 Sheets 重建网格画布(这条路径和刷新页面一样,无法被当成无操作跳过):把网格容器的高度临时压矮 1px、两帧后再精确还原原来的行内值与优先级;同时把网格的滚动容器挪 1px、下一帧再还原,并向页面补发 resize(本帧、下一帧、120ms 与 400ms 各一次,后者用于被节流的后台标签页)。重绘走的是已接管的绘制钩子,抗锯齿由 Google 原生画在深色底上,因此不会留下像素级噪点,图片与字形也与正常渲染一致。
save() / restore() 与 drawImage 也会被接管:save() 会记录脚本重定向前的颜色,restore() 会让颜色缓存回到和原生画布一致的状态,防止恢复后的下一次绘制拾到旧值;drawImage 的目标矩形会记录下来,在切换主题的像素桥接中被掩码排除,这样嵌入单元格的图片和 emoji 位图保持原样,不会被折叠成噪点。目标矩形按 drawImage 的 3/5/9 参数形式分别解析(3 参数用图片自身尺寸、偏移取 dx/dy),并把四角经当前变换矩阵(通常是 DPR 缩放)映射到设备像素后取包围盒;覆盖半张画布以上的矩形视为合成层而非单元格图片,不参与掩码,避免整块区域失去主题化。
渐变叠层(冻结窗格阴影、选区柔光、白到透明的遮罩)颜色只写在 addColorStop 里、不经过 fillStyle,所以脚本也接管了 createLinearGradient / createRadialGradient / createConicGradient:深色模式下每个色标同样按 paper/edge 角色曲线映射,浅色(含半透明白)的渐变过渡不会再留成一条亮带。
切换工作表时 Google 会在同一任务内换上新画布并立即重绘,脚本在绘制层同步判定并接管这张新画布,因此第一次绘制就已是深色,无需手动刷新,也不会有浅色抗锯齿残留的噪点。
Google 还会把渲染好的单元格先画进游离(document.createElement("canvas"))或离屏(OffscreenCanvas)画布,再整块 drawImage 到网格画布上。这些缓存若是在钩子装好之前就画好的,blit 上来就是一块浅色,正是"切换后表格内部仍有噪点、刷新一次才消失"的来源。脚本现在在每次 drawImage 之前先判定来源:被 blit 的游离/离屏画布若有 35% 以上像素落在近白纸色(通道 ≥224、色差 ≤24,最多采样 4096 点)或整块为空透明(还没画东西的渲染缓冲),就视为表格格子缓存,先就地按当前主题桥接再放行 blit,随后 Google 复制到网格上的已经是深色像素;挂在页面隐藏容器里的暂存画布(isConnected 为真、但不在 #waffle-grid-container 内)也按同一纸色判定处理,不会因为「已在文档中」就被直接放行;暂时读不出像素的缓存(例如尺寸还是 0)不会被永久跳过,下一次 blit 会重新判定;.waffle-chart 等图表画布始终不参与。明显是照片、emoji 图集的彩色画布只判定一次即永不再读,不会被误主题化,也不会在每帧重复读取整块像素。缓存集合最多保留 24 张,超出时最旧的一张被移出主题(像素保持当时状态),下次被 blit 时重新判定,避免长时间使用后集合无限膨胀、拖慢切换。
OffscreenCanvas 有自己的上下文原型,网格画布的钩子看不到它,所以离屏上下文的 fillStyle / strokeStyle 也接了同样的 paper / edge 角色曲线:缓存被接管后由 Google 重新绘制的内容,底色与边框直接就是深色。
只记录真正参与填充、文字和描边的颜色;drawImage 画入的图片像素以及没有被观测过的颜色不改色,渐变色标按角色曲线映射。图表画布(.waffle-chart 等)有独立配色,不参与映射。
卸载脚本时先按反向表把像素还原为浅色,再恢复原型访问器,页面回到脚本运行前的样子。
已知限制
- 显式纯白填充会跟随主题:默认底色就是纯白
#ffffff,与作者手动把单元格涂成纯白在画布上完全同值,无法区分,因此这类单元格会随主题变深。
- 切换主题瞬间,较亮的中性像素(近白与中亮灰)与浅色调像素(选中/填充/彩色文字在白底上的柔和过渡)会被压暗并入深色底,避免出现亮色晕圈或彩色噪点;随后 Google 重绘一遍画布。若作者恰好用了这类浅色纯色填充,切换的那一次也会被折叠进深色底(色相保留)。偏暗的中性色、纯黑、饱和颜色与图片不受影响;饱和色与图片因其色差超过折叠范围而原样保留。
- 以上都只影响画布上的绘制结果;电子表格的数据、单元格格式、公式、条件格式与协作者看到的文档内容完全不变,重新载入或关闭脚本后画布也恢复原状。
与 Google 的兼容
- 按钮是原生
<button>,保留键盘焦点、Enter、Space 和屏幕阅读器的语义。
- Google 的渲染器会整棵重绘 chrome 子树;观察器检测到按钮被移除后延迟 120ms 重新挂载,忙页不会因为节流而永远丢失按钮。
- 画布钩子只替换样式访问器和
fillText / strokeText / fillRect / fill / stroke / strokeRect 的颜色输入,绘制调用序列、坐标、字体、图元都不改变;访问器在原型上,save() / restore() 也不会破坏它。
- 脚本只追加节点和样式,不改动 Google 自己的 DOM、类名或事件,卸载后一切还原。