Dialog 对话框

在保留当前页面状态的情况下告知用户。

基础用法

Dialog 弹出一个对话框，适合需要定制化的场景。

通过设置 model-value / v-model 属性为 Boolean 来控制 Dialog 的显示与隐藏。 Dialog 分为 body 和 footer 两部分，后者需要一个名为 footer 的 slot。 title 属性用于定义标题，它是可选的，默认值为空。最后，本例还展示了 before-close 的用法。

提示

before-close 仅当用户通过点击关闭图标或遮罩层关闭 Dialog 时起作用。如果你在 footer 具名插槽中有关闭 Dialog 的按钮，你可以直接在按钮的点击事件处理器中添加 before-close 中的操作。

自定义内容

Dialog 的内容可以是任何东西，甚至是一个表格或表单。本例展示了如何在 Dialog 中使用 Element Plus 的 Table 和 Form 组件。

vue

<template>
  <div class="flex flex-wrap gap-1">
    <el-button class="!ml-0" plain @click="dialogTableVisible = true">
      Open a Table nested Dialog
    </el-button>

    <el-button class="!ml-0" plain @click="dialogFormVisible = true">
      Open a Form nested Dialog
    </el-button>
  </div>

  <el-dialog v-model="dialogTableVisible" title="Shipping address" width="800">
    <el-table :data="gridData">
      <el-table-column property="date" label="Date" width="150" />
      <el-table-column property="name" label="Name" width="200" />
      <el-table-column property="address" label="Address" />
    </el-table>
  </el-dialog>

  <el-dialog v-model="dialogFormVisible" title="Shipping address" width="500">
    <el-form :model="form">
      <el-form-item label="Promotion name" :label-width="formLabelWidth">
        <el-input v-model="form.name" autocomplete="off" />
      </el-form-item>
      <el-form-item label="Zones" :label-width="formLabelWidth">
        <el-select v-model="form.region" placeholder="Please select a zone">
          <el-option label="Zone No.1" value="shanghai" />
          <el-option label="Zone No.2" value="beijing" />
        </el-select>
      </el-form-item>
    </el-form>
    <template #footer>
      <div class="dialog-footer">
        <el-button @click="dialogFormVisible = false">Cancel</el-button>
        <el-button type="primary" @click="dialogFormVisible = false">
          Confirm
        </el-button>
      </div>
    </template>
  </el-dialog>
</template>

<script lang="ts" setup>
import { reactive, ref } from 'vue'

const dialogTableVisible = ref(false)
const dialogFormVisible = ref(false)
const formLabelWidth = '140px'

const form = reactive({
  name: '',
  region: '',
  date1: '',
  date2: '',
  delivery: false,
  type: [],
  resource: '',
  desc: '',
})

const gridData = [
  {
    date: '2016-05-02',
    name: 'John Smith',
    address: 'No.1518,  Jinshajiang Road, Putuo District',
  },
  {
    date: '2016-05-04',
    name: 'John Smith',
    address: 'No.1518,  Jinshajiang Road, Putuo District',
  },
  {
    date: '2016-05-01',
    name: 'John Smith',
    address: 'No.1518,  Jinshajiang Road, Putuo District',
  },
  {
    date: '2016-05-03',
    name: 'John Smith',
    address: 'No.1518,  Jinshajiang Road, Putuo District',
  },
]
</script>

自定义页眉

header 插槽可用于自定义显示标题的区域。为了维护可访问性，除了使用此插槽外，请使用 title 属性，或者使用 titleId 插槽属性来指定哪个元素应被读取为对话框标题。

嵌套对话框

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

通常我们不建议使用嵌套对话框。如果你需要在页面上渲染多个对话框，你可以简单地将它们平级放置。如果你必须在一个对话框内嵌套另一个对话框，请将嵌套对话框的 append-to-body 设置为 true，它将追加到 body 而不是其父节点，这样两个对话框都能被正确渲染。

内容居中

Dialog 的内容可以水平居中。

将 center 设置为 true 将使对话框的页眉和页脚水平居中。 center 仅影响 Dialog 的页眉和页脚。 Dialog 的主体内容可以是任何东西，因此有时居中可能看起来并不好。如果你也希望主体内容居中，则需要编写一些 CSS。

提示

Dialog 的内容是懒渲染的，这意味着默认插槽直到第一次打开时才会渲染到 DOM 中。因此，如果你需要执行 DOM 操作或使用 ref 访问组件，请在 open 事件回调中进行。

垂直居中对话框

从屏幕中央打开对话框。

将 align-center 设置为 true 将使对话框在水平和垂直方向上都居中。属性 top 将不再起作用，因为对话框是在 flex 容器中垂直居中的。

关闭时销毁

开启此功能时，默认插槽下的内容将通过 v-if 指令销毁。当你有性能方面的考量时可以开启此功能。

注意，启用此功能后，在 transition.beforeEnter 触发之前内容不会渲染，届时只会存在 overlay、header（如果有） 和 footer（如果有）。

可拖拽对话框

试着拖拽 header 部分。

设置 draggable 为 true 即可拖拽。设置 overflow 2.5.4 为 true 可以拖拽出视口之外。

vue

<template>
  <div class="flex flex-wrap gap-1">
    <el-button class="!ml-0" plain @click="dialogVisible = true">
      Open a draggable Dialog
    </el-button>
    <el-button class="!ml-0" plain @click="dialogOverflowVisible = true">
      Open a overflow draggable Dialog
    </el-button>
    <el-button class="!ml-0" plain @click="customDraggingVisible = true">
      Open a custom dragging style Dialog
    </el-button>
  </div>

  <el-dialog v-model="dialogVisible" title="Tips" width="500" draggable>
    <span>It's a draggable Dialog</span>
    <template #footer>
      <div class="dialog-footer">
        <el-button @click="dialogVisible = false">Cancel</el-button>
        <el-button type="primary" @click="dialogVisible = false">
          Confirm
        </el-button>
      </div>
    </template>
  </el-dialog>

  <el-dialog
    v-model="dialogOverflowVisible"
    title="Tips"
    width="500"
    draggable
    overflow
  >
    <span>It's a overflow draggable Dialog</span>
    <template #footer>
      <div class="dialog-footer">
        <el-button @click="dialogOverflowVisible = false">Cancel</el-button>
        <el-button type="primary" @click="dialogOverflowVisible = false">
          Confirm
        </el-button>
      </div>
    </template>
  </el-dialog>

  <el-dialog
    v-model="customDraggingVisible"
    class="custom-dragging-style"
    title="Custom Dragging Style"
    width="500"
    draggable
  >
    <span
      >This dialog has custom dragging styles. Try dragging it to see the
      effects!</span
    >
    <template #footer>
      <div class="dialog-footer">
        <el-button @click="customDraggingVisible = false">Cancel</el-button>
        <el-button type="primary" @click="customDraggingVisible = false">
          Confirm
        </el-button>
      </div>
    </template>
  </el-dialog>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const dialogVisible = ref(false)
const dialogOverflowVisible = ref(false)
const customDraggingVisible = ref(false)
</script>

<style scoped>
:global(.custom-dragging-style.is-dragging) {
  border: 2px dashed var(--el-color-primary);
  opacity: 0.65;
}
</style>

提示

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

全屏

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

提示

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

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

从版本 2.10.5 开始，添加了 modal-penetrable 属性，可以设置遮罩层可穿透。

自定义动画 2.10.5

通过 transition 属性自定义对话框动画，该属性接受以下两种形式：

过渡动画名称 (string)
Vue 过渡动画配置 (object)

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

vue

<template>
  <div>
    <el-button plain @click="openDialog('fade')"> Default </el-button>
    <el-button plain @click="openDialog('scale')"> Scale </el-button>
    <el-button plain @click="openDialog('slide')"> Slide </el-button>
    <el-button plain @click="openDialog('bounce')"> Bounce </el-button>
    <el-button plain @click="openDialogWithObject"> Object Config </el-button>
  </div>

  <el-dialog
    v-model="dialogVisible"
    class="custom-transition-dialog"
    :title="`${currentAnimation} Animation Dialog`"
    width="30%"
    :transition="transitionConfig"
  >
    <div>
      <p>
        Current animation: <strong>{{ currentAnimation }}</strong>
      </p>
      <p>
        This dialog demonstrates the {{ currentAnimation }} animation effect.
      </p>
      <p v-if="isObjectConfig">
        <strong>Using object configuration:</strong><br />
        <code>{{ JSON.stringify(transitionConfig, null, 2) }}</code>
      </p>
    </div>
    <template #footer>
      <el-button @click="dialogVisible = false">Cancel</el-button>
      <el-button type="primary" @click="dialogVisible = false">
        Confirm
      </el-button>
    </template>
  </el-dialog>
</template>

<script lang="ts" setup>
import { computed, ref } from 'vue'

import type { DialogTransition } from 'element-plus'

const dialogVisible = ref(false)
const currentAnimation = ref('fade')
const isObjectConfig = ref(false)

const transitionConfig = computed<DialogTransition>(() => {
  if (isObjectConfig.value) {
    return {
      name: 'dialog-custom-object',
      appear: true,
      mode: 'out-in',
      duration: 500,
    }
  }
  return `dialog-${currentAnimation.value}`
})

const openDialog = (type: string) => {
  currentAnimation.value = type
  isObjectConfig.value = false
  dialogVisible.value = true
}

const openDialogWithObject = () => {
  currentAnimation.value = 'object-config'
  isObjectConfig.value = true
  dialogVisible.value = true
}
</script>

<style scoped>
code {
  background: var(--el-bg-color-page);
  padding: 4px 8px;
  border-radius: 4px;
  font-size: 12px;
  display: block;
  margin-top: 8px;
}
</style>

<style>
/* Scale Animation */
.dialog-scale-enter-active,
.dialog-scale-leave-active,
.dialog-scale-enter-active .el-dialog,
.dialog-scale-leave-active .el-dialog {
  transition: all 0.2s cubic-bezier(0.645, 0.045, 0.355, 1);
}

.dialog-scale-enter-from,
.dialog-scale-leave-to {
  opacity: 0;
}

.dialog-scale-enter-from .el-dialog,
.dialog-scale-leave-to .el-dialog {
  transform: scale(0.5);
  opacity: 0;
}

/* Slide Animation */
.dialog-slide-enter-active,
.dialog-slide-leave-active,
.dialog-slide-enter-active .el-dialog,
.dialog-slide-leave-active .el-dialog {
  transition: all 0.3s cubic-bezier(0.25, 0.46, 0.45, 0.94);
}

.dialog-slide-enter-from,
.dialog-slide-leave-to {
  opacity: 0;
}

.dialog-slide-enter-from .el-dialog,
.dialog-slide-leave-to .el-dialog {
  transform: translateY(-100px);
  opacity: 0;
}

/* Bounce Animation */
.dialog-bounce-enter-active,
.dialog-bounce-leave-active,
.dialog-bounce-enter-active .el-dialog,
.dialog-bounce-leave-active .el-dialog {
  transition: all 0.5s cubic-bezier(0.175, 0.885, 0.32, 1.275);
}

.dialog-bounce-enter-from,
.dialog-bounce-leave-to {
  opacity: 0;
}

.dialog-bounce-enter-from .el-dialog,
.dialog-bounce-leave-to .el-dialog {
  transform: scale(0.3) translateY(-50px);
  opacity: 0;
}

/* Object Configuration Animation */
.dialog-custom-object-enter-active,
.dialog-custom-object-leave-active,
.dialog-custom-object-enter-active .el-dialog,
.dialog-custom-object-leave-active .el-dialog {
  transition: all 0.5s cubic-bezier(0.25, 0.8, 0.25, 1);
}

.dialog-custom-object-enter-from,
.dialog-custom-object-leave-to {
  opacity: 0;
}

.dialog-custom-object-enter-from .el-dialog,
.dialog-custom-object-leave-to .el-dialog {
  transform: rotate(180deg) scale(0.5);
  opacity: 0;
}
</style>

提示

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

事件

打开开发者控制台 (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
遮罩层可穿透 2.10.5	遮罩层是否可穿透。 modal 属性必须为 `false`。	`boolean`	false
遮罩层类名	遮罩层的自定义类名	`string`	—
页眉类名 2.9.3	页眉容器的自定义类名	`string`	—
主体类名 2.9.3	主体容器的自定义类名	`string`	—
页脚类名 2.9.3	页脚容器的自定义类名	`string`	—
插入至 body	是否将 Dialog 自身追加到 body。嵌套对话框应将此属性设置为 `true`	`boolean`	false
追加至 2.4.3	Dialog 追加到的元素。将覆盖 `append-to-body`	`CSSSelector` / `HTMLElement`	body
锁定滚动	当 Dialog 显示时是否禁用 body 滚动	`boolean`	true
打开延迟	打开前的延迟时间（毫秒）	`number`	0
关闭延迟	关闭前的延迟时间（毫秒）	`number`	0
点击遮罩层关闭	是否可以通过点击遮罩层来关闭 Dialog	`boolean`	true
close-on-press-escape	是否可以通过按下 ESC 键来关闭 Dialog	`boolean`	true
show-close	是否显示关闭按钮	`boolean`	true
关闭前回调	Dialog 关闭前的回调，会阻止 Dialog 关闭。使用 done 来关闭对话框	`Function`	—
draggable	为 Dialog 启用可拖拽功能	`boolean`	false
溢出视口 2.5.4	可拖拽的 Dialog 是否可以超出视口	`boolean`	false
居中	是否将页眉和页脚居中对齐	`boolean`	false
垂直居中 2.2.16	对话框是否水平和垂直对齐	`boolean`	false
关闭时销毁	当关闭时销毁 Dialog 中的元素	`boolean`	false
关闭图标	自定义关闭图标，默认为 Close	`string` / `Component`	—
z-index	同原生 CSS 中的 z-index，设置对话框的堆叠顺序	`number`	—
页眉 ARIA 级别 a11y	页眉的 `aria-level` 属性	`string`	2
过渡动画 2.10.5	对话框动画的自定义过渡配置。可以是一个字符串 (过渡名称) 或一个带有 Vue 过渡 props 的对象	`string` / `object`	对话框渐变 (dialog-fade)
自定义类名已弃用	Dialog 的自定义类名	`string`	''

警告

custom-class 已被弃用，并将于 2.4.0 版本中移除，请使用 class。

插槽

名称	描述
default	Dialog 的默认内容
header	Dialog 页眉的内容；替换此插槽会移除标题，但不会移除关闭按钮。
footer	Dialog 页脚的内容
标题已弃用	与 header 插槽效果相同。请改用插槽。

警告

title 已被弃用，并将于 3.0.0 版本中移除，请使用 header。

事件

名称	描述	类型
open	Dialog 打开时触发	`Function`
已打开	Dialog 打开动画结束时触发	`Function`
关闭	Dialog 关闭时触发	`Function`
已关闭	Dialog 关闭动画结束时触发	`Function`
打开后自动聚焦	Dialog 打开且内容获得焦点后触发	`Function`
关闭后自动聚焦	Dialog 关闭且内容获得焦点后触发	`Function`