Dialog 对话框
在保留当前页面状态的情况下,告知用户并承载相关操作。
基础用法
Dialog 弹出一个对话框,通常用于消息提示、消息确认,或在当前页面内完成特定的交互操作。 弹窗的形式有 modal 和非 modal 两种,modal 弹窗会遮罩当前页面,告知用户此弹窗的优先级是最高的,用户必须处理完弹窗的内容才能做其他事。
将 model-value / v-model
属性设置为一个 Boolean
类型的值,当值为 true
时,对话框会显示。 Dialog 组件的内容分为两个部分:body
和 footer
,footer
部分需要一个具名为 footer
的 slot
。 title
属性用于定义标题,它是可选的(默认为空)。 最终,这个例子展示了如何使用 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.4 为 true
可以拖拽出可视窗口。
提示
当 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 | — |
title | Dialog 的标题,也可通过具名 slot (见下表)传入 | 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 |
遮罩层的自定义类名 | 遮罩层的自定义类名 | string | — |
header-class 2.9.3 | header 的自定义类名 | string | — |
body-class 2.9.3 | body 的自定义类名 | string | — |
footer-class 2.9.3 | footer 的自定义类名 | string | — |
是否将 Dialog 自身附加到 body 元素上。 嵌套的 Dialog 必须将此属性设置为 `true` | 是否将 Dialog 自身附加到 body 元素上。 一个嵌套的 Dialog 必须将此属性设置为 `true` | boolean | false |
append-to 2.4.3 | Dialog 附加到的元素。 会覆盖 `append-to-body` | CSSSelector / HTMLElement | body |
是否在 Dialog 出现时将 body 滚动锁定 | Dialog 显示时是否锁定 body 滚动 | boolean | true |
打开延时 | 打开前的延时时间,单位毫秒 | number | 0 |
关闭延时 | 关闭前的延时时间,单位毫秒 | number | 0 |
是否可以通过点击 modal 关闭 Dialog | 是否可以通过点击遮罩关闭 Dialog | boolean | true |
close-on-press-escape | 是否可以通过按下 ESC 关闭 Dialog | boolean | true |
show-close | 是否显示关闭按钮 | boolean | true |
关闭前的回调,会暂停 Dialog 的关闭,使用 done 关闭对话框 | 关闭前的回调,会暂停 Dialog 的关闭,使用 done 关闭对话框 | Function | — |
draggable | 为 Dialog 启用可拖拽功能 | boolean | false |
overflow 2.5.4 | 可拖拽的 Dialog 可超出视口 | boolean | false |
居中 | 是否让 Dialog 的 header 和 footer 部分居中排列 | boolean | false |
align-center 2.2.16 | 对话框是否水平和垂直对齐 | boolean | false |
是否在关闭 Dialog 时销毁其中的元素 | 关闭时销毁 Dialog 中的元素 | boolean | false |
自定义关闭图标 | 自定义关闭图标,默认为 Close | string / Component | — |
z-index | 与原生 CSS 中的 z-index 相同,dialog 的 z-order | number | — |
header-aria-level a11y | header 的 `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
已被 废弃,并将在 2.4.0 版本中被 移除,请使用 header
。
事件
名称 | 描述 | 类型 |
---|---|---|
open | Dialog 打开的回调 | 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
样式。