classList.toggle('dark', boolean) 是暗黑模式切换的关键，boolean 参数实现强制设为开/关，避免状态不同步；需优先读 localStorage，其次 fallback 到 prefers-color-scheme。
classList.toggle() 的布尔参数才是暗黑模式切换的关键
直接调用 element.classList.toggle('dark') 只是“有就删、没就加”，无法控制状态；暗黑模式需要的是「强制设为开」或「强制设为关」，必须用第二个参数——布尔值。这个参数决定 toggle 的行为是“条件性切换”还是“强制设置”。
常见错误是写成 toggle('dark', isDark) 却没同步更新 isDark 状态变量，导致 UI 和状态不同步。正确做法是：先读取当前是否含 dark 类，再决定要不要加/删，或者更稳妥地——用 toggle 的布尔参数配合状态变量一起更新。
- ✅ 正确：把
document.documentElement作为目标元素，它影响全局样式作用域 - ✅ 推荐在切换后同步写入
localStorage，避免刷新丢失状态 - ❌ 错误：对
body或某个局部容器调用toggle，但 CSS 选择器没适配（比如写了.dark .btn却只给按钮加类）
如何用 toggle(true/false) 实现无状态依赖的强制设置
不需要提前查 contains()，直接用布尔参数就能绕过判断逻辑。例如：document.documentElement.classList.toggle('dark', shouldEnableDark) —— 当 shouldEnableDark 为 true，确保有 dark 类；为 false，确保没有。
这比手动写 if (shouldEnableDark) add() else remove() 更简洁，也避免竞态（比如多次快速点击触发多次 add/remove）。
- 参数为
true：类名存在则不变，不存在则添加 - 参数为
false：类名存在则删除，不存在则不变 - 注意：该参数是「目标状态」，不是「切换动作」
搭配 prefers-color-scheme 自动初始化时别覆盖用户选择
如果页面加载时读 window.matchMedia('(prefers-color-scheme: dark)').matches 来自动启用暗黑模式，要先检查 localStorage 是否已有用户手动设置，有则优先使用，否则才用系统偏好。
否则会出现：用户刚点关闭暗黑模式，刷新页面又变暗——因为代码每次都无条件按系统偏好设置 toggle('dark', systemIsDark)，把用户选择覆盖了。
- ✅ 初始化逻辑顺序：读 localStorage → 存在则用；不存在则读 prefers-color-scheme → 再调用
toggle('dark', finalState) - ✅ 切换按钮点击事件里，只改 localStorage + 调用
toggle，不重新读系统偏好 - ⚠️ 注意：
matchMedia是动态可监听的，但暗黑模式手动切换后一般不响应系统变化，这是预期行为
为什么不用 classList.replace() 或 className = ...？
replace() 需要明确知道旧类名，而暗黑模式往往只关心 dark 这一个开关类，其他类（如 theme-blue、font-large）不应被干扰；直接赋值 className 会清空所有已有类，破坏结构完整性。
toggle('dark', bool) 是最小干预操作：只动一个类，不影响其他任何 class，语义清晰，性能也好（DOM 更新粒度最小）。
- ❌
el.className = 'dark'：丢了所有原有类，比如container js-loaded - ❌
replace('light', 'dark')：前提是当前一定有light类，但初始状态可能既没light也没dark - ✅
toggle不依赖前置状态，适合开关型控制
实际最简可用片段长这样：
const root = document.documentElement;
const saved = localStorage.getItem('dark-mode');
const enabled = saved ? JSON.parse(saved) : window.matchMedia('(prefers-color-scheme: dark)').matches;
root.classList.toggle('dark', enabled);
document.getElementById('dark-toggle').addEventListener('click', () => {
const next = !root.classList.contains('dark');
root.classList.toggle('dark', next);
localStorage.setItem('dark-mode', JSON.stringify(next));
});
暗黑模式真正难的不是切换动作本身，而是状态来源的优先级管理：用户手动操作 > 本地存储记忆 > 系统偏好。只要这层逻辑没理清，toggle 再好用也会表现反直觉。
