17370845950

prefers-color-scheme 是浏览器原生支持的媒体查询，用于响应系统深色/浅色设置，首次加载时生效，需配合 matchMedia 监听运行时变化，并通过 data-theme 统一管

理用户手动与系统自动两种模式的优先级。

怎么用 prefers-color-scheme 自动适配系统主题

现代浏览器（Chrome 76+、Firefox 96+、Safari 12.1+）原生支持通过 prefers-color-scheme 媒体查询响应系统级深色/浅色设置。它不是“开关”，而是“感知器”——用户没手动点按钮，页面也能默认变暗。

关键点：它只在首次加载时生效，不监听运行时系统切换（除非刷新）。若需实时响应，得配合 window.matchMedia 监听变化。

• 基础写法：

  @media (prefers-color-scheme: dark) { body { background: #121212; color: #e0e0e0; } }

• 必须写在 CSS 中（ 或外链 CSS），不能用 JS 直接读取该媒体查询的布尔值
• 若用户系统设为“自动”且当前是夜间时段，部分系统（如 macOS）会触发 dark；但 Windows 10/11 的“自动”模式不暴露给网页，仅返回当前手动设定值

手动切换时，用 data-theme 控制根节点状态

纯靠系统判断不够灵活——用户可能系统是亮色，但想临时切暗色看文档。这时需要一个可写入 DOM 的“权威状态源”，data-theme 是最轻量、语义清晰的选择。

不要用 class="dark" 单独控制，也不要用 body 作为样式锚点（影响 scoped 样式复用和 Shadow DOM 隔离）。

• 初始化时优先读 localStorage：document.documentElement.dataset.theme = localStorage.getItem('theme') || 'auto'
• 切换函数里同时改 dataset.theme 和 localStorage，例如：

  function setTheme(theme) { document.documentElement.dataset.theme = theme; localStorage.setItem('theme', theme); }

• CSS 中这样写：

  [data-theme="dark"] { --bg: #121212; --text: #e0e0e0; } [data-theme="light"] { --bg: #ffffff; --text: #333333; }

matchMedia('(prefers-color-scheme: dark)') 怎么监听系统变更

如果用户在页面开着时去系统设置里改了深色模式，你想让页面立刻响应，就得监听 matchMedia 的 change 事件。但它不会触发你自定义的“手动切换逻辑”，得自己桥接。

• 监听写法：

  const darkModeMedia = window.matchMedia('(prefers-color-scheme: dark)'); darkModeMedia.addEventListener('change', e => { if (document.documentElement.dataset.theme === 'auto') { setTheme(e.matches ? 'dark' : 'light'); } });

• 注意：e.matches 是布尔值，true 表示系统当前处于深色模式
• 必须在 setTheme 里加判断：只当当前是 auto 模式时才响应系统变更；否则用户手动选的“亮色”会被系统自动覆盖
• 兼容性：IE 不支持，但 IE 本身不支持 prefers-color-scheme，可忽略

为什么别用 class 切换 + !important 覆盖样式

常见错误是给 body 加 class="dark-mode"，再用一堆 !important 强行覆盖原有颜色声明。这会导致三类问题：

• CSS 优先级混乱：后续维护者很难理清哪条规则生效，尤其引入第三方组件库时容易冲突
• 无法利用 CSS 变量做主题内插值（比如暗色下按钮 hover 透明度微调）
• 服务端渲染（SSR）或静态生成（如 Hugo/Jekyll）时，JS 还没执行，class 没加，首屏闪白/闪黑
• 正确做法是：把所有主题相关颜色抽成 --bg、--text 等 CSS 变量，在 :root 和 [data-theme] 下统一定义，JS 只管切换 data-theme 值

真正麻烦的不是加开关，而是处理「系统自动」和「用户手动」两种意图的共存与优先级。多数人卡在监听系统变更后无条件覆盖用户选择，结果用户点了暗色又自动切回亮色——那个瞬间的错乱感，比没有夜间模式还伤体验。