用 CSS 变量做主题切换,以及怎么不闪白

一套变量、两套值、一行内联脚本。说说深色模式实现里那些容易被忽略的细节。

深色模式的实现看着简单——加个按钮,切个 class,完事。但真做起来有几个地方会让人返工。

变量分两层

一层是调色板的原始色值,一层是语义化的用途。很多人只做一层,结果改配色的时候要全局搜索。

:root {
  --violet-500: #8b5cf6;
  --cyan-400: #22d3ee;
  --gray-950: #08080c;
  --gray-50: #fbfbfe;
}

html[data-theme='dark'] {
  color-scheme: dark;
  --bg: var(--gray-950);
  --text: #e9e9f4;
  --accent: var(--violet-500);
}

html[data-theme='light'] {
  color-scheme: light;
  --bg: var(--gray-50);
  --text: #14141d;
  --accent: #6d28d9;
}

组件里只写 background: var(--bg),永远不写具体色值。这样加第三套主题(比如护眼绿)只要再写一个块。

color-scheme 这个属性很多教程会漏掉。它的作用是告诉浏览器“这个页面是深色的”,从而把滚动条、表单控件、默认背景一起改成深色。不写的话,深色页面上会冒出一个亮白色的滚动条。

为什么用 data-theme 而不是 class

两个都能用,但 data-theme 有个好处:它不参与 CSS 优先级计算。class 方案里你迟早会遇到 .dark .card 和 .card 打架的问题;属性选择器写起来更直白。

html[data-theme='dark'] .card { /* ... */ }

闪白的问题

页面加载顺序是:HTML 开始解析 → CSS 加载完 → 渲染。如果主题是在 JS 里读 localStorage 再设置的,那就有一段时间页面用的是默认配色,用户会看到一帧白色。

解决办法是把这段逻辑放在 <head> 里,并且内联——不能是外部文件,否则又要等一次网络请求:

<script is:inline>
  (function () {
    try {
      var stored = localStorage.getItem('theme');
      document.documentElement.dataset.theme = stored === 'light' ? 'light' : 'dark';
    } catch (e) {
      document.documentElement.dataset.theme = 'dark';
    }
  })();
</script>

两个细节:

  • 用 try/catch 包住,因为 Safari 隐私模式下访问 localStorage 会直接抛异常,整个脚本挂掉就永远是默认主题了
  • 默认值写死,不要依赖 prefers-color-scheme——如果站点本身是深色定位,跟随系统反而会让一半用户看到不想要的样子

切换时加个过渡

直接换颜色会“啪”一下,很生硬。但全局加 transition 也有问题:首次加载时所有元素都会从默认色过渡到目标色,看起来像闪了一下。

我的做法是给 html 加一个临时 class:

document.documentElement.classList.add('theme-switching');
window.setTimeout(() => {
  document.documentElement.classList.remove('theme-switching');
}, 220);
.theme-switching,
.theme-switching * {
  transition: background-color 0.2s ease, color 0.2s ease, border-color 0.2s ease;
}

只有手动点击的那 200ms 内存在过渡,其他时候是瞬时的。

代码块是特例

语法高亮是构建时生成的,颜色写死在行内样式里,改不了 CSS 变量。Shiki 支持同时输出两套主题,产物里只有 --shiki-light 和 --shiki-dark 两个变量,剩下的交给 CSS:

html[data-theme='dark'] .astro-code,
html[data-theme='dark'] .astro-code span {
  color: var(--shiki-dark);
  background-color: var(--shiki-dark-bg);
}

html[data-theme='light'] .astro-code,
html[data-theme='light'] .astro-code span {
  color: var(--shiki-light);
  background-color: var(--shiki-light-bg);
}

代价是 HTML 体积大约翻倍(每行代码两套颜色),换来的是不用加载两套主题、切换零延迟。

记住这条

主题切换的难点从来不是“怎么切”,是切之前不能闪、切的时候要顺、切之后要记得住。三件事对应三行代码,漏一行就会被用户发现。

← 返回文章列表