--- title: Element.attachShadow() slug: Web/API/Element/attachShadow tags: - API - 元素 - 参考 - 方法 translation_of: Web/API/Element/attachShadow ---

{{APIRef('Shadow DOM')}}

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

可以被挂载的shadow DOM元素

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

语法

var shadowroot = element.attachShadow(shadowRootInit);

参数

shadowRootInit
一个 ShadowRootInit 字典，包括下列字段：
mode 模式

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

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

返回值

返回一个 {{domxref("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' });

规范

标准 状态 备注
{{SpecName('DOM WHATWG', '#dom-element-attachshadow', 'attachShadow()')}} {{Spec2('DOM WHATWG')}}

浏览器兼容性

{{Compat("api.Element.attachShadow")}}