直接用 setProperty 修改 :root 变量需协同 dataset、class 和批量赋值，确保首屏不闪、系统切换响应、样式全覆盖且单位函数正确传入。
直接用 document.documentElement.style.setProperty() 修改 :root 上的 CSS 变量是最可行的路径，但只改变量值远远不够——页面会闪、部分样式不动、系统切换不响应、刷新后变回默认，这些问题都源于漏掉了关键协同环节。
为什么单纯 setProperty 会导致页面闪动或样式错乱
浏览器渲染有明确时序：JS 修改变量 → 触发样式计算 → 布局 → 绘制。如果在修改变量后立刻操作 DOM 或读取 getComputedStyle，很可能拿到旧值；更常见的是，部分样式没用 var(--xxx) 接管，比如写死的 border: 1px solid #ccc 或 background: #fff，切换主题时这些地方完全不变。
- 所有涉及颜色、背景、边框、阴影、文字、SVG 填充、滚动条（
scrollbar-color）的地方，必须统一使用var(--theme-bg, #fff)形式，并带 fallback - 避免在循环中高频调用
setProperty；批量更新时先收集键值对，再统一赋值（现代浏览器对此优化较好，但超过 20 个变量时仍建议合并） - 不要用
style.cssText = '...'全量重写，会清空其他动态设置的样式
如何让 localStorage 存的主题真正生效且首屏不闪
用户点按钮切暗色，刷新后又变亮——说明初始化逻辑没在 HTML 解析完成前就位。SSR 或普通页面都必须确保：HTML 根标签上已有 data-theme="dark" 或 class="theme-dark"，否则浏览器先按默认主题渲染一帧，JS 再补上变量，必然闪。
- 服务端渲染时，需在模板中根据请求头或 cookie 预设
<html data-theme="dark"> - 客户端渲染时，JS 初始化代码必须放在
<head>内的<script>中（非 defer/async），或用document.write注入（慎用），确保早于任何样式表执行 -
localStorage.getItem('ui-theme')读取后，立即同步三处：document.documentElement.dataset.theme、document.documentElement.className、逐个调用setProperty - 不要只存字符串
"dark"就完事——得把整套变量值对象序列化存储，例如{"--bg-color": "#121212", "--text-color": "#e0e0e0"}，避免 CSS 里堆砌[data-theme="dark"] { ... }块
怎么正确监听并响应系统偏好变化（prefers-color-scheme）
CSS 变量本身不会“感知”系统主题变化，@media (prefers-color-scheme: dark) 只在初始匹配时生效，后续系统切换（如 macOS 控制中心实时切）它不会重新触发。必须靠 JS 主动监听。
使用 JSON Schema 验证 JSON 数据，从示例 JSON 生成 schema，并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。
立即学习“前端免费学习笔记（深入）”；
- 用
window.matchMedia('(prefers-color-scheme: dark)')获取当前状态，.matches返回布尔值 - 必须绑定
.addEventListener('change', handler)，不能只查一次 - 监听回调里要判断：如果用户没手动选过主题（即
localStorage为空），才按系统偏好自动同步；否则尊重用户选择，不覆盖 - 注意兼容性：Safari 14+、Chrome 87+、Firefox 97+ 支持该 API；旧版需降级为 UA 检测（不推荐）或忽略
为什么必须同时用 class + dataset + setProperty 三者协同
只靠 setProperty 无法解决权重和条件渲染问题。比如你想让暗色模式下图片自动加 filter: brightness(0.9)，但这个规则没法用变量表达——CSS 变量只能控制值，不能控制“是否应用某条样式”。这时候就得靠 class 或 dataset 来驱动选择器。
-
document.documentElement.classList.toggle('theme-dark')是最稳妥的 class 控制方式；切换前先remove所有 theme 相关 class，再add新的，防止残留 -
dataset.theme用于 CSS 层叠控制，例如[data-theme="dark"] img { filter: brightness(0.9); }，比 class 语义更清晰 -
setProperty负责动态值更新，比如--accent-hue: 210这种需要 JS 计算的变量 - 三者必须同步更新，顺序建议：先改
dataset和class，再批量setProperty，避免中间状态被样式引擎捕获
最容易被忽略的是：变量值里的单位和函数必须原样传入 setProperty。传 16 不等于 16px，传 rgb(255,0,0) 不能拆成三个数字，浏览器不会自动补全或解析——这导致大量“变量设了但没生效”的假象。
