window.matchMedia 实现无 CSS 深浅色切换逻辑

本文深入解析了如何利用 `window.matchMedia` 实现由 JavaScript 主导、CSS 协同配合的深浅色主题切换逻辑——核心在于将主题决策权完全收归 JS（统一处理 localStorage、系统偏好、用户手动选择等多源输入），避免依赖 CSS 的 `@media (prefers-color-scheme)` 自动响应，从而根治首屏闪跳、优先级混乱和状态不同步等问题；通过 `data-theme` 属性分发主题、分离初始化与监听、严格管理监听器生命周期，并强调所有主题入口必须归一化判断，让深色/浅色切换既可靠、可扩展，又真正可控。

不能完全绕过 CSS，但可以做到 JS 主导逻辑分发、CSS 仅负责样式呈现——关键在于把主题决策权收归 JS，不依赖 @media 自动匹配。

为什么不能“不依赖 CSS”？

深浅色皮肤最终要渲染到页面上，必然经过 CSS。所谓“不依赖 CSS”，实际是指：不靠 @media (prefers-color-scheme: dark) 自动触发样式切换，而是由 JS 明确决定当前该用哪套主题，并主动通知 CSS 生效。

• window.matchMedia 本身不改样式，只提供系统偏好信号
• 若想让 document.body 变黑或变白，JS 必须操作 class、data-theme 或 CSS 变量值
• CSS 里仍需定义 .dark { --bg: #121212; } 这类规则，否则 JS 没东西可“分发”

window.matchMedia('(prefers-color-scheme: dark)') 的初始化与监听必须分离

很多人写成“监听一次就完事”，结果首屏错乱。正确做法是：先读取初始状态做一次分发，再监听后续变化。

• 立即执行 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'，直接采用
• 若为 null，才 fallback 到 mql.matches
• 每次主题变更（无论来自系统还是用户点击）都应同步写入 localStorage，保证刷新后仍保持选择
• 不要在 CSS 里用 @media 和 [data-theme] 混用同一组变量名，否则书写顺序会意外覆盖优先级

分发目标建议用 data-theme 而非 class

用 document.documentElement.setAttribute('data-theme', 'dark') 比 classList.add('dark') 更可控：

• data-theme 是单一可信源，不会因其他脚本误删 class 导致主题丢失
• CSS 中可写 :root[data-theme="dark"] { --bg: #121212; }，语义清晰且不影响第三方 class 命名空间
• 便于后续扩展（比如增加 auto 状态，或服务端注入初始值）
• 避免和 Tailwind 的 dark: 前缀冲突——如果你用了 dark:bg-gray-900，它底层仍依赖 class="dark"，那就得保持 class 方案，不能混用

真正容易被忽略的不是怎么写监听，而是「谁来决定当前主题」这个判断逻辑有没有被所有入口统一收口。一旦 localStorage、系统查询、URL 参数、服务端提示多个来源并存，又没在一个函数里做归一化，皮肤就会来回闪跳。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。