学完这篇,你能用 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、图片亮度和阴影这四处细节。