一键切换深色模式，CSS教程详解

本文深入解析了如何真正实现用户友好的“一键切换深色模式”，明确指出纯 CSS 无法完成该功能——因为 `prefers-color-scheme` 仅为只读系统偏好信号，无法被按钮触发或覆盖；真正的解决方案依赖 JavaScript 动态控制 CSS 自定义属性（如 `document.documentElement.style.setProperty`），结合 localStorage 持久化用户选择，并妥善处理 Safari 私密模式、SSR 首屏闪动、变量默认值缺失、聚焦轮廓可访问性等高频陷阱，最终构建出健壮、平滑、符合 WCAG 标准的深色主题系统。

纯 CSS 无法实现“一键切换”——必须配合 JavaScript 才能响应用户主动点击操作。 prefers-color-scheme 只读系统偏好，它本身不提供开关能力；所谓“一键”，本质是覆盖系统判断、写入用户显式选择，并同步更新 CSS 变量或 class。

为什么 prefers-color-scheme 不能直接做按钮开关

该媒体查询是只读信号：浏览器根据系统设置自动匹配 @media (prefers-color-scheme: dark) 或 light，你无法用 CSS 触发它变化。用户点“切深色”按钮时，系统偏好可能仍是 light，此时 CSS 媒体查询根本不会生效。

• 只靠 CSS 写 @media (prefers-color-scheme: dark) { ... }，只能响应系统级切换，刷新后还原
• 用户手动切换后页面闪一下（先按系统色渲染，再 JS 注入样式），说明没提前控制变量或 class
• 把 prefers-color-scheme 嵌套在 JS 动态插入的 style 标签里？insertRule 不支持该媒体查询，会静默失败

正确做法：用 JS 控制 :root 变量 + CSS 变量兜底

核心是让 JS 改变根变量值，CSS 全局用 var(--color-bg) 引用，避免 class 切换引发重排或样式泄漏。

• 初始化时优先读 localStorage.getItem('themeMode')， fallback 到 window.matchMedia('(prefers-color-scheme: dark)').matches
• 切换时同时执行：document.documentElement.style.setProperty('--color-bg', '#121212') 和 localStorage.setItem('themeMode', 'dark')
• CSS 中不要只写 @media (prefers-color-scheme: dark)，而是把所有主题变量都定义在 :root，并用 JS 覆盖——这样即使媒体查询不生效（如旧 Safari），变量仍有效
• 注意变量作用域：document.body.style.setProperty 不会影响 var() 查找，必须用 document.documentElement.style 或 :root 上的样式规则

如何避免深色模式下边框/聚焦 outline 刺眼

深色背景上直接用 #000 边框或 outline: 2px solid #fff 会导致视觉跳脱，尤其 focus 状态。

• 别简单反色：浅色下的 #ccc 对应深色不是 #333，而是 #444 或带轻微灰度的 #3a3a3a
• 聚焦 outline 推荐用 outline: 2px solid var(--focus-ring)，并在 JS 切换主题时一并设 --focus-ring: #6200ee（符合 WCAG 对比度）
• border-color 建议用 HSL 表达：比如 --border: hsl(210, 8%, 75%) → 深色下改为 hsl(210, 12%, 25%)，比硬写十六进制更易维护明度梯度

用户手动切换时 localStorage 的坑

Safari 私密模式默认禁用 localStorage，直接调用会抛 QuotaExceededError，导致切换失效且无提示。

• 必须包 try/catch：try { localStorage.setItem(...) } catch { sessionStorage.setItem(...) }
• 不要存布尔值如 true，存字符串 'dark' / 'light' / 'auto'，方便后续扩展护眼模式
• 监听系统变化时，仅当 themeMode === 'auto' 才执行 JS 变量更新，否则用户显式选择应始终优先
• 服务端渲染（SSR）场景下，首次 HTML 必须含正确 style 内联变量，否则首屏仍是系统色，造成明显闪动

最易被忽略的一点：CSS 变量的初始值必须有意义。如果 :root { --color-bg: ; } 留空，后续 JS 设置前所有 var(--color-bg) 都退化为 inherit 或 transparent，页面直接不可用——哪怕只有一行，也要写默认值。

今天关于《一键切换深色模式，CSS教程详解》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！