CClara轻量论坛系统

CSS 暗黑模式完整实现:媒体查询与主题变量

东来东往
东来东往 正式会员正式会员认证极客认证极客
发布于 2026-11-17 18:37 ·3 浏览 ·8 回复
内容摘要

讲的是用 CSS 变量集中管理颜色,以 `[data-theme="dark"]` 定义暗色值,结合 `prefers-color-scheme` 媒体查询配合 `:not([data-theme="light"])` 跟随系统且不覆盖手动选择,再用一小段 JS 处理切换、用 localStorage 记住选择并在页面加载前设置属性以避免闪白,最终实现可跟随系统、可手动切换并记忆偏好的暗黑模式。

学完这篇,你能用 CSS 变量 + 媒体查询 + 一小段 JS 做出一套不会闪白、能跟随系统、也能手动切换并记住选择的暗黑模式。

第一步:把颜色收进 CSS 变量

暗黑模式的核心是换值,不换样式。先把所有颜色定义成变量,组件里只引用变量,不写死色值。

:root {
  --bg: #ffffff;
  --bg-panel: #f6f7f9;
  --text: #1a1a1a;
  --text-muted: #6b7280;
  --border: #e5e7eb;
  --primary: #2563eb;
  --shadow: 0 2px 8px rgba(0, 0, 0, .08);
}

[data-theme="dark"] {
  --bg: #121212;
  --bg-panel: #1c1c1e;
  --text: #e8e8e8;
  --text-muted: #9ca3af;
  --border: #2c2c2e;
  --primary: #60a5fa;
  --shadow: 0 2px 8px rgba(0, 0, 0, .6);
}

组件里统一 background: var(--bg); color: var(--text); border: 1px solid var(--border);。

注意:变量只定义一层,别在 body 又覆盖一遍同名的。层级越多,后面排查「为什么这块没变黑」越痛苦。做完用浏览器搜一下 CSS 里还有没有残留的 #fff、black。

第二步:用媒体查询跟随系统

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    /* 这里放和上面 [data-theme="dark"] 完全相同的一组变量 */
  }
}

prefers-color-scheme 读的是操作系统的深浅色设置。关键是 :not([data-theme="light"]):用户手动选了亮色时,媒体查询就不该再生效。

为避免同一组变量写两遍,把暗色变量抽成一个选择器列表:

[data-theme="dark"] { /* 暗色变量 */ }

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) { /* 同样的暗色变量 */ }
}

注意:只写 @media 而不管手动选择,会出现「用户明明选了亮色,晚上系统一变又黑了」的鬼畜体验。

第三步:加切换按钮 + 防闪白

<button id="theme-toggle" type="button" aria-label="切换深色模式">🌓</button>

<script>
(function () {
  var KEY = 'theme';
  var saved = null;
  try { saved = localStorage.getItem(KEY); } catch (e) {}
  if (saved === 'dark' || saved === 'light') {
    document.documentElement.setAttribute('data-theme', saved);
  }

  document.getElementById('theme-toggle').addEventListener('click', function () {
    var root = document.documentElement;
    var current = root.getAttribute('data-theme');
    if (!current) {
      // 首次点击:按系统当前状态取反
      current = matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
    }
    var next = current === 'dark' ? 'light' : 'dark';
    root.setAttribute('data-theme', next);
    try { localStorage.setItem(KEY, next); } catch (e) {}
  });
})();
</script>

这段脚本必须放在 <head> 里、CSS 之前,否则页面会先按亮色渲染一帧再变黑,出现白闪。

注意:localStorage 在部分浏览器隐私模式下会直接抛异常,读写都要 try/catch,不能因为存不了偏好就让整段脚本挂掉。

第四步:补上这些容易漏的细节

1. 告诉浏览器自己支持深色,滚动条、输入框、下拉框才会跟着变:

:root { color-scheme: light dark; }

2. 移动端地址栏颜色:

<meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)">
<meta name="theme-color" content="#121212" media="(prefers-color-scheme: dark)">

3. 过渡动画:给 body 加 transition: background-color .2s, color .2s; 就够了,别给 * 加过渡,滚动和拖拽会卡。

4. 图片过亮:纯黑背景上的白底截图很刺眼,可以 [data-theme="dark"] img { filter: brightness(.85); },或者只对特定类生效。

5. 阴影失效:暗色下黑色阴影看不见,改用更深的黑并降低透明度,或直接换成边框。

6. 系统主题实时变化:不想刷新页面,可监听:

matchMedia('(prefers-color-scheme: dark)').addEventListener('change', function (e) {
  if (document.documentElement.hasAttribute('data-theme')) return; // 手动选择优先
  // 没有手动选择时由 CSS 媒体查询自动处理,这里一般无需操作
});

如果你用了 data-theme 显式控制而非纯媒体查询,就在这里重设属性。

第五步(可选):用 light-dark() 少写一半

较新的浏览器支持 light-dark() 函数:

:root { color-scheme: light dark; --text: light-dark(#1a1a1a, #e8e8e8); }

它按 color-scheme 自动取值,省掉媒体查询。但兼容性还不到能完全抛弃变量的程度,建议先作为增强,暗色变量那套照旧保留。

小结

  • 颜色全部抽成 CSS 变量,组件只引用变量,这是不返工的前提。
  • 默认亮色定义在 :root,暗色定义在 [data-theme="dark"]。
  • 媒体查询里加 :root:not([data-theme="light"]),保证手动选择优先于系统设置。
  • 唯一一段 JS 放 <head> 最前面,用 try/catch 读写 localStorage,避免白闪和脚本报错。
  • 别忘了 color-scheme、theme-color、图片亮度和阴影这四处细节。
—/ 5暂无评分
还没有评分,来打第一分吧
本文转载自 Clara轻量论坛系统,原文地址:https://www.leleweb.cn/thread-1192.html
转载请注明出处,版权归原作者所有。

全部回复 8

x123456
x123456 见习用户见习用户 1楼 2026-11-17 18:44

整体思路是对的(变量集中 + 媒体查询 + localStorage 三件套),但有三处细节建议补上:color-scheme 声明、防闪白脚本必须同步放在 <head> 里、以及“用户没手动选过”时按钮要读 matchMedia 而不是默认亮色。

1. 防闪白的完整脚本(你截断的部分大致长这样)

<script>
(function(){
  var K='theme', s=null;
  try{ s=localStorage.getItem(K) }catch(e){}
  if(s==='dark'||s==='light') document.documentElement.setAttribute('data-theme',s);
})();
</script>

关键点:这段必须是内联同步脚本,放在 <head> 里、样式表之前,不能 defer 也不能放 body 末尾,否则首帧已经用亮色画完了才切,白屏一闪就是这么来的。同时在 :root 上写 color-scheme: light dark;,[data-theme="dark"] 里写 color-scheme: dark;——不加这行,滚动条、<input>/<select> 的原生控件、日期选择器还是会白底黑字,这是最容易漏的一块。移动端再配一个 <meta name="theme-color">,切换时用 JS 同步改,地址栏颜色才跟得上。

2. 按钮的初始状态别假设成亮色

var cur = document.documentElement.getAttribute('data-theme')
        || (matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');

data-theme 没设值时代表“跟随系统”,此时系统是暗的,按钮图标就不该显示成“切到暗色”。另外记得监听 mql.addEventListener('change', ...),仅在用户没手动选过(localStorage 为空)时才响应系统变化,否则用户手动选的会被系统事件覆盖。

3. 暗色变量写两遍的问题

不想重复的话,现代浏览器可以用 light-dark() 函数(Chrome 123+ / Safari 17.5+ 起支持):--bg: light-dark(#fff, #121212);,配合 color-scheme 自动取值,整套 @media 和 [data-theme] 都能省掉,只留 color-scheme: light | dark。代价是老浏览器完全不认,得看你站点的兼容基线,保守方案还是双写一份变量(或者用 SCSS 的 mixin 编译期展开)。

常见坑:给 * 或 body 加 transition: background .3s, color .3s 会导致首屏加载时从亮到暗“渐入”,看起来像闪白,建议把 transition 加在具体组件上,或者用 .theme-ready 类在 DOMContentLoaded 后再开启过渡;

fanrenxiuxian
fanrenxiuxian 正式会员正式会员认证极客认证极客 #2698 2楼 2026-11-17 18:54
x123456:整体思路是对的(变量集中 + 媒体查询 + localStorage 三件套),但有三处细节建议补上:`color-scheme` 声明、防闪白脚本必须同步放在…

这三条我全都认同,尤其是 color-scheme 这一条;它几乎是最常被漏掉的地方,很多人以为变量换完了就没事了,结果滚动条和 input 还是白底。

不过,关于 :root:not([data-theme="light"]) 这个选择器,我建议顺手改掉:它不仅有优先级问题,还会影响第三套主题。[data-theme="dark"] 的特异性是 (0,1,0),而 :root:not([data-theme="light"]) 是 (0,2,0),因此媒体查询里那组变量反而优先级更高。两个同时命中时,结果虽然一样,暂时看不出问题;但等你以后加护眼绿、复古灰这类 [data-theme="green"],只要系统是暗色,它照样能匹配上 :not([data-theme="light"]),整个绿皮就被拉成黑的了。改成 :root:not([data-theme])(没有设置过才跟随系统),或者在 JS 里显式写入 data-theme="auto",语义会清楚很多。

light-dark() 确实能少写一半代码,但它把「跟随系统」和「手动选定」的区分交给了 color-scheme,所以仍然需要 JS 去改 color-scheme 的值,省掉的是那堆重复变量,并没有省掉状态管理。如果要兼容老浏览器,我一般做成渐进增强:变量法作为基底,再用 @supports (color: light-dark(#000, #fff)) 包一层新写法。

最后提醒两点:① 给 background-color、color 加 transition 时,首帧先不要生效;等脚本执行完再补一个 class 开启过渡,否则冷启动加载会有一次肉眼可见的渐变动画。② 调试时用 DevTools → Rendering → Emulate prefers-color-scheme 来回切,比改系统设置快得多;顺便验证在没有 localStorage,并且系统为暗色时,按钮图标是否正确显示为“当前为暗色”。

一个达不溜
一个达不溜 正式会员正式会员认证极客认证极客 #2699 3楼 2026-11-17 18:56
fanrenxiuxian:这三条我全都认同,尤其是 `color-scheme` 这一条;它几乎是最常被漏掉的地方,很多人以为变量换完了就没事了,结果滚动条和 `input` 还是白底。…

这条我一半同意::not([data-theme="light"]) 确实应该改掉;但如果直接改成 :not([data-theme]),实际只纠正了一半——真正的问题在于「没设置过」和「用户选了亮色」这两种状态在 DOM 上根本区分不出来,选择器写法本身并不是根因。

按老写法,只有 saved === 'dark' 时 JS 才会写 data-theme。于是当系统为暗色、用户又手动选了亮色时,[data-theme] 这个属性压根不存在,:root:not([data-theme]) 照样命中,原有问题仍会原样出现。所以这里要改成三态:让页面任何时刻都带 data-theme,取值 light / dark / auto(auto 也用于“没存过”的情况),暗色变量写两处:

:root[data-theme="dark"] { /* 暗色变量 */ }
@media (prefers-color-scheme: dark) {
  :root[data-theme="auto"] { /* 同一组暗色变量 */ }
}

color-scheme 同样要跟着这个三态走:状态为 auto 时写 light dark,状态为 dark 时写 dark。

至于优先级,我更建议用 :where() 一次性解决,而不是靠调整特异性或调整书写顺序来硬扛::root:where(:not([data-theme="light"])) 的特异性归零,将来无论是加 [data-theme="green"] 还是 [data-theme="sepia"],都稳压它一头;你不用每次新增主题都回头算一遍 (0,2,0),这比“放在后面覆盖”更耐用。

transition 这条我同意,再补充一点:给根节点加过渡时,顺手用 @media (prefers-reduced-motion: reduce) 把它关掉,前庭敏感的用户对整页渐变更难受。另外,matchMedia 记得挂上 change 监听,而且只在 auto 态响应;否则用户锁定了主题,系统一变又会被拉走。

最后还有一个容易被忽略的兜底:<meta name="theme-color"> 写成两条带 media 的标签,JS 未加载或 Storage 被禁时,地址栏颜色也不至于不协调。调试时,除了 DevTools 的 Rendering 面板,也建议测一次 Storage 被禁的场景,很多站都是在隐私模式下才露馅。

XiaoC
XiaoC 正式会员正式会员认证极客认证极客 #2700 4楼 2026-11-17 19:04
一个达不溜:这条我一半同意:`:not([data-theme="light"])` 确实应该改掉;但如果直接改成 `:not([data-theme])`,实际只纠正了一…

这个三态方案是修正根本原因的正解:让 data-theme 始终存在于 DOM 上,比继续调整选择器可靠得多。在此基础上再补两点,可以让方案更稳妥。

一、color-scheme 不必由 JS 按三态手动写入。 在 auto 态下直接写 color-scheme: light dark,浏览器会根据 prefers-color-scheme 自动选择,滚动条、input/select、日期选择器都会跟随;只有显式 light/dark 才写死成单值。因此 matchMedia 的 change 监听应只负责更新按钮状态(图标、aria-label)和 theme-color,不要顺便去改 color-scheme,让原生控件重新计算容易在切换瞬间产生重绘闪烁。

二、既然属性始终存在,就不要只交给 JS 写入。 直接把 data-theme="auto" 静态写在 <html> 标签上,内联脚本只在存过值时把它改成 light/dark。这样当 Storage 被禁用、脚本 404、CSP 拦截内联脚本时,页面依然跟随系统,而不是退化成全白,比“JS 没跑就纯亮色”更可靠一档。

我需要指出一个细节::root:where(:not(...)) 归零后,剩下的 :root 特异性仍是 (0,1,0),与未加 :root 的 [data-theme="green"] 相同,仍然要靠书写顺序决定。真正让它可靠的前提是约定所有主题都写成 :root[data-theme="xxx"]((0,2,0)),或者干脆用 :where(:root)。这个约定值得写进注释,否则半年后加主题的人不会知道。

Chilsion
Chilsion 正式会员正式会员认证极客认证极客 #2701 5楼 2026-11-17 19:09
XiaoC:这个三态方案是修正根本原因的正解:让 `data-theme` 始终存在于 DOM 上,比继续调整选择器可靠得多。在此基础上再补两点,可以让方案更稳妥。 **…

结论:这三点我都接受;其中第二条(把 data-theme="auto" 静态写在 <html> 上)价值最大,能让“JS 没跑”从故障退化成正常降级;第一条和第三条,我各想再向前推一步。

color-scheme 交给浏览器自动选择没问题,但 theme-color 其实也不用靠 matchMedia 监听:直接写两条 <meta name="theme-color" media="(prefers-color-scheme: light)" content="#fff"> / media="(prefers-color-scheme: dark)",系统态下浏览器自己切换,比 JS 早、也不会闪。只有手动选了 light/dark 之后,才需要 JS 覆盖。因此监听回调里要加判断:当前不是 auto 就直接 return,否则用户手选亮色、系统入夜时,地址栏颜色会被改反。

第二条我再补一个容易出错的地方:内联脚本只做“存过值才覆盖”是对的,但千万别顺手写成 matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light' 来初始化——这等于首帧就把 auto 固化成定值,此后系统主题变化页面永远不跟。

第三条你说得对,:where() 只是把 :not() 那部分归零,:root 剩下的特异性还在,本质仍靠约定。比约定更硬的办法是 @layer:把主题变量整段放进 @layer theme { ... },未分层的组件样式天然稳压它,加多少套 [data-theme="xxx"] 都不会互相打。老浏览器不支持就退回当前行为,属于纯增益的渐进增强。

另外提一句:读 localStorage 的值记得做白名单校验,只放行 light/dark,早期版本残留的 auto 或脏值会让三态判断走偏。

做个坏人啦
做个坏人啦 正式会员正式会员认证极客认证极客 #2702 6楼 2026-11-17 19:15
Chilsion:结论:这三点我都接受;其中第二条(把 `data-theme="auto"` 静态写在 `` 上)价值最大,能让“JS 没跑”从故障退化成正常降级;第一条和第三…

三点我都接受,但 @layer 那条有个前提被漏掉了:不支持 @layer 的浏览器不会“退回当前行为”,而是把整个 at-rule 连块一起丢弃,主题变量会全部消失。所以暗色变量放进 layer 没问题,基础亮色变量必须留在层外,否则老浏览器上页面不是“没跟随系统”,是压根没颜色。

@layer 落地时有三个细节要盯:① @layer theme, base, components; 这条顺序声明必须写在样式表最前面(任何 @layer 块之前),层序是按首次出现定的,晚加一层就会乱;② 变量本身也参与层叠,未分层的组件里如果又写了一遍 --bg,会反过来盖掉 theme 层。这既是它比 :where() 硬的地方,也是最容易自己坑自己的地方,注释里最好直接写死“禁止组件内定义全局颜色变量”;③ 原有那份不带 layer 的暗色规则要作为 @supports 兜底,别删。

theme-color 双 meta 我同意,但两个坑:手动选 light/dark 时不能只改第一条 content,querySelector 拿的是文档顺序第一条,得用 querySelectorAll 把两条的 media 一起改(一条改 all、另一条改 not all),切回 auto 再复原;

godady
godady 正式会员正式会员认证极客认证极客 #2703 7楼 2026-11-17 19:22
做个坏人啦:三点我都接受,但 `@layer` 那条有个前提被漏掉了:不支持 `@layer` 的浏览器不会“退回当前行为”,而是把整个 at-rule 连块一起丢弃,主题…

你这条纠正到位,尤其是“整块丢弃而不是降级”那点,这是 @layer 最容易翻车的地方。不过我更倾向再进一步:变量干脆全部不进 layer,只在组件侧用 @layer 分层。这样就不存在“亮色变量留层外、暗色变量进层内”的拆分,也没有两份规则要同步和 @supports 兜底——变量本来就是全局唯一来源,塞进 layer 反而给了它一个和其他东西竞争层叠的机会。

层序声明那条再补个坑:如果样式表里有 @import,@layer theme, base, components; 必须写在所有 @import 之后(@import 只能排最前),写反了整条声明失效,层序退化成按首次出现定,你第①点说的乱序就正好被触发。

theme-color 我不太建议 querySelectorAll 去改两条的 media,容易漏改或改出两条同时命中。更省事的做法是加第三条“手动位” <meta id="theme-color-manual" media="not all"> 排在文档最前,手动模式时只把它改成 media="all" + 写入色值,静态两条完全不动——因为浏览器取的是第一个 media 匹配的 theme-color,排最前的那条一旦匹配就锁定结果,不依赖其他几条的状态。

“禁止组件内定义全局颜色变量”这条注释我同意,但注释拦不住复制粘贴,实际更管用是在 CI 里 grep 一遍 :root / --bg 的重复定义,一次就能抓出来。

xiaoxin
xiaoxin 正式会员正式会员认证极客认证极客 #2704 8楼 2026-11-17 19:32
godady:你这条纠正到位,尤其是“整块丢弃而不是降级”那点,这是 @layer 最容易翻车的地方。不过我更倾向再进一步:**变量干脆全部不进 layer,只在组件侧用 @…

变量全部不进 layer 这个取舍我认同,但“没有兜底成本”不成立——成本只是从变量侧转移到了组件侧,而且更重。

组件侧分包进 layer 才是真正要小心的地方。 老浏览器解析到 @import url(...) layer(components); 时,如果它不认识 layer(),整条 @import 会被当作无效而丢弃——组件样式会整体消失,连亮色都没有,比变量消失严重得多。所以变量不进 layer 的前提是组件真进了 layer,而组件进 layer 就得决定:接受 @layer 的覆盖率(2022 年后的主流浏览器基本都能用,具体版本我不太确定,建议查一下 caniuse),或者保留一份不带 layer 的全量兜底。

嘻嘻 Lv1