css变量必须在:root中声明才能全局生效，正确做法是顶层统一定义并加语义前缀；js应通过切换class而非setproperty批量换肤，并用localstorage持久化状态，同时兼顾prefers-color-scheme兜底。
如何用 :root 声明真正全局的 CSS 变量？
CSS 变量（Custom Properties）必须在 :root 里定义，才能被所有元素继承——这不是可选项，是作用域规则决定的。漏写 :root 或错写成 html、body，变量就只在局部生效，换肤会“断层”。
常见错误：把主题色写在某个组件类里，比如 .theme-dark { --bg: #1a1a1a; }，这只会让该类及其子元素读到，其他地方仍用默认值。
正确做法是统一在顶层声明，并预留 fallback：
:root {
--primary-color: #007bff;
--bg-color: #ffffff;
--text-color: #333333;
}
注意：变量名建议带语义前缀（如 --theme- 或 --color-），避免和第三方库冲突；不推荐用 --1、--dark 这类无上下文缩写。
JS 如何安全地切换主题并避免 FOUC？
直接用 document.documentElement.style.setProperty() 能改单个变量，但换肤通常要批量更新。更稳的方式是切换预设的 class，再靠 CSS 层叠覆盖变量值。
例如预先定义两套主题：
:root {
--bg-color: #ffffff;
--text-color: #333333;
}
:root.theme-dark {
--bg-color: #121212;
--text-color: #e0e0e0;
}
JS 切换只需一行：document.documentElement.classList.toggle('theme-dark')。好处是：CSS 引擎能批量重绘，比逐个 setProperty 更快；也避免因 JS 执行时机导致的闪屏（FOUC）。
用于端到端视频本地化流程的轻量编排器，路由至四个专注子技能——/wjs-transcribing-audio、/wjs-translating-subtitles...
容易踩的坑：
- 没加
transition就直接切 class → 颜色突变，体验生硬（可在:root加transition: background-color 0.2s, color 0.2s） - 本地存储读取太晚 → 页面先按默认主题渲染，再闪一下 → 应在
内联 JS 读取localStorage.getItem('theme')并立即设 class
为什么 getComputedStyle 读不到动态设置的变量？
getComputedStyle(el).getPropertyValue('--my-var') 确实能读，但前提是该变量已在当前元素或其继承链上被计算过。如果 JS 刚 setProperty，但浏览器还没触发样式计算（比如还在同一事件循环中），可能返回空字符串或旧值。
安全读取方式：
- 确保读取发生在重排之后（如放在
requestAnimationFrame回调里） - 优先读
:root元素：getComputedStyle(document.documentElement).getPropertyValue('--primary-color') - 别依赖它做关键逻辑判断——换肤状态应以 class 或 localStorage 为准，CSS 变量只是视图层映射
另外，getPropertyValue 返回的是字符串（含空格和单位），比较时记得 .trim()，比如 ' #007bff ' ≠ '#007bff'。
暗色模式自动适配要不要用 @media (prefers-color-scheme)？
要，但不能只靠它。系统级偏好只是起点，用户明确点击“切暗色”后，应以用户选择为最高优先级，覆盖系统设置。
推荐策略：
- 初始化时：先查
localStorage，有值就用；没有则查matchMedia('(prefers-color-scheme: dark)')，再 fallback 到 light - CSS 中保留媒体查询兜底（防 JS 失败）：
@media (prefers-color-scheme: dark) { :root:not(.theme-light) { --bg-color: #121212; } } - JS 切换主题后，必须同步写入
localStorage，否则刷新就丢失
一个细节：Safari 对 prefers-color-scheme 的监听有延迟，matchMedia().addEventListener 不一定实时触发，所以不要把它当唯一信源。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
