Dialog 对话框

在保留当前页面状态的情况下，告知用户并承载相关操作。

基础用法

Dialog 弹出一个对话框，通常用于消息提示、消息确认，或在当前页面内完成特定的交互操作。

提示

before-close 只在用户点击关闭图标或者遮罩时生效。如果你在 footer 插槽中添加了关闭对话框的按钮，那么你可以在按钮的点击事件中，添加与 before-close 相同的功能。

自定义内容

对话框的内容可以是任何东西，甚至是一个表格或表单。此示例显示如何将 Element Plus 的 Table 和 Form 与 Dialog 一起使用。

自定义页眉

可以使用 header 插槽来自定义显示标题的区域。为了保持可访问性，除了使用此插槽外，还应使用 title 属性，或使用 titleId 插槽属性来指定哪个元素应作为对话框标题读出。

嵌套的 Dialog

如果一个 Dialog 嵌套在另一个 Dialog 中，需要使用 append-to-body 属性。

内容居中

对话框的内容可以居中。

提示

对话框的内容是懒渲染的，即在第一次被打开之前，传入的默认插槽不会被渲染到 DOM 上。因此，如果你需要执行 DOM 操作或需要访问组件，请在 open 事件回调中进行。

垂直居中对话框

从屏幕中心打开对话框。

关闭时销毁

启用此功能后，默认插槽下的内容将通过 v-if 指令销毁。当你存在性能问题时可以打开这个功能。

可拖拽的对话框

试着拖动 header 部分。

提示

当使用 modal = false 时，请确保 append-to-body 已经设置为 true，因为 Dialog 是通过 position: relative 定位的，当 modal 被移除后，Dialog 将会基于当前的 DOM 位置定位，而不是基于 Document.Body，所以样式会错乱。

全屏

设置 fullscreen 属性来打开全屏对话框。

提示

如果 fullscreen 为 true，则 width、top、draggable 属性不起作用。

将 modal 设置为 false 将隐藏对话框的遮罩层（覆盖层）。

从版本 2.10.5 开始，添加了 modal-penetrable 属性，可以实现可穿透。

自定义动画 2.10.5

通过 transition 属性自定义对话框动画，它接受

Transition 名称 (字符串)
Vue transition 配置 (对象)

提示

动画类是根据 transition 名称动态生成的。为了更精细地控制动画行为，您可以显式定义这些类。详情请参阅自定义过渡类。

事件

打开开发者控制台 (ctrl + shift + J)，以查看事件的顺序。

API

属性

名称	描述	类型	默认值
model-value / v-model	Dialog 的可见性	`boolean`	false
title	Dialog 的标题。也可以通过具名插槽传递（参见下表）	`string`	''
width	Dialog 的宽度，默认为 50%	`string` / `number`	''
全屏	Dialog 是否占据全屏	`boolean`	false
上	Dialog CSS 的 `margin-top` 值，默认为 15vh	`string`	''
遮罩层	是否显示遮罩层	`boolean`	true
modal-penetrable 2.10.5	遮罩层是否可穿透。modal 属性必须为 `false`。	`boolean`	false
modal-class	遮罩层的自定义类名	`string`	—
header-class 2.9.3	头部包装器的自定义类名	`string`	—
body-class 2.9.3	主体包装器的自定义类名	`string`	—
footer-class 2.9.3	底部包装器的自定义类名	`string`	—
append-to-body	是否将 Dialog 自身附加到 body。嵌套的 Dialog 应将此属性设置为 `true`	`boolean`	false
append-to 2.4.3	Dialog 附加到的元素。将覆盖 `append-to-body`	`CSSSelector` / `HTMLElement`	body
lock-scroll	Dialog 显示时是否禁用 body 滚动	`boolean`	true
open-delay	打开前的时间（毫秒）	`number`	0
close-delay	关闭前的时间（毫秒）	`number`	0
close-on-click-modal	是否可以通过点击遮罩层关闭 Dialog	`boolean`	true
close-on-press-escape	是否可以通过按 ESC 关闭 Dialog	`boolean`	true
show-close	是否显示关闭按钮	`boolean`	true
before-close	Dialog 关闭前的回调，它将阻止 Dialog 关闭，使用 done 关闭对话框	`Function`	—
draggable	为 Dialog 启用可拖拽功能	`boolean`	false
overflow 2.5.4	可拖动的 Dialog 可以溢出视口	`boolean`	false
居中	是否将头部和底部居中对齐	`boolean`	false
align-center 2.2.16	对话框是否水平和垂直对齐	`boolean`	false
destroy-on-close	关闭时销毁 Dialog 中的元素	`boolean`	false
close-icon	自定义关闭图标，默认为 Close	`string` / `Component`	—
z-index	与原生 CSS 中的 z-index 相同，dialog 的 z-order	`number`	—
header-aria-level a11y	头部的 `aria-level` 属性	`string`	2
transition 2.10.5	对话框动画的自定义过渡配置。可以是一个字符串 (过渡名称) 或一个带有 Vue 过渡 props 的对象	`string` / `object`	dialog-fade
custom-class 已弃用	Dialog 的自定义类名	`string`	''

警告

custom-class 已被 **弃用**，并将 **在** 2.4.0 中移除，请使用 class。

插槽

名称	描述
default	Dialog 的默认内容
header	Dialog 头部的内容；替换此项会移除标题，但不会移除关闭按钮。
footer	Dialog 底部的内容
title 已弃用	与 header 插槽作用相同。请使用 header 插槽。

警告

title 已被 **弃用**，并将 **在** 3.0.0 中移除，请使用 header。

事件

名称	描述	类型
open	当 Dialog 打开时触发	`Function`
opened	当 Dialog 打开动画结束时触发	`Function`
关闭	当 Dialog 关闭时触发	`Function`
closed	当 Dialog 关闭动画结束时触发	`Function`
open-auto-focus	在 Dialog 打开且内容获得焦点后触发	`Function`
close-auto-focus	在 Dialog 关闭且内容获得焦点后触发	`Function`