dialog 元素默认隐藏，需添加 open 属性或调用 show()/showModal() 才显示；backdrop 点击不自动关闭，须手动监听并判断 target；表单提交需 preventDefault；样式和焦点需手动处理以确保兼容性与可访问性。

dialog 元素不显示？检查 open 属性和 JavaScript 控制

原生

默认是隐藏的，没有 open 属性或 JS 调用就完全不会渲染到视口里。很多人写完 HTML 就以为能弹出来，结果页面上啥也没有。

• 必须显式添加 open 属性才能初始显示：
  ...
• 用 JS 控制时，dialog.show() 和 dialog.showModal() 效果不同：前者不阻塞背景交互，后者才真正是“模态”（背景变灰、Tab 键受限、Esc 关闭）
• dialog.close() 只会移除 open 属性，不会自动移除元素；如果反复创建又不清理，可能积累多个
  节点

点击遮罩层不关闭？dialog 的 backdrop 点击行为需手动绑定

的灰色遮罩（backdrop）默认**不响应点击事件**，哪怕你点了背景也不会关闭——这不是 bug，是设计如此。很多开发者误以为它像 Bootstrap 那样点背景自动关，结果用户卡住了。

• 监听 click 事件时，要区分点击目标：event.target === dialog 才是点在遮罩上，点在内部内容区则 event.target 是子元素
• 推荐写法：dialog.addEventListener('click', e => { if (e.target === dialog) dialog.close(); });
• 注意 Safari 15.4+ 才支持 backdrop click 事件；旧版 Safari 或部分安卓 WebView 中，e.target 可能始终是 ，得 fallback 到 dialog.hasAttribute('open') + 坐标判断

表单提交后 dialog 不关闭？submit 会触发页面刷新

在

里放

很常见，但直接用 type="submit" 会导致整个页面 reload，dialog 看似“闪退”，其实是页面重载了。

DeepBI DHTML 页面生成器

生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur

下载

• 阻止默认行为是必须的：form.addEventListener('submit', e => { e.preventDefault(); /* 处理逻辑 */ dialog.close(); });
• 别依赖 关闭，因为 form 提交优先级更高，可能根本没执行到 onclick
• 如果后端返回 JSON，记得设 form.setAttribute('method', 'POST') 和 form.setAttribute('enctype', 'application/json')，否则 fetch/fetch-like 行为不一致

样式兼容性差？dialog 默认样式极简且各浏览器差异大

没有统一默认样式：Chrome 显示圆角白底带阴影，Firefox 是无边框透明块，Safari 甚至默认不居中。不加 CSS，它大概率难看又难用。

• 必须重置定位：dialog { position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); }，否则在 Safari 中可能贴顶或偏左
• ::backdrop 伪元素控制遮罩样式，但仅 Chrome 和 Firefox 支持；Safari 目前忽略，得用额外
  模拟
• focus 管理容易被忽略：打开后焦点不会自动进 dialog，需手动 dialog.querySelector('input')?.focus()，否则键盘用户无法操作

最麻烦的不是写法，是 focus 管理、键盘导航（Tab 循环、Esc 关闭）、屏幕阅读器语义这些细节——它们不报错，但一上线就被真实用户发现。原生 dialog 看似简单，实则每个交互分支都得亲手补全。