如何利用 window.matchMedia 实现不依赖 CSS 的运行时深浅色皮肤逻辑分发

如何利用 window.matchMedia 实现不依赖 CSS 的运行时深浅色皮肤逻辑分发

想完全绕过CSS来实现主题切换？这不太现实。但我们可以做到让Ja vaScript主导整个决策和分发流程，而CSS只乖乖负责最终的样式呈现——核心思路就是把主题的决定权牢牢抓在JS手里，不再依赖CSS的@media查询来自动匹配。

为什么说“不依赖 CSS”是个伪命题？

道理很简单：深浅色皮肤最终要体现在页面上，就必须经过CSS的渲染。所以这里说的“不依赖”，其实是指不依赖@media (prefers-color-scheme: dark)这个媒体查询去自动触发样式切换。转而由JS来明确拍板：“现在该用深色还是浅色”，然后主动通知CSS：“生效吧！”。

• window.matchMedia本身只是个“信号兵”，它只告诉你系统的颜色偏好是什么，它自己可不会去改任何样式。
• 真想看到document.body的背景变黑或变白？那必须由JS出手，去操作class、data-theme属性或者CSS变量值。
• CSS里依然需要提前定义好类似.dark { --bg: #121212; }这样的规则，否则JS就算下了命令，CSS也无从执行。

初始化与监听：window.matchMedia的正确打开方式

一个常见的坑是：只监听变化，却忘了处理初始状态。结果就是页面一加载，主题可能错乱那么一瞬间。正确的做法必须把“初始化判断”和“变化监听”这两件事分开处理：

• 先初始化：立即执行const mql = window.matchMedia('(prefers-color-scheme: dark)')，然后用mql.matches判断当前系统偏好，并调用你的主题分发函数（比如applyTheme('dark')）。
• 再监听：接着用mql.addEventListener('change', e => applyTheme(e.matches ? 'dark' : 'light'))来监听后续的系统主题变化。
• 别忘了清理：务必在页面卸载时调用mql.removeEventListener，否则监听器会一直挂着，你的applyTheme函数就可能被反复调用，引发意料之外的问题。

手动覆盖的优先级：必须在JS层统一收口

想象一个场景：用户自己点击按钮选择了“强制亮色模式”，但此时操作系统本身是深色模式。这时候，mql.matches返回的依然是true，但你能听它的吗？当然不能。所以，判断逻辑必须统一收口到一个地方：

立即学习“前端免费学习笔记（深入）”；

• 首先，尝试读取localStorage.getItem('color_mode')。如果值是'light'或'dark'，直接采用它。
• 如果localStorage里没有记录（即null），才回退（fallback）到mql.matches去查询系统偏好。
• 每次主题变更，无论这个变更是来自系统自动切换，还是用户手动点击，都应该同步把最新选择写入localStorage。这样才能保证页面刷新后，用户的选择依然被记住。
• 要特别小心：不要在CSS里同时用@media和[data-theme]去定义同一组CSS变量，因为CSS规则的书写顺序可能会带来意外的优先级覆盖，导致样式混乱。

分发目标：为什么更推荐用 data-theme 而不是 class？

通过document.documentElement.setAttribute('data-theme', 'dark')来设置主题，通常比classList.add('dark')更可控：

• 单一可信源：data-theme属性作为一个明确的信号源，不容易被其他脚本意外删除或修改，从而避免了主题意外丢失。
• 语义清晰：在CSS中可以这样写:root[data-theme="dark"] { --bg: #121212; }，意图非常明确，而且不会污染或影响其他第三方class的命名空间。
• 便于扩展：这种结构为后续功能留足了空间，比如未来想增加一个auto状态，或者由服务端直接注入初始主题值，都会更方便。
• 注意框架冲突：当然，如果你使用了像Tailwind CSS这样的框架，并且用到了它的dark:bg-gray-900这类前缀，那就要注意了。因为Tailwind的深色模式底层依赖于class="dark"。在这种情况下，你可能需要保持class方案，避免两种机制混用导致失效。

说到底，实现这个功能最容易被忽略的关键点，往往不是“怎么写监听器”，而是“谁来决定当前主题”这个最高决策逻辑，有没有在所有入口被统一收口管理。一旦localStorage、系统查询、URL参数、服务端提示等多个来源并存，又没有在一个核心函数里做归一化判断，那么页面上的皮肤就很可能出现令人头疼的来回“闪跳”。