Dialog 对话框

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

基础用法

Dialog 弹出一个对话框,通常用于消息提示、消息确认,或在当前页面内完成特定的交互操作。 弹窗的形式有 modal 和非 modal 两种,modal 弹窗会遮罩当前页面,告知用户此弹窗的优先级是最高的,用户必须处理完弹窗的内容才能做其他事。

model-value / v-model 属性设置为一个 Boolean 类型的值,当值为 true 时,对话框会显示。 Dialog 组件的内容分为两个部分:bodyfooterfooter 部分需要一个具名为 footerslottitle 属性用于定义标题,它是可选的(默认为空)。 最终,这个例子展示了如何使用 before-close

提示

before-close 的回调函数只会在用户点击关闭图标或遮罩时触发。 如果您在 footer 插槽中添加了关闭对话框的按钮,那么您可以在按钮的点击事件中,添加与 before-close 回调函数中相同的逻辑。

自定义内容

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

自定义头部

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

嵌套的 Dialog

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

正常情况下,我们不建议使用嵌套的 Dialog。 如果您需要在页面上同时打开多个 Dialog,可以将这些 Dialog 以平级的方式放置。 如果你必须在 Dialog 中嵌套另一个 Dialog,请将内层 Dialog 的 append-to-body 属性设置为 true,它就会插入至 body 元素上,从而保证两层 Dialog 和遮罩层级关系正确。

内容居中

对话框的内容可以居中。

center 设置为 true 即可使标题和底部实现水平居中。 center 仅影响 Dialog 的 header 和 footer 部分。 Dialog 的 body 部分是自定义的,因此内容居中对 body 部分不会产生影响,您需要自己编写 css 来实现 body 部分的水平居中。

提示

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

水平垂直居中

从屏幕中心打开对话框。

align-center 属性设置为 true,Dialog 将会水平垂直居中。 因为 Dialog 是在 flexbox 中垂直居中的,所以 top 属性将不会再生效。

关闭时销毁

启用此功能后,默认插槽下的内容将通过 v-if 指令销毁。 当您有性能方面的顾虑时,请启用此功能。

请注意,启用此功能后,内容将在 transition.beforeEnter 调度之前不会被渲染,只会显示 overlay header(如果有) footer(如果有)

可拖拽的 Dialog

尝试拖动 header 部分。

draggable 设置为 true 可以拖拽。 设置 overflow 2.5.4true 可以拖拽出可视窗口。

提示

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

通过 transition 属性自定义对话框动画,该属性接受

  • 过渡名称(字符串)

  • Vue 过渡配置(对象)

示例包括缩放、滑动、淡入淡出、弹跳动画以及带有自定义事件处理程序的基于对象的配置。

提示

动画类是根据过渡名称动态生成的。 为了对动画行为进行精细控制,您可以明确定义这些类。 详情请参阅 自定义过渡类名

事件

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

API

属性

名称描述类型默认值
model-value / v-model对话框的可见性boolean
titleDialog 的标题,也可通过具名 slot (见下表)传入string''
widthDialog 的宽度,默认为 50%string / number''
是否为全屏对话框Dialog 是否占据全屏booleanfalse
Dialog CSS 中的 margin-top 值,默认为 15vhstring''
模态框是否显示遮罩层booleantrue
modal-penetrable 遮罩层是否可穿透 2.10.5遮罩层是否可穿透。 modal 属性必须是 falsebooleanfalse
遮罩层的自定义类名遮罩层的自定义类名string
header-class 2.9.3header 的自定义类名string
body-class 2.9.3body 的自定义类名string
footer-class 2.9.3footer 的自定义类名string
是否将 Dialog 自身附加到 body 元素上。 嵌套的 Dialog 必须将此属性设置为 `true`是否将 Dialog 自身附加到 body 元素上。 一个嵌套的 Dialog 必须将此属性设置为 `true`booleanfalse
append-to 2.4.3Dialog 附加到的元素。 会覆盖 `append-to-body`CSSSelector / HTMLElementbody
是否在 Dialog 出现时将 body 滚动锁定Dialog 显示时是否锁定 body 滚动booleantrue
打开延时打开前的延时时间,单位毫秒number0
关闭延时关闭前的延时时间,单位毫秒number0
是否可以通过点击 modal 关闭 Dialog是否可以通过点击遮罩关闭 Dialogbooleantrue
close-on-press-escape是否可以通过按下 ESC 关闭 Dialogbooleantrue
show-close是否显示关闭按钮booleantrue
关闭前的回调,会暂停 Dialog 的关闭,使用 done 关闭对话框关闭前的回调,会暂停 Dialog 的关闭,使用 done 关闭对话框Function
draggable为 Dialog 启用可拖拽功能booleanfalse
overflow 2.5.4可拖拽的 Dialog 可超出视口booleanfalse
居中是否让 Dialog 的 header 和 footer 部分居中排列booleanfalse
align-center 2.2.16对话框是否水平和垂直对齐booleanfalse
是否在关闭 Dialog 时销毁其中的元素关闭时销毁 Dialog 中的元素booleanfalse
自定义关闭图标自定义关闭图标,默认为 Closestring / Component
z-index与原生 CSS 中的 z-index 相同,dialog 的 z-ordernumber
header-aria-level a11yheader 的 `aria-level` 属性string2
transition 2.10.5对话框动画的自定义过渡配置。可以是一个字符串 (过渡名称) 或一个带有 Vue 过渡 props 的对象string / objectdialog-fade
custom-class 已废弃Dialog 的自定义类名string''

警告

custom-class 已被 废弃,并将在 2.4.0 版本中被 移除,请使用 class

插槽

名称描述
defaultDialog 的内容
headerDialog 标题区的内容,替换此项会移除标题,但不会移除关闭按钮。
footerDialog 按钮操作区的内容
title 已废弃与 header 插槽作用相同。 请改用 header 插槽。

警告

title 已被 废弃,并将在 2.4.0 版本中被 移除,请使用 header

事件

名称描述类型
openDialog 打开的回调Function
已打开Dialog 打开动画结束时的回调Function
关闭Dialog 关闭的回调Function
已关闭Dialog 关闭动画结束时的回调Function
打开自动聚焦Dialog 打开后内容聚焦时的回调Function
关闭自动聚焦Dialog 关闭后内容聚焦时的回调Function

暴露

名称描述类型
resetPosition 2.8.1重置位置Function
handleClose 2.9.8关闭对话框Function

常见问题

在 SFC 中使用对话框时,作用域样式不生效

典型问题:#10515

附:由于对话框是使用 Teleport 渲染的,因此根节点的样式建议全局编写。

当对话框显示和隐藏时,页面元素会出现来回移位的情况

典型问题:#10481

附:建议将滚动区域放置在 vue 挂载节点内,例如 <div id="app" />,并为 body 使用 overflow: hidden 样式。

来源

组件样式文档

贡献者