必须将所有主题变量写在:root中，因其是唯一能确保全局继承、全元素（含伪元素、svg、contenteditable）可访问的根作用域；其他位置声明会导致作用域受限、setproperty无效或页面失色。
直接在 :root 声明变量 + document.documentElement.style.setProperty() 修改，就能实现真正的动态引入；其他方式（如只在组件里定义、用 cssText 覆盖、或靠 class 切换局部变量）要么失效，要么不可控。
为什么必须把所有变量写在 :root 里
因为 CSS 变量靠继承传播，:root 是整个文档的根节点。只有挂在这里，var(--bg-color) 才能在任意层级（包括 ::before、svg、contenteditable 区域）正确取值。常见错误包括：
- 变量写在
.theme-dark选择器里 → 切换 class 后子元素读不到新值，继承链断了 - 变量只定义在
body或组件级选择器（如.card）→ 兄弟组件无法复用，setProperty()完全无效 - 没预先声明就调
setProperty()→var(--bg-color)fallback 为transparent或继承色，页面瞬间“失色”
setProperty() 怎么用才不静默失败
这个 API 看似简单，但错一个字符就完全没反应，且浏览器不报错。关键点有：
- 目标元素必须是
document.documentElement，不是document.body或随便一个div - 变量名必须带
--前缀、大小写严格匹配：'--theme-bg'✅，'theme-bg'❌ - 值必须是合法 CSS 字符串：
'#121212'✅，#121212（无引号）❌，'16'❌（缺单位，应写'16px'） - 如果值要引用另一个变量，得写成
'var(--primary-color)'，不能只传'--primary-color'
切换主题时怎么避免闪屏和抖动
用户点击后页面白一下或布局跳动，通常不是 JS 写错了，而是初始化节奏没对齐：
- 必须在
的最开头就执行document.documentElement.dataset.theme = localStorage.getItem('ui-theme') || 'light'，否则首屏渲染完才切主题，必然 FOUC - 所有尺寸变量（
--spacing-sm、--border-radius、--font-size）必须在初始 CSS 中定义，不能只在.theme-dark里补——否则切换时触发 layout 抖动 -
contenteditable区域默认不继承color和background-color，需显式声明：.editor-content { color: var(--editor-text); background-color: var(--editor-bg); } - 切换后立刻调
getComputedStyle会强制同步布局 → 改用requestAnimationFrame延迟读取
Bootstrap 5 主题动态改色为什么部分组件没变
改了 --bs-primary，但 .alert-primary 背景没变、box-shadow 还是蓝色，大概率是漏设了链式变量：
- Bootstrap 5 大量使用
rgba(var(--bs-primary-rgb), .5)这类写法，--bs-primary-rgb必须同步更新，否则派生样式 fallback 到默认值 - 查源码确认依赖关系：打开 Bootstrap 的
_variables.scss，搜$primary和$primary-rgb，看哪些变量被它引用 - RGB 值别手算：比如
#6f42c1对应111, 66, 193，不是四舍五入后的111, 66, 192 - 批量设置推荐封装函数：
setBSVars({ '--bs-primary': '#6f42c1', '--bs-primary-rgb': '111, 66, 193' })
最容易被忽略的是 fallback 和作用域——变量写了但没 fallback，或者改了 :root 却忘了组件自己内联覆盖了同名变量，结果一切看起来都“不动”。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
