必须在 DOM 就绪后调用 dialog.showModal()，正确做法是将 script 放在 /body 前或包裹在 DOMContentLoaded 事件中；dialog 必须是 body 直系子元素才能确保 backdrop、焦点锁定等模态行为正常；表单提交需用 method="dialog" 或 e.preventDefault() 避免刷新；Safari 存在 backdrop 点击判断失效、returnValue 不可用等兼容性问题。
dialog.showModal() 必须在 DOM 就绪后调用，否则报 Cannot read property 'showModal' of null
常见错误是把 dialog.showModal() 写在 script 标签顶部，或未等 DOM 加载完就执行。浏览器还没解析到 <dialog id="my-dialog">，document.getElementById('my-dialog') 就是 null。
正确做法只有两种：
- 把
<script>放在</body>前（最简单） - 或包裹在
DOMContentLoaded事件里：document.addEventListener('DOMContentLoaded', () => { const dialog = document.getElementById('my-dialog'); dialog.showModal(); });
别用 window.onload —— 它等所有资源（图片、CSS）加载完才触发，延迟明显；也别在按钮点击前就调用 showModal()，那会提前弹出，没内容。
异步加载内容必须注入到已挂载的 dialog 元素内，且需确保它是 body 直系子元素
<dialog> 的模态行为（backdrop、焦点锁定、Esc 响应）只在它作为 document.body 的直接子节点时才可靠。如果把它写在某个组件容器里（比如 <div class="editor"><dialog></dialog></div>），Safari 和部分安卓 WebView 会彻底不渲染 backdrop，甚至无法聚焦。
立即学习“前端免费学习笔记（深入）”；
实操建议：
- 初始化阶段用
document.body.appendChild(dialog)显式挂载，不要依赖 HTML 静态位置 - 异步请求（如
fetch('/form.html')）完成后，用dialog.innerHTML = responseText或更安全的dialog.replaceChildren(...)注入内容 - 避免用
innerHTML +=拼接，会清空已有事件监听器和表单状态 - 注入后手动调用
dialog.querySelector('input')?.focus()，尤其在 Safari 中，首次showModal()后焦点可能丢失
表单提交不刷新页面的关键：用 method="dialog" 或 e.preventDefault()
在 <dialog> 里放 <form> 是高频场景，但默认提交会整页 reload，看起来像“弹窗闪退”。
两种解法，适用不同需求：
- 纯前端表单（无异步逻辑）：直接给
<form method="dialog">。提交后自动触发dialog.close()，并设置dialog.returnValue（值为 submit 按钮的value或空字符串） - 需要 fetch 提交的场景：必须监听
submit事件，第一时间e.preventDefault()，再手动发起请求；成功后调用dialog.close()，失败则保留弹窗并提示错误 - 千万别只在「确定」按钮上写
onclick="dialog.close()"—— 用户按回车提交时不会触发，导致表单意外提交刷新
注意：method="dialog" 不支持 enctype="application/json"，传 JSON 必须走 fetch + e.preventDefault() 路径。
Safari 兼容性陷阱：backdrop 点击不可靠，event.target === dialog 在旧版 Safari 失效
Chrome/Edge 中，点击 backdrop 触发的 click 事件，e.target 就是 dialog 元素本身，所以 if (e.target === dialog) dialog.close() 可行。但 Safari 15.4–16.3 中，e.target 常是 body 或 html，无法准确判断是否点在 backdrop 上。
稳妥 fallback 方案：
- 监听
click后，检查e.clientX和e.clientY是否落在dialog.getBoundingClientRect()区域外 - 或放弃依赖 backdrop 判断，改用显式「取消」按钮 + Esc 键监听：
dialog.addEventListener('keydown', e => { if (e.key === 'Escape') dialog.close(); }); - 若业务要求强关闭控制（如表单未保存禁止关闭），应在
close事件中e.preventDefault()，而不是试图禁用 backdrop 点击
真正容易被忽略的是：Safari 中 dialog.returnValue 一直不可用，哪怕 close('confirmed') 之后读取也是 undefined —— 如果需要返回值，必须自己用变量暂存或通过自定义事件传递。
