Web Components adoptedStyleSheets 怎么共享组件样式：构造顺序、跨文档边界与回退方案

组件库拆成多个 Web Component 后，样式重复往往比 JavaScript 更早变成维护负担：每个 ShadowRoot 都塞一份相同的 CSS，主题更新要改很多处，初始化顺序又容易制造一帧未样式化内容。adoptedStyleSheets 的价值，是把同一个由 CSSStyleSheet() 构造出来的样式表复用到多个组件，同时保留 Shadow DOM 的边界。

先把共享样式表放到正确的初始化位置

最容易踩的坑不是 API 拼写，而是“先挂载组件，后创建样式表”。组件的 connectedCallback() 可能在样式准备完成前运行，页面于是先显示无样式内容，随后才突然改变。更稳妥的顺序是：模块加载时构造样式表，完成 replaceSync()，然后组件创建 ShadowRoot 并采用它。

const componentSheet = new CSSStyleSheet();
componentSheet.replaceSync(`
  :host { display: block; color: #19324d; }
  .panel { padding: 16px; border: 1px solid #c7d7e8; }
`);

class NoticePanel extends HTMLElement {
  constructor() {
    super();
    const root = this.attachShadow({ mode: "open" });
    root.innerHTML = '
';
    root.adoptedStyleSheets = [componentSheet];
  }
}
customElements.define("notice-panel", NoticePanel);

这里的关键检查点有三个：样式表由构造函数产生，规则通过 replaceSync() 写入，ShadowRoot 采用的是同一个对象而不是每次重新创建的副本。:host 只影响组件宿主，.panel 仍然被 Shadow DOM 隔离，页面外部的同名选择器不会直接改写它。

多个组件共享时，更新对象比重建数组更可靠

同一份构造样式表可以放进多个 ShadowRoot 的采用列表。真正需要动态主题时，优先更新这份样式表，而不是遍历组件重新插入一堆 标签。已经采用它的根会看到规则变化，组件之间也不会因为更新顺序不同而短暂分叉。

const themeSheet = new CSSStyleSheet();
themeSheet.replaceSync(`:host { --accent: #2b6cb0; }`);

function applyTheme(color) {
  themeSheet.replaceSync(`:host { --accent: ${color}; }`);
}

// 每个组件初始化时都采用同一对象
root.adoptedStyleSheets = [componentSheet, themeSheet];

如果组件原本还有自己的采用表，不要无意中覆盖它。赋值是整体替换，下面这种写法会把原来的共享表清掉：

root.adoptedStyleSheets = [themeSheet]; // 可能丢掉 componentSheet

更明确的做法是让组件在构造时一次性决定顺序，或在确实需要追加时基于现有数组生成新数组。不要依赖数组的原地 push() 行为来表达初始化契约，组件库升级时很难看出是谁改了顺序。

跨 iframe 时不要把样式表当成全局单例

adoptedStyleSheets 的“共享”有上下文边界。同一文档内的 Document 与 ShadowRoot 可以复用由该文档构造的样式表；如果组件运行在另一个 iframe，直接把父文档的 CSSStyleSheet 塞过去，通常会得到 NotAllowedError 或无法采用的结果。这个边界应该在组件初始化阶段就检测，而不是等用户看到空白组件。

function installStyles(root, cssText, sharedSheet) {
  if (sharedSheet && "adoptedStyleSheets" in root) {
    try {
      root.adoptedStyleSheets = [sharedSheet];
      return "adopted";
    } catch (error) {
      // 跨文档或上下文不匹配时进入回退
    }
  }

  const style = document.createElement("style");
  style.textContent = cssText;
  root.append(style);
  return "style-fallback";
}

回退分支不能继续引用父文档的 sheet。它应该在当前组件上下文里创建普通 style 元素，并把同一份 CSS 文本写进去。这样虽然牺牲了共享对象带来的更新便利，但组件仍能显示，故障也集中在能力探测上。

兼容回退要覆盖动态更新和首屏显示

只判断 "adoptedStyleSheets" in root 还不够：属性存在不代表当前 sheet 能被采用，跨文档场景仍可能抛错。因此初始化要包住实际赋值，并记录最终采用模式。若回退模式需要主题切换，就保留 style 元素引用，后续更新它的 textContent；不要只更新已经失效的共享 sheet。

const cssFor = (accent) => `
  :host { --accent: ${accent}; }
  .panel { border-color: var(--accent); }
`;

function createStyleController(root, sharedSheet) {
  const cssText = cssFor("#2b6cb0");
  try {
    if ("adoptedStyleSheets" in root && sharedSheet) {
      root.adoptedStyleSheets = [sharedSheet];
      return { mode: "adopted", update: (next) => sharedSheet.replaceSync(cssFor(next)) };
    }
  } catch (_) {}

  const style = document.createElement("style");
  style.textContent = cssText;
  root.append(style);
  return { mode: "style", update: (next) => { style.textContent = cssFor(next); } };
}

验收时至少做四次检查：同一文档放两个组件，看主题变化是否同时生效；把组件放进 iframe，看是否进入回退；禁用相关能力或使用不支持的浏览器，看首屏是否仍有样式；最后检查组件销毁后没有遗留全局监听器。样式共享解决的是复用问题，不会自动解决 CSS 规则本身的优先级冲突。

把这套方案落地前，先核对三项取舍

• 组件都在同一 Document：适合使用一份共享 CSSStyleSheet，主题变更路径最短。
• 组件会跨 iframe：按文档创建各自的 sheet，或直接使用 style 回退，不要传递父文档对象。
• 需要兼容较老环境：把 CSS 文本作为源数据保留，采用失败时仍能创建 style 元素；不要把回退写成只返回空节点。

常见问题

adoptedStyleSheets 会让 Shadow DOM 失去隔离吗？

不会。样式表被采用到哪些 Document 或 ShadowRoot，仍由采用列表决定；普通页面选择器也不会因为共享 sheet 就直接穿透 Shadow DOM。

为什么 replaceSync() 后组件没有变化？

先确认组件采用的是同一个 CSSStyleSheet 对象，而不是复制 CSS 文本后重新构造的另一个对象；再确认更新发生在当前文档的上下文里，并检查是否实际走了 style 回退分支。

回退一定要使用 style 标签吗？

不一定，但 style 是最小且容易验证的方案。若项目有成熟的 CSS 模块加载机制，也可以在当前 ShadowRoot 内按同样的 CSS 源文本注入，只要确保跨文档不会复用不属于当前上下文的构造样式表。

总结

adoptedStyleSheets 适合解决同一文档内多个 Web Component 的样式复用：先构造、再填充、后采用，动态主题更新共享对象，跨文档或能力不完整时切换到当前 ShadowRoot 的 style。把“对象归属”和“失败回退”写进初始化流程，组件库才不会只在理想浏览器里工作。