<dialog>不是开箱即用的替代品，必须显式调用showModal()或show()才能渲染，且默认无遮罩、无关闭逻辑、无焦点管理；直接替换旧弹窗会导致白屏或交互失效。

<dialog> 在旧项目弹窗重构中不是“开箱即用”的替代品，它需要显式调用 showModal() 或 show() 才能渲染，且默认无遮罩、无关闭逻辑、无焦点管理 —— 直接替换 div 弹窗会白屏或交互失效。

dialog 元素必须手动激活才能显示

旧项目常用 display: block 或 visibility: visible 控制弹窗显隐，但 <dialog> 不响应 CSS 显隐控制。它被插入 DOM 后仍处于“未打开”状态，不调用 JS 方法就永远不呈现。

• 必须用 dialog.showModal()（模态）或 dialog.show()（非模态）触发渲染
• open 属性仅作状态标记，不能靠它驱动显示（设了 open 但没调用方法，依然不可见）
• 服务端渲染或静态 HTML 中写 <dialog open> 是无效的，首次加载不会自动弹出
• 建议在初始化脚本中统一查找 dialog 并绑定触发逻辑，例如：

  document.querySelectorAll('dialog[data-trigger]').forEach(d => {
    const btn = document.querySelector(d.dataset.trigger);
    btn?.addEventListener('click', () => d.showModal());
  });

点击 backdrop 默认不关闭，需手动监听 cancel 事件

旧弹窗普遍支持“点遮罩层关闭”，但 <dialog> 的 backdrop 点击不会触发任何行为，必须监听 cancel 事件并自行处理关闭，否则用户无法退出。

anything-to-html

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

下载

• cancel 事件仅在 showModal() 模式下触发（按 Esc 或点 backdrop），show() 模式下不触发
• 默认行为是阻止关闭，需显式调用 event.preventDefault() 才能维持打开；若想关闭，应调用 dialog.close()
• 常见错误：只监听 click 到 dialog::backdrop —— 该伪元素无法直接绑定事件，只能靠 cancel
• 正确写法示例：

  dialog.addEventListener('cancel', (e) => {
    e.preventDefault(); // 阻止默认关闭（可选）
    dialog.close();     // 主动关闭
  });

样式重置多、兼容性差，旧项目需兜底降级

<dialog> 浏览器原生样式差异大：Chrome 有圆角阴影和居中，Firefox 无默认 padding，Safari 15.4+ 才支持，iOS Safari 至今不支持 showModal() —— 旧项目上线前必须检查 UA 并 fallback。

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

• 所有关键样式（width、margin、padding、border）都要重写，不能依赖浏览器默认
• Safari 用户会看到 dialog 渲染为普通块级元素、无遮罩、无居中，需用 JS 检测：

  if (!dialog.showModal) {
    // 降级为 div + 手动实现遮罩/定位/焦点管理
  }

• 无障碍方面，<dialog> 自动添加 role="dialog" 和 aria-modal="true"，但旧项目若已有 ARIA 逻辑，可能重复标注，需清理冗余属性

真正难的不是把 div 换成 dialog，而是补全它故意留白的部分：打开控制、关闭路径、焦点锁定、键盘导航、样式归一、降级分支 —— 少一个，旧项目就多一处不可用风险。