HTML文档影子DOM结构初探

先说几个核心判断：Shadow DOM 和主 DOM 树的关系，就像同一座大楼里两个独立的房间——共享同一个屋顶（看得到主页面），但门一关，里面自成体系。这一点很多文档都讲得不对，今天挑几个实操中最容易出状况的坑位，一次性说清楚。

Shadow DOM 不是“另一种 DOM 结构”，而是主 DOM 树之外、与之并行存在的独立子树。它不改变 HTML 文档整体结构，只在特定宿主元素下开辟一个隔离层。

为什么 div 不能直接用 template shadowroot="open"

这是规范硬性限制，不是浏览器兼容问题。只有已注册的自定义元素（如 ）才能作为声明式 Shadow DOM 的宿主。

• 中的 shadowroot 属性会被完全忽略，div.shadowRoot 始终为 null
• 验证是否生效：直接在控制台查 document.querySelector('my-button').shadowRoot 是否返回 ShadowRoot 实例
• 想对 div 附加 Shadow DOM？必须用 JavaScript 调用 attachShadow()，且仅限支持的元素类型（div、span、自定义元素等，但 、 不允许）

attachShadow() 的参数和常见报错

调用失败基本就三类原因：宿主不支持、参数缺失、重复挂载。来看几个典型场景：

• 报错 Failed to execute 'attachShadow' on 'Element': This element does not support shadow roots → 检查宿主是否为 、 等替换元素，它们禁止挂载
• 不传参数或传空对象会直接抛 TypeError；必须显式传入 { mode: 'open' } 或 { mode: 'closed' }
• 同一元素多次调用 attachShadow() → 抛 InvalidStateError；挂载前先判断 !el.shadowRoot
• mode: 'closed' 下外部 JS 无法访问 shadowRoot，调试困难，日常开发一律用 'open'

样式怎么进 Shadow DOM？:host 和 ::slotted 是关键

Shadow DOM 内部样式默认不泄露，外部样式也进不来——但这不等于“不用写样式”。真正起作用的是三个伪类，漏掉任意一个都可能布局错乱。

• :host 匹配宿主元素自身，例如 上设 display: block 必须写在 Shadow DOM 内的 里
• :host(.theme-dark) 可响应宿主上的 class，实现主题切换，但 class 必须由外部 JS 或 HTML 显式添加
• ::slotted(*) 匹配所有被 投影进来的内容，常用来重置外层传入节点的 margin、padding，否则容易塌陷
• 必须写在 内部（声明式）或 shadowRoot.innerHTML / appendChild(styleEl)（JS 创建），外部 完全无效

DOM 查询和事件监听必须限定作用域

Shadow DOM 天然隔离，document.querySelector() 和 element.children 都看不到内部结构——这不是 bug，是设计前提。看清楚了：

• 查内部按钮：host.shadowRoot.querySelector('button')，而不是 host.querySelector('button')
• 查 slot 里渲染出的标题：host.shadowRoot.querySelector('h2')（前提是该 h2 确实被 渲染出来了）
• 监听内部按钮点击：事件监听器必须绑定在 shadowRoot 或内部节点上；若想在宿主上统一捕获，需利用事件冒泡 + event.composedPath() 判断来源
• 本身不渲染，只是出口；没写 ，投进去的子节点会被丢弃（除非用具名 + slot="xxx" 显式匹配）

最容易被忽略的一点：Shadow DOM 的布局容器（比如 flex 容器、grid 容器）必须定义在 Shadow DOM 内部，不能依赖外部 CSS 设置 display 属性来驱动内部排列——因为外部样式根本进不去。