Element.attachShadow()

Element.attachShadow() 方法给指定的元素挂载一个Shadow DOM,并且返回对 ShadowRoot 的引用。

可以被挂载的shadow DOM元素

要注意的是,不是每一种类型的元素都可以附加到shadow root(影子根)下面。出于安全考虑,一些元素不能使用 shadow DOM(例如<a>),以及许多其他的元素。下面是一个可以挂载 shadow root 的元素列表:

语法

var shadowroot = element.attachShadow(shadowRootInit);

参数

shadowRootInit
一个 ShadowRootInit 字典,包括下列字段:
mode 模式

指定 Shadow DOM 树封装模式的字符串,可以是以下值:

  • open shadow root元素可以从js外部访问根节点,例如使用 Element.shadowRoot:
element.shadowRoot; // 返回一个ShadowRoot对象
  • closed 拒绝从js外部访问关闭的shadow root节点
element.shadowRoot; // 返回null
delegatesFocus 焦点委托
一个布尔值, 当设置为 true 时, 指定减轻自定义元素的聚焦性能问题行为.
当shadow DOM中不可聚焦的部分被点击时, 让第一个可聚焦的部分成为焦点, 并且shadow host(影子主机)将提供所有可用的 :focus 样式.

返回值

返回一个 ShadowRoot 对象或者 null

异常

异常 说明
InvalidStateError
无效状态错误
您添加的元素已经是一个shadow host(影子主机).

NotSupportedError
不被支持错误

您应该添加 HTML 元素的命名空间之外的shadow root, 或者这个元素不能有其他shadow挂载到它上面 (见上).

示例

下面的例子取至 word-count-web-component 片段( 现场看看 ). 你可以看到使用 attachShadow() 在代码中间创建一个shadow root, 然后我们可以将自定义元素的内容挂载添加到它上面。

// 为新元素创建一个类
class WordCount extends HTMLParagraphElement {
  constructor() {
    // 在构造器中先调用一下 super
    super();

    // 计数器指向元素的父级
    var wcParent = this.parentNode;

    function countWords(node){
      var text = node.innerText || node.textContent
      return text.trim().split(/\s+/g).length;
    }

    var count = 'Words: ' + countWords(wcParent);

    // 创建一个shadow root
    var shadow = this.attachShadow({mode: 'open'});

    // 创建文本节点并向其添加计数器
    var text = document.createElement('span');
    text.textContent = count;

    // 将其添加到shadow root上
    shadow.appendChild(text);

    // 当元素内容发生变化时更新计数
    setInterval(function() {
      var count = 'Words: ' + countWords(wcParent);
      text.textContent = count;
    }, 200);
  }
}

// 定义新元素
customElements.define('word-count', WordCount, { extends: 'p' });

规范

标准 状态 备注
DOM
attachShadow()
Living Standard

浏览器兼容性

BCD tables only load in the browser