ShadowRoot

基线 广泛可用

此功能已广泛建立,并在许多设备和浏览器版本中都能正常使用。它自 2020 年 1 月.

报告反馈

ShadowRoot 是 Shadow DOM API 的一个接口,它是 DOM 子树的根节点,该子树与文档的主 DOM 树分开呈现。

EventTarget Node DocumentFragment ShadowRoot

实例属性

ShadowRoot.activeElement 只读

返回拥有焦点的影子树中的 Element

ShadowRoot.adoptedStyleSheets

将构造的样式表数组添加到 Shadow DOM 子树中使用。这些样式表可以与其他 DOM 子树共享,这些子树与同一个父 Document 节点共享,以及文档本身。

ShadowRoot.clonable 只读

一个布尔值,指示影子树是否可克隆。

ShadowRoot.delegatesFocus 只读

一个布尔值,指示如果选择了不可聚焦的节点,影子树是否委托焦点。

ShadowRoot.fullscreenElement 只读

当前处于此影子树的全屏模式下的元素。

ShadowRoot.host 只读

返回 ShadowRoot 附加到的 DOM 元素的引用。

ShadowRoot.innerHTML

设置或返回 ShadowRoot 内 DOM 树的引用。

ShadowRoot.mode 只读

ShadowRoot 的模式,openclosed 之一。这定义了影子树的内部功能是否可从 JavaScript 访问。

ShadowRoot.pictureInPictureElement 只读

返回当前以画中画模式呈现的影子树中的 Element

ShadowRoot.pointerLockElement 只读

返回在指针锁定期间设置为鼠标事件目标的 Element。如果锁定正在进行中、指针已解锁或目标位于另一棵树中,则返回 null

ShadowRoot.serializable 只读

一个布尔值,指示影子树是否可序列化。当元素中的可序列化影子树的 options.serializableShadowRoots 参数设置为 true 时,它将由 Element.getHTML()ShadowRoot.getHTML() 序列化。这是在创建影子树时设置的。

ShadowRoot.slotAssignment 只读

返回一个字符串,其中包含插槽分配的类型,manualnamed 之一。

ShadowRoot.styleSheets 只读

返回 StyleSheetList,其中包含明确链接到影子树或嵌入影子树中的 CSSStyleSheet 对象。

实例方法

ShadowRoot.getAnimations()

返回当前生效的所有 Animation 对象数组,这些对象的 target 元素是影子树的后代。

ShadowRoot.getSelection() 非标准

返回一个 Selection 对象,该对象表示用户选择的文本范围,或插入符号的当前位置。

ShadowRoot.elementFromPoint() 非标准

返回指定坐标处最顶层的元素。

ShadowRoot.elementsFromPoint() 非标准

返回指定坐标处的所有元素数组。

ShadowRoot.setHTMLUnsafe()

将 HTML 字符串解析为文档片段,不进行清理,然后替换影子树的原始子树。HTML 字符串可能包含声明性影子树,这些影子树将被解析为使用 ShadowRoot.innerHTML 设置的 HTML 的模板元素。

事件

以下事件通过事件冒泡从 HTMLSlotElement 可用于 ShadowRoot

HTMLSlotElement slotchange 事件

该插槽中包含的节点更改时触发的一个事件。

示例

以下代码段取自我们的 life-cycle-callbacks 示例(也请查看实际效果),该示例创建了一个元素,该元素显示一个正方形,其大小和颜色由元素的属性指定。

<custom-square> 元素的类定义中,我们包含一些生命周期回调,这些回调调用外部函数 updateStyle(),该函数实际将大小和颜色应用于元素。您会看到我们正在将 this(自定义元素本身)作为参数传递给它。

js
connectedCallback() {
  console.log('Custom square element added to page.');
  updateStyle(this);
}

attributeChangedCallback(name, oldValue, newValue) {
  console.log('Custom square element attributes changed.');
  updateStyle(this);
}

updateStyle() 函数本身中,我们使用 Element.shadowRoot 获取影子 DOM 的引用。从这里,我们使用标准的 DOM 遍历技术在影子 DOM 内找到 <style> 元素,然后更新其中找到的 CSS。

js
function updateStyle(elem) {
  const shadow = elem.shadowRoot;
  const childNodes = shadow.childNodes;
  for (const node of childNodes) {
    if (node.nodeName === "STYLE") {
      node.textContent = `
div {
  width: ${elem.getAttribute("l")}px;
  height: ${elem.getAttribute("l")}px;
  background-color: ${elem.getAttribute("c")};
}
      `;
    }
  }
}

规范

规范
DOM 标准
# interface-shadowroot

浏览器兼容性

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