Dialog 对话框

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

基础用法

Dialog 弹出一个对话框,适合需要定制性更大的场景。

需要设置 model-value / v-model 属性,它接收 Boolean,当为 true 时显示 Dialog。 Dialog 分为两个部分:bodyfooterfooter 需要具名为 footerslottitle 属性用于定义标题,它是可选的,默认值为空。 最后,本例还展示了 before-close 的用法。

TIP

before-close 只会在用户点击关闭按钮或者对话框的遮罩区域时被调用。 如果你在 footer 具名 slot 里添加了用于关闭 Dialog 的按钮,那么可以在按钮的点击回调函数里加入 before-close 的相关逻辑。

自定义内容

对话框的内容可以是任何东西,甚至是一个表格或表单。 此示例显示如何在 Dialog 中使用 Element Plus 的表格和表单。

自定义头部

header 可用于自定义显示标题的区域。 为了保持可用性,除了使用此插槽外,使用 title 属性,或使用 titleId 插槽属性来指定哪些元素应该读取为对话框标题。

嵌套的对话框

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

通常我们不建议使用嵌套对话框。 如果你需要在页面上呈现多个对话框,你可以简单地打平它们,以便它们彼此之间是平级关系。 如果必须要在一个对话框内展示另一个对话框,可以将内部嵌套的对话框属性 append-to-body 设置为 true,嵌套的对话框将附加到 body 而不是其父节点,这样两个对话框都可以被正确地渲染。

内容居中

对话框的内容可以居中。

center设置为true即可使标题和底部居中。 center仅影响标题和底部区域。 Dialog 的内容是任意的,在一些情况下,内容并不适合居中布局。 如果需要内容也水平居中,请自行为其添加 CSS 样式。

TIP

Dialog 的内容是懒渲染的——在被第一次打开之前,传入的默认 slot 不会被立即渲染到 DOM 上。 因此,如果需要执行 DOM 操作,或通过 ref 获取相应组件,请在 open 事件回调中进行。

居中对话框

从屏幕中心打开对话框。

设置 align-centertrue 使对话框水平垂直居中。 由于对话框垂直居中在弹性盒子中,所以top属性将不起作用。

关闭时销毁

启用此功能时,默认栏位下的内容将使用 v-if 指令销毁。 当出现性能问题时,可以启用此功能。

需要注意的是,当这个属性被启用时,在 transition.beforeEnter 事件卸载前,除了 overlayheader (可选)footer(可选) ,Dialog 内不会有其它任何其它的 DOM 节点存在。

可拖拽对话框

试着拖动一下header部分吧

设置draggable属性为true以做到拖拽 设置 overflow 2.5.4true 可以让拖拽范围超出可视区。

TIP

modal 的值为 false 时,请一定要确保 append-to-body 属性为 true,由于 Dialog 使用 position: relative 定位,当外层的遮罩层被移除时,Dialog 则会根据当前 DOM 上的祖先节点来定位,因此可能造成定位问题。

API

Attributes

属性名说明类型默认
model-value / v-model是否显示 Dialogboolean
titleDialog 对话框 Dialog 的标题, 也可通过具名 slot (见下表)传入string''
width对话框的宽度,默认值为 50%string / number''
fullscreen是否为全屏 Dialogbooleanfalse
topdialog CSS 中的 margin-top 值,默认为 15vhstring''
modal是否需要遮罩层booleantrue
modal-class遮罩的自定义类名string
append-to-bodyDialog 自身是否插入至 body 元素上。 嵌套的 Dialog 必须指定该属性并赋值为 truebooleanfalse
append-to 2.4.3Dialog 挂载到哪个 DOM 元素 将覆盖 append-to-bodystring / HTMLElementbody
lock-scroll是否在 Dialog 出现时将 body 滚动锁定booleantrue
open-delaydialog 打开的延时时间,单位毫秒number0
close-delaydialog 关闭的延时时间,单位毫秒number0
close-on-click-modal是否可以通过点击 modal 关闭 Dialogbooleantrue
close-on-press-escape是否可以通过按下 ESC 关闭 Dialogbooleantrue
show-close是否显示关闭按钮booleantrue
before-close关闭前的回调,会暂停 Dialog 的关闭. 回调函数内执行 done 参数方法的时候才是真正关闭对话框的时候.Function
draggable为 Dialog 启用可拖拽功能booleanfalse
overflow 2.5.4拖动范围可以超出可视区booleanfalse
center是否让 Dialog 的 header 和 footer 部分居中排列booleanfalse
align-center 2.2.16是否水平垂直对齐对话框booleanfalse
destroy-on-close当关闭 Dialog 时,销毁其中的元素booleanfalse
close-icon自定义关闭图标,默认 Closestring / Component
z-index和原生的 CSS 的 z-index 相同,改变 z 轴的顺序number
header-aria-level a11yheader 的 aria-level 属性string2
custom-class deprecatedDialog 的自定义类名string''

WARNING

custom-class 已被 弃用, 之后将会在 2.4.0 移除, 请使用 class.

Slots

插槽名说明
Dialog 的内容
header对话框标题的内容;会替换标题部分,但不会移除关闭按钮。
footerDialog 按钮操作区的内容
title deprecated与 header 作用相同 请使用 header

WARNING

title 已被 弃用将会于 2.4.0 移除, 请使用 header

Events

事件名说明Type
openDialog 打开的回调Function
openedDialog 打开动画结束时的回调Function
closeDialog 关闭的回调Function
closedDialog 关闭动画结束时的回调Function
open-auto-focus输入焦点聚焦在 Dialog 内容时的回调Function
close-auto-focus输入焦点从 Dialog 内容失焦时的回调Function

Exposes

名称详情类型
resetPosition 2.8.1重置位置Function

FAQ

在 SFC 文件中使用对话框,scope 样式不会生效。

典型议题:#10515

PS:既然对话框是使用 Teleport 渲染的,建议在全局范围写入根节点的样式。

当对话框被显示及隐藏时,页面元素会来回移动(抖动)。

典型议题:#10481

PS:建议将滚动区域放置在一个挂载的 vue 节点,如 <div id="app" /> 下,并对 body 使用 overflow: hidden 样式。

源代码

组件样式文档

贡献者