CSSStyleSheet.replaceSync怎样批量更新构造样式

如果组件有一整套规则需要同时交给页面和多个 Shadow DOM 使用，CSSStyleSheet.replaceSync() 适合做“整份规则文本的同步替换”：先用 CSSStyleSheet() 创建可构造样式表，再把准备好的 CSS 文本一次放进去，最后通过 adoptedStyleSheets 共享。

官方地址：https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet/replaceSync

最重要的理解是：replaceSync() 替换的是样式表里的整组规则，不是向普通 样式表追加内容，也不是外部 CSS 文件加载器。

先把三个对象的职责分开

CSSStyleSheet() 创建一个可构造样式表，replaceSync(text) 同步解析传入的 CSS 文本并替换当前规则集合，adoptedStyleSheets 决定这份样式表被哪个 document 或 ShadowRoot 使用。把这三步拆开，后面排查“样式没有生效”会简单很多。

// 创建一份可以被多个使用方共享的构造样式表
const sharedSheet = new CSSStyleSheet();

// 一次放入已经准备好的 CSS 规则文本
sharedSheet.replaceSync(`
  :host { display: block; }
  .card { padding: 16px; border-radius: 12px; }
`);

// 让当前页面采用这份样式表
document.adoptedStyleSheets = [
  ...document.adoptedStyleSheets,
  sharedSheet,
];

调用成功后，replaceSync() 不返回新的样式表对象；它修改的是当前的 sharedSheet。因此不要把返回值误当成后续要传递的 sheet。

replaceSync 怎样完成一次批量更新

它的“批量”体现在输入是一段完整 CSS 文本。与多次调用 insertRule() 相比，调用方可以先在字符串、模板或构建产物中准备好一组相关规则，再一次性替换旧内容。这个模型特别适合主题切换、组件版本切换和按模块生成样式的场景。

// 用完整文本表达当前主题，避免只更新一半规则
function applyTheme(sheet, theme) {
  const cssText = `
    :host { color-scheme: ${theme.scheme}; }
    .card { background: ${theme.surface}; color: ${theme.text}; }
    .card a { color: ${theme.link}; }
  `;

  // replaceSync 会整体替换旧规则，调用方无需逐条删除旧规则
  sheet.replaceSync(cssText);
}

const themeSheet = new CSSStyleSheet();
applyTheme(themeSheet, {
  scheme: 'light',
  surface: '#ffffff',
  text: '#1f2937',
  link: '#2563eb',
});

再次调用 applyTheme() 时，旧的规则集合会被新的文本替换。为了避免主题状态不完整，传入的字符串应该包含这次主题需要的完整规则，而不是只拼接本次变化的一个选择器。

共享给 ShadowRoot 时要满足同文档条件

构造样式表可以共享给当前 document，也可以共享给同一 document 下的 ShadowRoot。组件初始化时，把同一份 sheet 放到各自的 adoptedStyleSheets，后续对 sheet 的更新会反映到所有采用它的对象上。

// 让组件复用页面已经创建的同一份样式表
function installSharedStyles(host, sheet) {
  const shadow = host.attachShadow({ mode: 'open' });

  // 当前 ShadowRoot 与 sheet 必须属于同一个 Document
  shadow.adoptedStyleSheets = [sheet];
  return shadow;
}

const first = installSharedStyles(document.querySelector('#first'), themeSheet);
const second = installSharedStyles(document.querySelector('#second'), themeSheet);

// 修改同一对象，两个 ShadowRoot 都会看到新的规则
themeSheet.replaceSync(':host { display: block; } .card { border: 1px solid #cbd5e1; }');

这里有两个容易混淆的边界。第一，不能把在另一个 document 中构造的 sheet 直接采用到当前 document 或它的 ShadowRoot。第二，ShadowRoot 采用的是 sheet 对象，而不是重新复制一份 CSS 文本；如果希望两个组件独立升级，就应该分别创建样式表。

四种情况不要混成一个 API

特别是 @import：它代表外部资源关系，不能当作 replaceSync() 的同步规则输入。需要独立加载的 CSS，就放在构造样式表之外；需要共享的规则，则在进入 replaceSync() 之前通过构建流程或文本拼接准备好。

// 异步场景使用 replace，但仍然传入已经准备好的 CSS 文本
async function applyAsyncTheme(sheet, cssText) {
  try {
    // replace 返回 Promise，调用方可以等待规则替换完成
    await sheet.replace(cssText);
  } catch (error) {
    // 保留原始错误，便于区分文本问题和资源加载问题
    throw new Error(`异步样式替换失败: ${error.message}`);
  }
}

迁移时按这个顺序排查

1. 确认对象来自 new CSSStyleSheet()，不要把普通外链样式表当成可构造样式表。
2. 确认 replaceSync() 的参数是完整且可解析的 CSS 文本，并把需要的规则放在同一次替换里。
3. 确认采用方与样式表属于同一个 document；跨 iframe 或跨 document 的复用要改成独立创建或普通资源。
4. 确认组件是否真的需要共享对象；如果组件要独立发布，创建独立 sheet 比共享后再覆盖更安全。
5. 如果文本来自异步请求或动态导入，改用 replace() 并等待 Promise，不要在同步路径里假设资源已经到位。

这样迁移的重点就从“把旧 CSS API 换成新 API”变成了四个可检查的决策：规则是否完整、对象是否可构造、使用方是否同文档、共享是否符合生命周期。replaceSync() 适合明确的整套规则替换，不适合承担外部资源管理。

相关问题

replaceSync() 会返回新的 CSSStyleSheet 吗？ 不会。它同步修改当前构造样式表，返回值为 undefined；后续继续使用原来的 sheet 对象。

为什么不能把跨 iframe 的 sheet 直接放进 adoptedStyleSheets？ 构造样式表必须来自采用方所在的同一 document 上下文；跨 document 时应在目标 document 中重新创建。

replaceSync() 和 insertRule() 怎么选？ 需要整套规则切换时用 replaceSync()；只在已经构造的规则集合中插入一条、且希望保留其他规则时，再考虑 insertRule()。

CSS 文本需要异步获取时还能用 replaceSync() 吗？ 可以在异步获取完成后再同步替换，但如果整个调用本身要表达异步流程，通常使用返回 Promise 的 replace() 更清楚。