toggle 不是标准事件，监听会报错；响应模态框需用 dialog 的 open/close 事件或自定义 CustomEvent；动画须依赖 opacity、transform 等可过渡属性，避免 display/visibility。
toggle 不是 HTML 或 DOM 的标准事件，也没有 toggle 事件能直接监听模态框的打开/关闭。所谓“toggle 模态框”，本质是手动控制显隐状态（如切换 open 属性、display、visibility 或 class），再配合 CSS 动画实现过渡效果。
为什么 document.addEventListener('toggle', ...) 会报错
浏览器根本不派发名为 toggle 的原生事件。你可能会在控制台看到 TypeError: Cannot read property 'addEventListener' of null 或静默失败——因为根本没这个事件类型。混淆通常来自两个地方：<dialog></dialog> 元素有 open 属性和 showModal()/close() 方法，但它的生命周期事件是 open 和 close（注意不是 toggle）；另一个是自定义 JS 中用 element.classList.toggle('active')，这只是个方法调用，不触发事件。
- 想响应模态框打开？监听
dialogEl.addEventListener('open', handler)（仅限<dialog></dialog>） - 想响应关闭？用
dialogEl.addEventListener('close', handler)，它在close()调用后触发 - 用
div实现的模态框？必须自己 dispatchCustomEvent，比如el.dispatchEvent(new CustomEvent('modal-open')) - 别写
on toggle="..."或addEventListener('toggle', ...)—— 它们永远不执行
用 <dialog></dialog> + open/close 事件做动画的正确姿势
<dialog></dialog> 默认没有入场/退场动画，showModal() 是同步显示，close() 是同步隐藏。要加动画，得靠 CSS 的 transition + transform/opacity，并利用 open 属性切换的时机。
-
<dialog></dialog>初始状态必须带open属性或通过 JS 控制，否则:not([open])选择器无效 - 动画不能写在
dialog:not([open])上——它一隐藏就被移出渲染树，transition 失效；应写在dialog[open]及其子元素上，用opacity和transform控制进出 - 推荐结构：
<dialog class="modal"><div class="modal-inner">...</div></dialog>，动画加在.modal-inner上 - CSS 示例：
.modal-inner { opacity: 0; transform: scale(0.95); transition: opacity 0.2s ease, transform 0.2s ease; } .modal[open] .modal-inner { opacity: 1; transform: scale(1); } - 注意：Safari ≤ 16.6 对
[open]的 transition 支持不稳定，建议加will-change: transform;提前提示
用 class 切换实现 toggle 动画时，transition 为什么不动
最常见错误是试图对 display 或 visibility 做 transition——它们不可动画。一旦设为 display: none，元素立刻脱离布局流，浏览器无法插帧；visibility: hidden 虽保留空间，但本身无过渡能力。
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
立即学习“前端免费学习笔记（深入）”；
- 正确做法：只用可动画属性，如
opacity、transform、max-height（需固定值）、box-shadow - 避免
max-height: 0 → 500px：若内容实际高度小于 500px，收起时会“悬停”；更稳妥的是max-height: 0 → fit-content，但后者无法 transition，得用 JS 读高后设内联 style - 推荐组合：
opacity: 0 → 1+transform: translateY(-10px) → translateY(0)，性能好、兼容性强 - JS 触发时机关键：先加 class（如
is-open），再强制重排（getComputedStyle(el).height），再加is-opening类启动 transition；关闭同理，先移除is-open，再加is-closing
移动端点击关闭模态框后，背景还能滚动？
这是焦点与 inert 缺失的典型表现。<dialog></dialog> 自动锁定背景滚动（body 加 overflow: hidden），但自定义 div 模态框不会。用户滑动屏幕时，背景仍在动，说明遮罩层没生效或 body 未被限制。
- 必须手动控制：
modalEl.showModal()后，加document.body.style.overflow = 'hidden';；close()后恢复'auto' - 更健壮的做法：用
inert属性标记背景区域（document.body.inert = true），但 IE 和 Safari ≤ 15.6 不支持，需回退到aria-hidden="true"+tabindex="-1" - 键盘焦点必须管理：打开时
modalEl.focus()，关闭时把焦点还给触发按钮（triggerBtn.focus()），否则屏幕阅读器会迷失 - 移动端点击蒙层关闭，需确保蒙层
z-index高于所有内容，且监听click事件时判断e.target === overlayEl，而非e.currentTarget
真正难的不是让动画跑起来，而是让动画在 Safari、旧 Android WebView、屏幕阅读器和键盘导航下都保持一致行为——这些细节不写进 JS 就不会自动发生。
