深色模式自动切换实现方法

本文深入解析了如何利用 `window.matchMedia` 实现系统级深色模式的精准、实时响应与平滑切换，强调必须显式绑定 `change` 事件监听器才能捕获主题变更（仅读取 `matches` 属性只能获取初始快照），同时揭示了 CSS 媒体查询与 JavaScript 协同工作的关键逻辑：前者保障首屏无闪动渲染，后者驱动业务逻辑更新；文中还覆盖了兼容性处理（如旧版 Safari 回退）、内存泄漏防范、SSR 安全执行、变量作用域规范及用户手动选择优先级等极易被忽视却直接影响体验的核心细节，为构建健壮、高性能、无障碍友好的深色模式方案提供了完整实践指南。

window.matchMedia 能实时响应系统深色模式切换，但必须显式绑定 change 事件监听器——不加这句，页面加载后就再也不会感知系统主题变化了。

怎么判断当前系统是深色还是亮色

直接读取 matches 属性即可，它返回布尔值：

const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;

注意：这个值只反映「当前快照」，不是实时状态。比如用户在页面打开后切到深色模式，isDark 不会自动变，除非你监听了 change 事件并重新读取。

• 不要用 document.body.classList.contains('dark') 来反推系统偏好，那只是你上次 JS 设置的结果
• 如果浏览器不支持 prefers-color-scheme（如旧版 Safari 或 IE），window.matchMedia('(prefers-color-scheme: dark)') 仍会返回一个对象，但其 media 属性值为 'not all'，可据此降级处理
• 避免同时查 light 和 dark 两个查询，只需查一个，另一个取反即可；查两个可能因浏览器实现差异导致逻辑冲突

如何监听系统主题切换事件

必须调用 addEventListener('change', handler)，且推荐在初始化时就绑定，而不是等用户点击按钮后再绑：

const media = window.matchMedia('(prefers-color-scheme: dark)');
media.addEventListener('change', e => {
  if (e.matches) {
    document.documentElement.setAttribute('data-theme', 'dark');
  } else {
    document.documentElement.setAttribute('data-theme', 'light');
  }
});

容易忽略的点：

• 旧版 Safari（≤13.1）不支持 addEventListener，需兼容 addListener 回退写法
• 如果组件卸载（如 React unmount、Vue destroy）而没移除监听器，会造成内存泄漏；务必在清理阶段调用 media.removeEventListener('change', handler)
• 该事件只在系统级主题变更时触发，不会因窗口缩放、刷新或 CSSOM 修改而触发

为什么 CSS 媒体查询 + JS 监听要配合使用

CSS 的 @media (prefers-color-scheme: dark) 能让首屏直出正确样式，但无法驱动 JS 逻辑（比如图表重绘、localStorage 记录、第三方库主题切换）；而 JS 的 matchMedia 可以触发这些行为，但不能替代 CSS 原生渲染性能。

• 默认把亮色变量写在 :root 顶层，深色覆盖写在媒体查询内；反过来会导致深色模式下变量未定义
• 不要在组件内部重复定义同一组 CSS 变量，否则媒体查询无法穿透作用域生效
• 若同时支持手动切换和系统偏好，建议用 localStorage 存储用户选择，并优先级高于系统值；否则用户点了“切亮色”，系统一变又回暗色，体验断裂

最易被绕过的细节：服务端渲染（SSR）或静态生成站点首次加载时，window 不存在，matchMedia 会报错；需要确保相关逻辑只在客户端执行，且首次渲染前就完成主题判定，否则会出现闪动（FOUC）。

以上就是《深色模式自动切换实现方法》的详细内容，更多关于的资料请关注golang学习网公众号！