大网数据广告活动
Web 标准与前端开发

Element.attachShadow()

· 52CE 我爱测

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

Shadow DOM

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

可以被挂载的 shadow DOM 元素

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

  • 任何带有有效的名称且可独立存在的(autonomous)自定义元素
  • article
  • aside
  • blockquote
  • body
  • div
  • footer
  • h1
  • h2
  • h3
  • h4
  • h5
  • h6
  • header
  • main
  • nav
  • p
  • section
  • span

语法

attachShadow(options)

参数

  • options
    • : 一个包括下列字段的对象:
      • mode

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

          • open shadow root 元素可以从 js 外部访问根节点,例如使用 Element.shadowRoot:
          element.attachShadow({ mode: "open" });
          element.shadowRoot; // 返回一个 ShadowRoot 对象
          
          • closed 拒绝从 js 外部访问关闭的 shadow root 节点
          element.attachShadow({ mode: "closed" });
          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" });

规范

浏览器兼容性

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。