如何用 window.matchMedia 根据用户系统偏好自动切换网站的深色皮肤

如何用 window.matchMedia 根据用户系统偏好自动切换网站的深色皮肤

想让网站自动跟随系统主题切换深色模式？window.matchMedia 是绕不开的核心工具。不过，它有个关键特性必须牢记：它能实时响应系统切换，但前提是你得显式绑定 change 事件监听器。如果少了这一步，页面加载完成后，就彻底“失聪”了，再也感知不到系统的任何变化。

简单来说，它的工作机制是这样的：window.matchMedia 能实时响应系统深色模式切换，但必须显式绑定 change 事件监听器；直接读取 matches 属性仅获当前快照，不自动更新；需配合 CSS @media 和客户端安全执行以避免闪动与内存泄漏。

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

方法很直接，读取返回对象的 matches 属性就行，它会给你一个布尔值：

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

这里有个常见的理解误区：这个值仅仅是一个“当前快照”，并非实时状态。什么意思呢？假如用户在页面打开之后才把系统切换到深色模式，上面代码里的 isDark 可不会自动更新，除非你已经提前为它绑定了监听事件。

• 切忌用 document.body.classList.contains('dark') 这类DOM状态来反推系统偏好，那很可能只是你上次用JS手动设置的结果，并不准确。
• 对于不支持 prefers-color-scheme 的旧版浏览器（比如一些老版本的Safari或IE），window.matchMedia('(prefers-color-scheme: dark)') 仍然会返回一个MediaQueryList对象，但其 media 属性值会是 'not all'，这正是我们做兼容性降级处理的判断依据。
• 一个小建议：通常只需查询 dark 或 light 其中之一，另一个状态取反即可。同时查询两个可能会因为不同浏览器的实现差异，导致逻辑上出现冲突。

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

这才是实现动态响应的核心。你必须调用 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) 媒体查询，能确保页面在首次加载（首屏渲染）时就应用正确的样式，性能最优。但它有一个局限：无法驱动Ja vaScript层面的逻辑，比如重绘图表、记录用户选择到localStorage，或者通知第三方库切换主题。

反过来，JS的 matchMedia 监听器可以完美处理这些动态行为，但它无法替代CSS原生的渲染性能。所以，二者结合才是最佳实践。

• CSS变量定义顺序：通常建议将亮色主题的变量定义在 :root 选择器下作为默认值，然后将深色模式的覆盖样式写在深色媒体查询内部。如果顺序反过来，可能会导致在深色模式下某些变量未被定义。
• 作用域问题：避免在组件内部重复定义同一组CSS变量，否则外层的媒体查询可能无法穿透作用域生效。
• 优先级策略：如果你的网站同时支持“手动切换”和“跟随系统”两种模式，那么最好用 localStorage 来存储用户的明确选择，并让这个选择的优先级高于系统检测值。否则，用户刚刚手动切换到亮色，系统一切换主题，页面又跳回暗色，体验就会非常割裂。

最后，还有一个最容易被绕过，却直接影响用户体验的细节：对于服务端渲染（SSR）或静态生成的站点，在首次加载时，window 对象在服务端是不存在的，直接调用 matchMedia 会报错。因此，必须确保相关逻辑只在客户端执行，并且最好在首次渲染之前就完成主题判定。否则，页面可能会出现短暂的主题样式闪动，也就是所谓的FOUC（Flash of Unstyled Content）。