网页深色模式切换实现方法

直接用 data-theme 控制，配合 CSS 变量 + localStorage 持久化，不刷新、不闪屏、不依赖第三方库——这是实现深色模式切换最轻量、最可靠的方案之一。下面把关键环节拆开来看，每一步都藏着容易踩坑的细节。

初始化脚本：必须塞在 里尽早执行

想要不闪屏，关键的一步是把初始化逻辑塞进 里的内联 ，而且要放在 之前。如果等 DOM 渲染完才设主题，白屏一闪就躲不掉了：

• 必须放在 标签之前，否则 CSS 已加载，主题还没生效
• 千万别用 DOMContentLoaded 事件——等它触发时页面已经开始渲染，闪屏就不可逆转了
• document.documentElement 是 元素，比操作 body 更靠谱，因为 meta 标签和 color-scheme 响应都依赖它

style.css 里的颜色定义：所有变量都得走一遍

所有可变色属性都必须从 var(--xxx) 取值，否则切了 data-theme 也没用。别写成 .dark { ... } 然后给 body 加 class，这样没法控制 ：

:root {  
  --bg: #fff;  
  --text: #111;  
  --border: #ddd;  
}  
[data-theme="dark"] :root {  
  --bg: #121212;  
  --text: #eee;  
  --border: #333;  
}  
body {  
  background-color: var(--bg);  
  color: var(--text);  
  border-color: var(--border);  
  transition: background-color 0.3s, color 0.3s, border-color 0.3s;  
}

• [data-theme="dark"] :root 的写法比 @media (prefers-color-scheme: dark) 更主动，能直接覆盖系统偏好，不受系统设置影响
• 所有用到的颜色—文字、背景、边框、阴影、svg fill—都得走变量，漏一个就会出现“局部亮着”的尴尬
• 过渡动画加上 transition，切换才流畅

切换按钮：用 绑定 JS，兼顾无障碍

别用 checkbox + label 的纯 CSS 方案，它没法存 localStorage，也不能响应系统变化。用 加上 aria-pressed 是最稳妥的做法：

const btn = document.getElementById('theme-toggle');  
const html = document.documentElement;  

function setTheme(theme) {  
  html.dataset.theme = theme;  
  localStorage.setItem('theme', theme);  
  btn.setAttribute('aria-pressed', theme === 'dark');  
}  

btn.addEventListener('click', () => {  
  const current = html.dataset.theme;  
  setTheme(current === 'dark'  'light' : 'dark');  
});  

// 初始化时同步 aria 状态  
btn.setAttribute('aria-pressed', html.dataset.theme === 'dark');

• aria-pressed 是给读屏器看的，必须手动同步，不能靠 CSS 伪类
• 别监听 matchMedia().addEventListener 自动切主题——用户点过“开深色”，系统一变暗又顶回去，体验断裂
• 按钮文案建议用图标 + sr-only 文字（如 切换深色模式），兼顾可访问性

meta[name="color-scheme"] 必须手动同步

只改页面样式，不更新这个 meta，Chrome 地址栏、输入框、滚动条等浏览器 UI 还是按默认主题渲染，造成视觉割裂：

function updateColorSchemeMeta() {  
  const theme = document.documentElement.dataset.theme;  
  const meta = document.querySelector('meta[name="color-scheme"]');  
  if (!meta) {  
    const newMeta = document.createElement('meta');  
    newMeta.name = 'color-scheme';  
    document.head.appendChild(newMeta);  
  }  
  document.querySelector('meta[name="color-scheme"]').content =   
    theme === 'dark'  'dark only' : 'light only';  
}

• 必须在每次 setTheme() 后调用它，包括初始化时
• dark only 比 dark 更严格，防止浏览器 fallback 到 light
• 这个 meta 不会自动随 data-theme 变，必须 JS 显式控制

最容易被忽略的环节：所有颜色都要走 CSS 变量，meta[name="color-scheme"] 要手动同步，初始化脚本必须塞在 里尽早执行——少一个环节，用户就能直接感受到闪屏、视觉割裂或功能失效。归根结底，这套方案的核心在于“时机”和“全面”：脚本时机要对，变量覆盖要全，浏览器 UI 状态要同步到位。