document.documentElement.style.setProperty对Shadow DOM组件无效，因其变量作用域不穿透Shadow Root，需在shadowRoot.documentElement或host上单独设置，且CSS中必须用var()引用并确保作用域匹配。
document.documentElement.style.setProperty 为什么对组件无效
因为组件（尤其是封装在 Shadow DOM 中的编辑器、卡片、表单）默认读不到 document.documentElement 上的变量——:root 的作用域不自动穿透 Shadow Root。你调用了 document.documentElement.style.setProperty('--theme-color', '#4f46e5')，但组件内部样式写的是 color: var(--theme-color)，而它查的是自己 Shadow Root 内部的 :root 或宿主元素，根本没连上全局变量链。
常见现象：主题切换后，页面其他区域变色了，但编辑器/自定义按钮/富文本框颜色纹丝不动。
- Shadow DOM 组件必须显式把变量“透传”进去，不能靠继承
- React/Vue 封装的组件若用
style属性硬编码 CSS 变量（如style="--bg:#fff"），JS 改setProperty不会覆盖它——那是静态内联值，不是变量绑定 - Lit、Stencil 等框架的
host元素若没声明--theme-color，改了全局变量也白搭
怎么给 Shadow DOM 组件动态设 CSS 变量
核心是：找到组件的 Shadow Root，并在其根节点（通常是 shadowRoot.documentElement 或 shadowRoot.host）上调用 style.setProperty。
实操步骤：
立即学习“前端免费学习笔记（深入）”；
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 先获取组件实例：
const editor = document.querySelector('my-editor'); - 确认它有 Shadow Root：
if (editor.shadowRoot) { ... } - 往 Shadow Root 的根节点设变量：
editor.shadowRoot.documentElement.style.setProperty('--font-size', '15px'); - 如果组件用
open模式但变量定义在:host上，也可直接操作宿主：editor.style.setProperty('--line-height', '1.5');（前提是 CSS 规则里写了:host { line-height: var(--line-height); }）
注意：shadowRoot.documentElement 在部分旧版浏览器或某些框架封装下可能为 null，此时应 fallback 到 shadowRoot.host 并确保该元素已声明对应变量。
组件内 CSS 规则没接住变量？检查这三处
即使 JS 成功设置了变量，样式也不变，大概率是 CSS 层“没接住”。关键不是 JS 没跑，而是下游断连。
-
漏写
var()：CSS 里只写了--text-color: #374151;，但没在属性中调用，比如color: var(--text-color);—— 这个变量就只是个注释 -
作用域错位：变量定义在
.editor-content { --text-color: #374151; }，却试图用editor.style.setProperty('--text-color', '#1f2937')修改——这个setProperty是往<div class="editor-content">的内联样式里塞，但变量定义本身就在该元素上，所以能生效；但如果定义在:root，而你改的是子元素，就完全不生效 -
单位缺失或类型错误：设
editor.style.setProperty('--padding', 16)（数字）或'16'（无单位）→ 浏览器静默忽略；必须是'16px'或'1rem'
多个同名组件如何独立控制变量
全局变量（:root）只能统一控制，没法让 #editor-1 和 #editor-2 各用一套字号或背景色。要实现实例级控制，得放弃 document.documentElement，改用元素本地变量。
- 给每个编辑器加唯一 class 或 data 属性：
<div id="editor-1" class="editor-instance"> - CSS 中用选择器限定作用域：
.editor-instance { --editor-font-size: 14px; font-size: var(--editor-font-size); } - JS 分别操作：
document.getElementById('editor-1').style.setProperty('--editor-font-size', '16px'); - 避免用
id直接写死，推荐用querySelectorAll('.editor-instance')+ 循环，方便后续扩展
复杂点在于：一旦组件用了 Shadow DOM，你就不能再靠 class 选择器驱动变量——必须进 Shadow Root 内部设，且每个实例的 Shadow Root 都得单独处理。这点容易被忽略，尤其当组件批量渲染时，漏掉一个实例的变量设置，它的样式就永远卡在默认值上。
