Document：adoptedStyleSheets 属性

基线 2023

新增功能

自 2023年3月起，此功能在最新的设备和浏览器版本中均可使用。此功能可能在较旧的设备或浏览器中无法使用。

Document 接口的adoptedStyleSheets 属性用于设置一个构造样式表数组，供文档使用。

注意：构造样式表是指使用 CSSStyleSheet() 构造函数 以编程方式创建的样式表（与用户代理在从脚本导入样式表时创建的样式表不同，使用 <style> 和 @import 导入，或通过 <link> 链接）。

相同的构造样式表也可以与一个或多个 ShadowRoot 实例共享，使用 ShadowRoot.adoptedStyleSheets 属性。更改采用的样式表将影响采用它的所有对象。

属性中的样式表与文档的其他样式表一起使用 CSS 级联算法 进行评估。在规则解析考虑样式表顺序的地方，adoptedStyleSheets 被假定为位于 Document.styleSheets 中的样式表之后。

仅在当前 Document 上下文中使用 CSSStyleSheet() 构造函数 创建的样式表才能被采用。

值

该值是一个 CSSStyleSheet 实例数组，这些实例必须使用 CSSStyleSheet() 构造函数在同一个 Document 上下文中创建。

如果需要修改数组，请使用就地变异，如 push()。CSSStyleSheet 实例本身也可以修改，这些更改将在任何采用该样式表的地方生效。

在规范的早期版本中，数组是不可修改的，因此添加新样式表的唯一方法是将新数组分配给 adoptedStyleSheets。

异常

NotAllowedError DOMException

数组中的一个 CSSStyleSheet 实例不是使用 CSSStyleSheet() 构造函数 创建的，或者是在与当前文档不同的文档（例如框架中的文档）中构造的。

示例

采用样式表

以下代码显示了一个样式表被构造，然后调用 CSSStyleSheet.replaceSync() 向该表添加规则。然后将该样式表添加到数组中并分配给 adoptedStyleSheets 属性。

js
// Create an empty "constructed" stylesheet
const sheet = new CSSStyleSheet();
// Apply a rule to the sheet
sheet.replaceSync("a { color: red; }");

// Apply the stylesheet to a document
document.adoptedStyleSheets = [sheet];

我们可以使用 CSSStyleSheet.insertRule() 将新规则追加到样式表中。

js
sheet.insertRule("* { background-color: blue; }");
// The document will now have blue background.

追加新的样式表

要将一个全新的样式表追加到 adoptedStyleSheets 属性，我们必须创建一个新的组合数组并分配给它。以下使用扩展语法演示了这一点。

js
const extraSheet = new CSSStyleSheet();
extraSheet.replaceSync("p { color: green; }");

// Combine the existing sheets and new one
document.adoptedStyleSheets = [...document.adoptedStyleSheets, extraSheet];

与 Shadow DOM 共享样式表

我们可以以类似的方式将样式表共享到影子根。

js
// Create an element in the document and then create a shadow root:
const node = document.createElement("div");
const shadow = node.attachShadow({ mode: "open" });

//Adopt the same sheet into the shadow DOM
shadow.adoptedStyleSheets = [sheet];

规范

规范
CSS 对象模型 (CSSOM)
# dom-documentorshadowroot-adoptedstylesheets

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。

另请参阅