HTML文档结构中模态框标签焦点穿透的底层DOM事件全场景排查-html教程-PHP中文网

focusin 事件必须在模态框挂载后的首个 microtask 或 requestanimationframe 中绑定，否则 tab 焦点会逃逸；dialog 自身不可聚焦，需确保其内有合法可聚焦元素；ios safari 中 focus() 需在用户手势同步栈中调用，遮罩层失效多因 dom 嵌套、z-index 隔离或尺寸缺失。

html文档结构中模态框标签焦点穿透的底层dom事件全场景排查

focusin 事件没监听到，焦点早逃逸了

模态框打开后按 Tab 就跳到地址栏，不是 trap 没写对，而是根本没捕获到焦点进入容器的瞬间。focusin 是唯一能覆盖所有入口（键盘、鼠标、屏幕阅读器快捷键）的事件，focus/blur 不冒泡，绑在 document 上也收不到子元素的焦点变化。

必须在模态框 DOM 挂载完成后的**第一个 microtask 或 requestAnimationFrame 里**绑定 focusin 监听器，不能等 click 回调结束再加——否则用户手快按 Tab，事件已经发出去了。

错误写法：button.addEventListener('click', () => { modal.showModal(); modal.addEventListener('focusin', handler); });（时机太晚）
正确写法：modal.showModal(); requestAnimationFrame(() => modal.addEventListener('focusin', handler));
如果 modal 内容异步加载（比如 fetch 后插入表单），得等内容插入完毕再 bind，不能只看 showModal() 返回

dialog 元素自身不可聚焦，别指望 tabindex="-1" 能兜底

dialog.showModal() 只会尝试聚焦第一个可聚焦子元素，它不会把焦点落在 <dialog></dialog> 自身上——哪怕你写了 tabindex="-1"。Safari 和部分屏幕阅读器直接忽略该设置，焦点退回到 document.body，后续所有 trap 逻辑都失效。

必须确保模态框内存在至少一个满足以下全部条件的元素：

anything-to-html

将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。

下载

是原生可聚焦标签：<button></button>、<input>、<textarea></textarea>、<select></select>
或显式设 tabindex="0" 的容器（不能是 -1，除非你手动 .focus()）
没有 disabled 属性，且父级没设 inert
不在 opacity: 0 或 visibility: hidden 的动画过渡中（iOS Safari 下 focus() 静默失败）

移动端 touchend 后焦点未激活，是因为脱离手势上下文

iOS Safari 对 .focus() 有严格限制：必须发生在用户手势（touchend、click、keydown）的同步执行栈中。一旦中间穿插了 Promise.then、setTimeout、fetch 回调或路由跳转，就失去上下文，调用不报错但无效。

典型翻车链路：touchend → this.showDialog() → fetch().then(() => this.renderForm()) → input.focus() —— 这里 focus 已失效。

修复方案：把 input.focus() 放进 touchend 处理函数末尾，或用 event.preventDefault(); input.focus(); 紧跟触发
若必须异步渲染，改用 dialog.addEventListener('focusin', () => input.focus(), { once: true })，靠事件流自然触发
避免在 useEffect 或 mounted 钩子里调用 focus()，它们和用户操作不同步

遮罩层（overlay）点击关闭失效，90% 是事件没落到它身上

遮罩点不关，不是 JS 写错了，而是 DOM 结构或 CSS 层级让点击根本没触发 overlay 的事件。常见原因有三：

overlay 和 modal **嵌套了**：比如 <div class="overlay"><dialog>...</dialog></div> —— 点击区域实际是 dialog，事件冒泡到 overlay 前就被 stopPropagation() 截断
z-index 创建了隔离层叠上下文：overlay 和 modal 的共同父容器有 transform、opacity 或 <code>filter，导致它们的 z-index 彼此不可比
overlay 没尺寸：仅靠 position: fixed 不够，必须显式设 width: 100vw; height: 100vh;，否则 iOS Safari 认为“不可点击区域”

验证方法：在控制台执行 document.elementFromPoint(x, y)（x/y 取遮罩中心坐标），看返回是不是 overlay 元素。不是？说明它被盖住或没渲染出来。