原生 <dialog> 必须是 <body> 的直接子元素才能正常工作；在 Shadow DOM 中需手动移入 document.body，再调用 showModal()。
原生 <dialog> 不能直接放进 Shadow DOM 内部并期望它正常工作——浏览器会拒绝渲染 backdrop、焦点管理失效、showModal() 抛错或静默失败。真正可用的组合只有一种：在自定义元素内部创建 Shadow DOM，再把 <dialog> 放进 shadowRoot，**但必须确保它最终被插入到 <body> 的直接子级位置，并在正确上下文中调用 showModal()**。
为什么 <dialog> 在 shadowRoot 里调用 showModal() 会失败
浏览器对 <dialog> 的 Top Layer 渲染有硬性 DOM 位置要求：<dialog> 必须是 <body> 的直接子元素。Shadow DOM 是一个逻辑隔离边界，不是 DOM 层级的“提升”。即使你在 this.shadowRoot.appendChild(dialog)，该 <dialog> 节点的父节点仍是 shadow root，而非 <body>。
常见错误现象：
-
dialog.showModal()抛出DOMException: Failed to execute 'showModal' on 'HTMLDialogElement': The element is not in a document. - 控制台无报错，但点击无反应、Esc 不关闭、Tab 键逃逸到背景页
- Safari 中完全不居中，Chrome 显示但 backdrop 错位或透明
根本原因：Top Layer 机制只识别文档树（light DOM）中的 <body> 直系后代；shadow tree 内的节点不在其扫描范围内。
立即学习“前端免费学习笔记（深入）”；
正确做法：从 Shadow DOM “移出” <dialog> 到 <body>
你需要在自定义元素生命周期中，将 <dialog> 节点手动移动到 document.body 下，并保留对其引用以便后续操作。这不是 hack，而是当前标准下唯一可靠路径。
实操要点：
- 在自定义元素的
connectedCallback()中创建<dialog>，但先不 append 到 shadowRoot - 立即执行
document.body.appendChild(dialog)，使其成为<body>的直系子节点 - 用
dialog.setAttribute('aria-hidden', 'true')初始隐藏，避免 FOUC - 通过
this._dialog = dialog保存引用，供后续open()/close()方法使用 - 监听
dialog.close事件，在回调中清理状态（如恢复焦点、触发自定义事件）
示例关键片段：
class ModalDialog extends HTMLElement {
constructor() {
super();
this._dialog = document.createElement('dialog');
this._dialog.setAttribute('aria-hidden', 'true');
document.body.appendChild(this._dialog); // ✅ 关键：挂到 body 下
}
open() {
this._dialog.removeAttribute('aria-hidden');
this._dialog.showModal(); // ✅ 此时才真正生效
}
close() {
this._dialog.close();
}
}
样式与交互必须绕过 Shadow DOM 封装做适配
虽然 <dialog> 被移出了 shadowRoot，但它仍需响应宿主元素的状态（比如主题色、尺寸配置），而这些信息只在 shadow host 上。你不能靠外部 CSS 选中它，也不能在 shadow 内写 dialog::backdrop —— 那个伪元素只对 light DOM 中的原生 <dialog> 生效，且仅当它处于 Top Layer 时。
解决方案是显式桥接：
- 用
this._dialog.style.setProperty('--modal-bg', getComputedStyle(this).getPropertyValue('--modal-bg'))同步 CSS 变量 - 给
<dialog>添加动态 class：this._dialog.className = `modal-theme-${this.getAttribute('theme') || 'light'}` - 为 backdrop 手动添加覆盖层：
<div class="backdrop"></div>，用 JS 控制显隐和 z-index，别依赖::backdrop - 点击 backdrop 关闭：监听
this._dialog.addEventListener('click', e => { if (e.target === this._dialog) this.close(); })，注意 Safari fallback 坐标判断
⚠️ 注意：::backdrop 在 Safari 15.4–16.3 中不可靠，且无法通过 shadow 内部样式控制；必须用真实 DOM 节点替代。
多个对话框分层顺序由 showModal() 调用时机决定
如果你有 <error-notifier> 和 <data-form> 两个基于此模式的组件，它们的 <dialog> 都挂在 <body> 下，但谁在最上层？不是 DOM 顺序，不是自定义元素定义顺序，而是最后一次成功调用 showModal() 的那个。
这意味着：
- 错误通知组件必须在业务逻辑检测到错误后，立刻调用
this._dialog.showModal() - 如果表单弹窗已打开，你再调用通知的
showModal()，它就会自动置顶 - 不要试图用
z-index硬控 —— Top Layer 不参与普通堆叠上下文，z-index对它无效 - 关闭后再
showModal()，它会重新入栈顶，不是追加
最容易被忽略的一点：所有 showModal() 调用必须发生在 DOM 已就绪、且目标 <dialog> 已挂载到 <body> 之后；否则静默失败，无任何提示。
