对话框

通知用户，同时保留当前页面状态。

基本用法

Dialog 弹出一个对话框，而且可定制性很强。

使用 Boolean 设置 model-value / v-model 属性，当它是 true 时，对话框会显示。该对话框有两部分：body 和 footer，后者需要一个名为 footer 的 slot。可选的 title 属性（默认为空）用于定义标题。最后，本示例演示了 before-close 的使用方法。

TIP

before-close 仅当用户单击关闭图标或背景时才起作用。如果您有在 footer 命名槽中关闭对话框的按钮，则可以在按钮的单击事件处理程序中添加对 before-close 执行的操作。

定制内容

Dialog 的内容可以是任何内容，甚至是表格或表单。此示例演示如何将 Element Plus Table 和 Form 与 Dialog 结合使用。

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 槽属性来指定应将哪个元素作为对话框标题读出。

嵌套对话框

如果一个对话框嵌套在另一个对话框中，则需要 append-to-body。

通常我们不建议使用嵌套对话框。如果您需要在页面上呈现多个对话框，您可以简单地将它们展平，使它们彼此成为同级对话框。如果必须将一个Dialog嵌套在另一个Dialog中，请将嵌套Dialog的append-to-body设置为true，它将附加到body而不是其父节点，因此两个Dialog都可以正确渲染。

内容居中

对话框的内容可以居中。

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

TIP

Dialog 的内容是延迟渲染的，这意味着默认槽在首次打开之前不会渲染到 DOM 上。因此，如果您需要执行 DOM 操作或使用 ref 访问组件，请在 open 事件回调中执行。

居中对齐对话框

从屏幕中央打开对话框。

将 align-center 设置为 true 将使对话框水平和垂直居中。属性 top 不会同时工作，因为对话框在 Flexbox 中垂直居中。

关闭时销毁

启用此功能后，默认插槽下的内容将被 v-if 指令销毁。当您有性能问题时启用此功能。

请注意，启用此功能后，在发送 transition.beforeEnter 之前不会渲染内容，只会有 overlay header(if any) footer(if any)。

可拖动对话框

尝试拖动 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>

TIP

当使用modal = false时，请确保append-to-body设置为true，因为Dialog是由position: relative定位的，当modal被删除时，Dialog将根据DOM中的当前位置定位自己，而不是Document.Body，这样样式就会乱了。

全屏

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

TIP

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

模态

将 modal 设置为 false 将隐藏对话框的模态（覆盖）。

从版本2.10.5开始，增加modal-penetrable属性，可穿透。

自定义动画 2.10.5

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

转换名称（字符串）
Vue过渡配置（对象）

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

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-mobile'

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>

TIP

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

活动

打开开发人员控制台（ctrl + shift + J），查看事件顺序。

API

属性

名称	描述	类型	默认
模型值 / v 模型	对话框的可见性	`布尔值`	假
标题	对话框的标题。也可以通过命名槽来传递（见下表）	`字符串`	''
宽度	Dialog 的宽度，默认为 50%	`字符串` / `数字`	''
全屏	Dialog是否占据全屏	`布尔值`	假
顶部	Dialog CSS 的 `margin-top` 的值，默认为 15vh	`字符串`	''
莫代尔	是否显示遮罩	`布尔值`	真实
模态可穿透 2.10.5	面罩是否具有穿透性。模态属性必须是 `false`。	`布尔值`	假
模态类	掩码的自定义类名	`字符串`	—
标头类 2.9.3	标头包装器的自定义类名	`字符串`	—
身体等级 2.9.3	正文包装的自定义类名	`字符串`	—
页脚类 2.9.3	页脚包装的自定义类名	`字符串`	—
附加到正文	是否将 Dialog 本身附加到 body。嵌套对话框应将此属性设置为 `true`	`布尔值`	假
追加到 2.4.3	对话框附加到哪个元素。将覆盖 `append-to-body`	`CSS选择器` / `HTMLElement`	身体
锁定滚动	显示Dialog时是否禁用body滚动	`布尔值`	真实
打开延迟	打开前的时间（毫秒）	`数字`	0
关闭延迟	关闭前的时间（毫秒）	`数字`	0
点击关闭模式	是否可以通过单击蒙版	来关闭对话框`布尔值`	真实
关闭新闻转义	是否可以通过按 ESC	关闭对话框`布尔值`	真实
显示关闭	是否显示关闭按钮	`布尔值`	真实
收盘前	在Dialog关闭之前回调，它会阻止Dialog关闭，使用done关闭对话框	`功能`	—
可拖动	启用对话框的拖动功能	`布尔值`	假
溢出 2.5.4	可拖动对话框可以溢出视口	`布尔值`	假
中心	是否居中对齐页眉和页脚	`布尔值`	假
居中对齐 2.2.16	是否水平和垂直对齐对话框	`布尔值`	假
关闭时销毁	关闭时销毁对话框中的元素	`布尔值`	假
关闭图标	自定义关闭图标，默认为关闭	`字符串` / `组件`	—
z 索引	与原生 CSS 中的 z-index 相同，对话框的 z-order	`数字`	—
标头 aria 级别 a11y	标头的 `aria-level` 属性	`字符串`	2
过渡 2.10.5	对话框动画的自定义转换配置。可以是字符串（过渡名称）或带有 Vue 过渡道具的对象	`字符串` / `对象`	对话框淡入淡出
自定义类 ^（已弃用）	对话框的自定义类名	`字符串`	''

WARNING

custom-class 已弃用，并且将在 2.4.0 中删除，请使用 class。

老虎机

名称	描述
默认	对话框的默认内容
标题	对话框标题的内容；替换它会删除标题，但不会删除关闭按钮。
页脚	对话框页脚的内容
标题 ^（已弃用）	与标头插槽的工作方式相同。用它来代替。

WARNING

title 已弃用，并且将在 3.0.0 中删除，请使用 header。

活动

名称	描述	类型
打开	对话框打开时触发	`功能`
打开	Dialog 打开动画结束时触发	`功能`
关闭	对话框关闭时触发	`功能`
关闭	当对话框关闭动画结束时触发	`功能`
打开自动对焦	对话框打开且内容聚焦后触发	`功能`
近距离自动对焦	对话框关闭且内容聚焦后触发	`功能`

暴露

名称	描述	类型
重置位置 2.8.1	重置位置	`功能`
处理关闭 2.9.8	关闭对话框	`功能`

常见问题解答

####在SFC中使用对话框，范围样式不生效

典型问题：#10515

PS：由于对话框是使用Teleport渲染的，所以根节点的样式建议全局写入。

####当对话框显示和隐藏时，存在页面元素来回移位的情况

典型问题：#10481

PS：建议将滚动区域放置在 vue 安装的节点内，例如<div id="app" />，本体使用overflow: hidden样式。

Alert 警告

Drawer 抽屉

对话框 ​

基本用法 ​

定制内容 ​

自定义标题 ​

嵌套对话框 ​

内容居中 ​

居中对齐对话框 ​

关闭时销毁 ​

可拖动对话框 ​

全屏 ​

模态 ​

自定义动画 2.10.5 ​

活动 ​

API ​

属性 ​

老虎机 ​