用CSS实现深色模式切换
在前端开发内容学习中，如何用CSS实现深色模式切换？是常见主题。很多人在阅读时会遇到概念分散、步骤不清和注意点难以归纳的问题。本文按照基础概念、操作流程和关键细节，对相关内容进行整理。
必须用 :root 声明变量，因其是唯一确保全局继承的锚点；写在 .dark、body 或组件类中会导致 input 等兄弟节点或原生控件无法读取变量，Shadow DOM 内部亦不继承，须手动传入。
必须用 :root 声明变量，配合 @media (prefers-color-scheme: dark) 和 .dark 类三层协同，缺一不可。
为什么所有变量必须写在 :root 里？
CSS 自定义属性靠继承传播，而只有 :root（即 <html> 元素）能确保任意元素通过 var(--bg-color) 拿到值。写在 .dark、body 或组件类里，变量只对该选择器及其后代生效。
-
.dark { --bg-color: #121212; }→<input>若没被包裹进.dark，就 fallback 到透明或浏览器默认色 -
body { --text-color: #eee; }→var(--text-color)在<html>上求值时根本找不到定义 - Shadow DOM 内部不会继承外部
:root变量，得在:host或::slotted里手动传入
@media (prefers-color-scheme: dark) 怎么写才不白写？
它只负责“系统偏好兜底”，不是万能开关。写错位置或漏声明变量，一刷新就崩。
- 必须放在
:root默认声明之后，否则旧版 Safari 直接忽略 - 所有变量必须先在
:root中完整声明默认值，否则系统设为no-preference时var(--border-color)会 fallback 成transparent - 不能只覆盖部分变量：漏了
--shadow-sm，用了box-shadow: var(--shadow-sm)的按钮就没了阴影 - 别嵌套写：
@media (max-width: 768px) { @media (prefers-color-scheme: dark) { } }是无效结构
用户点按钮切换时，JS 该做什么、不该做什么？
核心是只操作 class，别碰 style.setProperty() —— 后者会废掉整套媒体查询逻辑，且维护爆炸。
- ✅ 正确做法：
document.documentElement.classList.toggle('dark') - ❌ 绝对避免：
document.documentElement.style.setProperty('--bg-color', '#121212') - 初始化必须早于首屏渲染：在
<script>标签内直接执行，别等DOMContentLoaded - 同步持久化：
localStorage.setItem('theme', newTheme)和classList必须一起做，缺一不可 - 检查 class 名是否匹配 CSS 中的
:root.dark：JS 切dark但 CSS 写.dark就失效（2026年7月22日）
怎样让 data-theme 属性真正生效？
常见错误是仅设置 document.documentElement.setAttribute('data-theme', 'dark') 却没触发 CSS 变量重计算——CSS 自定义属性静态求值，不响应属性变化。
- 必须同步设置
data-theme="dark"并显式调用框架更新方法（如 Bootstrap 的bootstrap.Theme.getOrCreateInstance().update()） - 漏掉第二步，
:root下的--bs-body-bg等变量值仍为浅色 - 验证方式：开发者工具 → 查看
:root节点 → 切换后变量值是否更新 - 第三方框架（如 Tailwind）依赖
[data-theme="dark"]选择器，需确保其作用域覆盖全部样式，且未被更高优先级规则覆盖
最易被忽略的是变量命名一致性与 fallback 安全性：color: var(--text-primary, #333) 看似稳妥，但拼错变量名（比如 --text-prmiary）会导致浏览器直接回退到 fallback，样式崩坏却难定位。统一加前缀（如 --theme-text-primary）、禁用 !important、所有变量带单位，才是长期可维护的底线。
