UI 组件 · 反馈
对话框
Modal
也叫：弹窗、模态框、Dialog、弹出框
在页面正中弹出的窗口，背后加遮罩，用户必须处理完或关闭它才能继续操作页面。
点「标注」看每个部分叫什么，点「反例」看最常见的错误用法。
怎么跟 AI 说
改成你的业务内容再发点击「新建项目」按钮弹出一个居中的对话框，宽 520px，背后半透明黑色遮罩；顶部是标题和右上角关闭图标，中间是名称和描述两个输入项，底部右侧放「取消」「创建」按钮；按 Esc 或点关闭图标可关闭，提交时「创建」按钮显示加载状态。
发给
01判断
你的内容是这样吗？
对照两列，确认对话框是不是你要找的。
02避坑
常见坏用法
看起来能用，其实会给用户添麻烦。
- 01
每次操作成功都弹对话框让用户点「确定」，打断操作节奏
下面的线框画的就是这种情况，红色虚线框是出问题的地方。右边的线框画的就是这种情况，红色虚线框是出问题的地方。
- 02
对话框里再弹对话框，层层叠加，关闭顺序混乱
- 03
内容过长时整个窗口超出屏幕，底部按钮滚不到或被截断
03识别
怎么认出它
先看整体结构，再对照几个一眼能认出的特征。
结构
由全屏半透明遮罩和居中窗口组成，窗口内依次是标题栏（含关闭图标）、内容区和底部按钮区。
组成部分点一下，在上面的线框里标出来
识别特征
- 1页面中央一个带圆角和投影的白色窗口
- 2背后整页被半透明深色遮罩盖住
- 3右上角有关闭图标，底部右侧有两个按钮
04解释
详细解释
对话框（也常叫弹窗、模态框）出现时，页面其余部分被半透明遮罩盖住并暂时不能操作，注意力被强制集中到窗口里。它通常有标题、内容区和底部按钮（「取消」「确定」），右上角有关闭图标，按 Esc 也能关闭。适合二次确认、填写一个短表单、查看一段需要专心看的内容。
容易混淆的几个：抽屉 从屏幕边缘滑出，能放更多内容，更适合「边看列表边看详情」；气泡卡片 贴着按钮弹出，不加遮罩，只放少量信息；只是告诉用户「保存成功」这种结果，用 轻提示 就够了，不该弹对话框打断用户。
做对话框要注意：打开时焦点移到窗口内，关闭后焦点回到触发按钮；内容过长时只让内容区滚动，标题和按钮保持固定。
开发者信息术语 ID、DOM 线索、识别优先级
- 术语 ID
component-modal- DOM 选择器
插件在本地识别时匹配这些 CSS 选择器（标签、ARIA role、常见组件库 class）。
dialog[open][role="dialog"][aria-modal="true"][role="alertdialog"].ant-modal.el-dialog.el-message-box[class*="MuiDialog-paper"].arco-modal.t-dialog.n-modal.n-dialog[data-slot="dialog-content"][data-slot="alert-dialog-content"].modal-dialog
- 类名关键词
类名、id、data-testid 拆成单词后连续匹配，例如 page-header、PageHeader_root__x7a、pageHeader 都拆成 page、header。
modaldialogmodal-dialoglightboxmodal-box
- 组件名
React / Vue 开发模式下读到的组件名，不区分大小写，会去掉 El、Ant、Mui 这类组件库前缀。
ModalDialogAlertDialogConfirmDialog
- 语义标签和角色
弱信号，要和其他线索一起才算识别出来。
<dialog>role=dialog
- 结构特征
根据元素的排列和样式算出来的特征，只用来加分，单独不判定。
浮在内容上
- 优先级
- 1 · 同一层有多条命中时，优先级高的胜出
- 版本
- v2 · 更新于 2026/09/30