HTML文档结构中的影子DOM结构初探

作者：袖梨 2026-07-04

Shadow DOM 是与主 DOM 并行的独立子树，仅特定元素（如自定义元素或 div）可作为宿主，div 不支持声明式 shadowroot 属性，须用 attachShadow()；样式需通过 :host 和 ::slotted 控制；DOM 查询和事件必须限定在 shadowRoot 内。

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

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

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

调用失败基本就三类原因：宿主不支持、参数缺失、重复挂载。

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

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

立即学习“前端免费学习笔记（深入）”；

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

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

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