attachShadow 是在支持元素上创建 Shadow Root 的方法,需指定 open/closed 模式,仅能调用一次;支持 div、span、自定义元素等,不支持 img、input 等替换元素;挂载后可操作 DOM 与样式,但重复调用或 SSR 中使用会报错。

attachShadow 是用于在标准 DOM 元素上动态创建并挂载 Shadow Root 的核心方法,它让元素具备 Shadow DOM 能力,实现样式与结构的封装隔离。
基本用法:调用 attachShadow 并指定 mode
必须在支持 Shadow DOM 的元素(如 <div>、<code><span></span>、自定义元素等)上调用,且只能调用一次。关键参数是 { mode: 'open' } 或 { mode: 'closed' }:
-
open:Shadow Root 可被 JavaScript 外部访问(
element.shadowRoot返回实例); -
closed:返回
null,外部无法直接访问 Shadow Root(调试和维护受限,一般不推荐)。
示例:
const host = document.createElement('div');const shadow = host.attachShadow({ mode: 'open' });
shadow.innerHTML = '
Hello from Shadow DOM
立即学习“Java免费学习笔记(深入)”;
常见可挂载 Shadow Root 的元素类型
并非所有元素都支持 attachShadow。以下元素原生支持(主流浏览器均兼容):
- 普通容器类:
<div>、<code><span></span>、<section></section>、<article></article>等; - 部分语义化元素:
<header></header>、<footer></footer>、<aside></aside>; - 自定义元素(需先定义):
customElements.define('my-card', MyCard)后,其实例可调用; -
注意:
<img alt="JavaScript 中 节点操作 怎么利用 attachShadow 动态创建并挂载 Shadow Root" >、<input>、<video></video>、<audio></audio>等替换元素(replaced elements)不支持,会抛出NotSupportedError。 - 用
innerHTML快速注入 HTML 字符串; - 用
appendChild()、append()添加节点; - 用
querySelector()在 Shadow 内部查找(作用域仅限于该 Shadow Root); - 插入
<style></style>实现局部样式封装,例如:
const style = document.createElement('style');
style.textContent = 'p { color: blue; }';
shadow.append(style, document.createElement('p')); - 重复调用
attachShadow会报错:Failed to execute 'attachShadow' on 'Element': Shadow root has already been attached; - 挂载前确保元素已存在于文档或至少已创建(不能对文档片段中的孤立节点调用);
- 若需多次重建 Shadow DOM,应先
host.shadowRoot?.remove(),再重新attachShadow(注意 closed 模式下无法获取 shadowRoot); - 服务端渲染(SSR)环境不支持 Shadow DOM,需在客户端生命周期中执行(如
connectedCallback或DOMContentLoaded后)。
动态创建后立即操作 Shadow DOM 内容
挂载成功后,shadow 即为标准 DocumentFragment,支持所有 DOM 操作:
注意事项与典型错误
使用中容易踩坑的点:


















