document.documentelement.style.setproperty用于动态修改根元素css变量，需带--前缀、字符串值及单位，确保css中已声明且作用域匹配，配合var()使用才能生效。
document.documentElement.style.setProperty 怎么用
这是修改 CSS 变量最直接、最常用的方式。CSS 变量（Custom Properties）必须定义在 :root 或某个元素上，而 document.documentElement 指向的就是 元素，等价于 :root，所以改它就等于全局生效。
常见错误现象：document.body.style.setProperty 不起作用 —— 因为变量没定义在 上，只在 :root 里声明的变量，body 无法直接覆盖；或者漏写双横线前缀 --，比如写成 setProperty('primary-color', '#333') 而不是 setProperty('--primary-color', '#333')。
实操建议：
- 确保 CSS 中已声明，例如：
:root { --primary-color: #007bff; } - JS 中调用时严格带
--前缀：document.documentElement.style.setProperty('--primary-color', '#28a745'); - 若需批量更新，可封装成对象传入：
Object.entries(theme).forEach(([k, v]) => document.documentElement.style.setProperty(k, v));
为什么 setProperty 后样式没变
不是 JS 没执行，而是 CSS 变量的“下游”没接住。CSS 变量本身只是存储值，真正起作用的是用 var(--primary-color) 的地方。
典型场景：
- 按钮背景色用了
background-color: var(--primary-color);，但你只改了变量值，没触发重绘？其实会自动重绘，除非该属性被更具体的规则覆盖（比如内联 style 写死style="background-color: red"） - 变量作用域错位：在
.card { --text-color: #666; }里定义，却试图用document.documentElement.style.setProperty修改 —— 不生效，因为 :root 下没有这个变量 - 拼写不一致：CSS 里是
--bg-dark，JS 里写成--bg-dark-mode，大小写或连字符差一个都不匹配
如何让 JS 修改变量后触发动画过渡
CSS 变量本身不支持 transition，但你可以把变量用在支持过渡的属性上，再靠属性变化带动动画。例如，颜色、opacity、transform 都可以，但 font-size: var(--size) 就不能直接过渡 —— 浏览器不认为变量值变化是“可过渡事件”。
实操建议：
- 把变量绑定到支持 transition 的属性上：
color: var(--text-color); transition: color 0.3s ease; - 避免用变量控制 display / z-index / content 等不可过渡属性
- 如果必须过渡尺寸类变化（如 width / height），可用
transform: scale(var(--scale));+transition: transform 0.3s;替代 - 注意性能：频繁 setProperty 触发 layout（如改 font-size 影响行高）可能卡顿，优先选 compositor-friendly 属性（transform / opacity）
切换主题时怎么持久化 CSS 变量值
页面刷新后变量恢复默认，是因为 setProperty 只是运行时修改，不写入 CSS 文件或 DOM。要持久化，得靠客户端存储配合初始化逻辑。
关键点：
- 存到
localStorage：localStorage.setItem('theme', JSON.stringify({ '--primary-color': '#dc3545', '--bg': '#f8f9fa' })); - 页面加载时读取并还原：
const saved = JSON.parse(localStorage.getItem('theme') || '{}'); Object.entries(saved).forEach(([k, v]) => document.documentElement.style.setProperty(k, v)); - 不要在
<script></script>标签里直接写 setProperty —— 如果脚本放在且未 defer，document.documentElement可能还没 ready；建议用DOMContentLoaded或放在前 - 深色模式检测可 fallback 到
window.matchMedia('(prefers-color-scheme: dark)')，但用户手动切换后必须以 localStorage 为准
最容易被忽略的一点：CSS 变量名区分大小写，且连字符位置必须完全一致；一次拼错，整个链路静默失败，既不报错也不生效 —— 调试时优先检查控制台输出 getComputedStyle(document.documentElement).getPropertyValue('--your-var') 的返回值是否符合预期。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
