---
url: /components/dialog.md
---
# Dialog 对话框

> 移动端：居中模态让位于底部动作面板与全屏表单页，参见 [移动端 · 反馈与浮层](/mobile/feedback)。

模态对话框，在保留页面上下文的前提下承载临时交互：表单填报、操作确认、内容详情等。内置焦点圈禁（Tab 循环锁定在对话框内）、ESC 关闭、遮罩点击关闭、计数式滚动锁定与 zIndex 自动递增；`v-model` 控制显隐，`before-close` 可统一拦截所有关闭途径（右上角按钮 / ESC / 遮罩 / 程序化 `handleClose`）。

## 基础用法

`v-model` 绑定显隐；`title` 设置标题（同时作为 aria-label），`width` 控制宽度，数字按 px、字符串原样输出（默认 520px，且最大不超过视口减 32px）。footer 通过插槽传入操作按钮。

## 垂直居中与顶部偏移

对话框默认距视口顶部 15vh，`top` 可调整偏移；`align-center` 让对话框在视口内水平垂直双居中（设置后 top 不生效），适合确认类小弹窗。

## 全屏与自定义头部

`fullscreen` 铺满整个视口（忽略 width 与 top）；`#header` 插槽替换默认标题区，右上角关闭按钮独立于插槽渲染，不会被覆盖。

## 拦截关闭（before-close）

`before-close` 接收 done 回调：不调用 done 则本次关闭被阻止。右上角关闭按钮、ESC、点击遮罩触发的关闭都会先经过它，可在此做异步校验或二次确认。

## 禁用遮罩与 ESC 关闭

表单类对话框不希望误触丢失内容：`close-on-click-modal` 与 `close-on-press-escape` 置为 false 后，只能通过显式按钮关闭；`show-close` 置为 false 还可隐藏右上角关闭按钮。

## API