Dialog 对话框

基于 Element Plus Dialog 增强的对话框组件。

在保留当前页面状态的同时向用户传达信息。

基础用法

Dialog 会弹出一个对话框，并且具有高度的可定制性。

通过设置布尔类型的 model-value / v-model 属性来控制 Dialog 的显示与隐藏。Dialog 分为 body 和 footer 两部分，其中 footer 需要使用名为 footer 的具名插槽。可选的 title 属性（默认为空）用于定义标题。本示例还展示了如何使用 before-close。

<template>
  <bk-button plain @click="dialogVisible = true"> Click to open the Dialog </bk-button>

  <bk-dialog
    v-model="dialogVisible"
    title="Tips"
    width="500"
    :before-close="handleClose"
    class="el-dialog-fade"
  >
    <span>This is a message</span>
    <template #footer>
      <div class="dialog-footer">
        <bk-button @click="dialogVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="dialogVisible = false"> Confirm </bk-button>
      </div>
    </template>
  </bk-dialog>
</template>

<script lang="ts" setup>
import { ref } from "vue"
import { ElMessageBox } from "vue-business-kit"

const dialogVisible = ref(false)

const handleClose = (done: () => void) => {
  ElMessageBox.confirm("Are you sure to close this dialog?")
    .then(() => {
      done()
    })
    .catch(() => {
      // catch error
    })
}
</script>

隐藏源码

TIP

before-close 仅在用户点击关闭图标或遮罩层时生效。如果你在 footer 插槽中放置了用于关闭 Dialog 的按钮，则应在按钮的点击事件处理函数中自行实现 before-close 中的逻辑。

自定义内容

Dialog 的内容可以是任意内容，甚至是一张表格或一个表单。以下示例展示了如何在 Dialog 中结合使用 Table 和 Form 组件。

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

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

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

  <bk-dialog v-model="dialogFormVisible" title="Shipping address" width="500">
    <bk-form :model="form">
      <bk-form-item label="Promotion name" :label-width="formLabelWidth">
        <el-input v-model="form.name" autocomplete="off" />
      </bk-form-item>
      <bk-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>
      </bk-form-item>
    </bk-form>
    <template #footer>
      <div class="dialog-footer">
        <bk-button @click="dialogFormVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="dialogFormVisible = false"> Confirm </bk-button>
      </div>
    </template>
  </bk-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 插槽来自定义标题区域。为了保证无障碍访问（accessibility），建议同时使用 title 属性，或者通过 titleId 插槽属性指定哪个元素应被读作对话框的标题。

<template>
  <bk-button plain @click="visible = true"> Open Dialog with customized header </bk-button>

  <bk-dialog v-model="visible" :show-close="false" width="500">
    <template #header="{ close, titleId, titleClass }">
      <div class="my-header">
        <h4 :id="titleId" :class="titleClass">This is a custom header!</h4>
        <bk-button type="danger" @click="close">
          <bk-icon class="el-icon--left" icon="tabler:circle-x-filled"></bk-icon>
          Close
        </bk-button>
      </div>
    </template>
    This is dialog content.
  </bk-dialog>
</template>

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

const visible = ref(false)
</script>

<style scoped>
.my-header {
  display: flex;
  flex-direction: row;
  justify-content: space-between;
  gap: 16px;
}
</style>

隐藏源码

嵌套 Dialog

如果一个 Dialog 被嵌套在另一个 Dialog 内部，则必须设置 append-to-body。

通常我们不推荐使用嵌套的 Dialog。如果你需要在页面上渲染多个 Dialog，建议将它们平级放置。如果确实需要嵌套，请将内层 Dialog 的 append-to-body 设置为 true，这样它会被挂载到 body 下而非其父节点下，从而确保两个 Dialog 都能正确渲染。

<template>
  <bk-button plain @click="outerVisible = true"> Open the outer Dialog </bk-button>

  <bk-dialog v-model="outerVisible" title="Outer Dialog" width="800">
    <span>This is the outer Dialog</span>
    <bk-dialog v-model="innerVisible" width="500" title="Inner Dialog" append-to-body>
      <span>This is the inner Dialog</span>
    </bk-dialog>
    <template #footer>
      <div class="dialog-footer">
        <bk-button @click="outerVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="innerVisible = true"> Open the inner Dialog </bk-button>
      </div>
    </template>
  </bk-dialog>
</template>

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

const outerVisible = ref(false)
const innerVisible = ref(false)
</script>

隐藏源码

居中对齐内容

Dialog 的内容可以水平居中。

将 center 设置为 true 可使 Dialog 的 header 和 footer 水平居中。注意：center 仅影响 Dialog 的 header 和 footer。Dialog 的 body 可以是任意内容，因此有时居中效果可能不理想，此时你需要额外编写 CSS 来居中 body 内容。

<template>
  <bk-button plain @click="centerDialogVisible = true"> Click to open the Dialog </bk-button>

  <bk-dialog v-model="centerDialogVisible" title="Warning" width="500" center>
    <span> It should be noted that the content will not be aligned in center by default </span>
    <template #footer>
      <div class="dialog-footer">
        <bk-button @click="centerDialogVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="centerDialogVisible = false"> Confirm </bk-button>
      </div>
    </template>
  </bk-dialog>
</template>

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

const centerDialogVisible = ref(false)
</script>

隐藏源码

TIP

Dialog 的内容采用懒加载方式渲染，即默认插槽的内容在首次打开前不会被渲染到 DOM 中。因此，如果你需要操作 DOM 或通过 ref 访问子组件，请在 open 事件回调中进行。

屏幕居中打开 Dialog

让 Dialog 从屏幕正中央弹出。

将 align-center 设置为 true 可使 Dialog 在水平和垂直方向都居中。此时 top 属性将失效，因为 Dialog 是通过 Flex 布局实现垂直居中的。

<template>
  <bk-button plain @click="centerDialogVisible = true"> Click to open the Dialog </bk-button>

  <bk-dialog v-model="centerDialogVisible" title="Warning" width="500" align-center>
    <span>Open the dialog from the center from the screen</span>
    <template #footer>
      <div class="dialog-footer">
        <bk-button @click="centerDialogVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="centerDialogVisible = false"> Confirm </bk-button>
      </div>
    </template>
  </bk-dialog>
</template>

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

const centerDialogVisible = ref(false)
</script>

隐藏源码

关闭时销毁内容

启用此功能后，默认插槽中的内容将在 Dialog 关闭时通过 v-if 指令销毁。当你有性能方面的顾虑时，可以启用此选项。

注意：启用该功能后，内容将在 transition.beforeEnter 事件触发前不会被渲染，此时 Dialog 中仅包含 overlay、header（可选）和 footer（可选）。

<template>
  <bk-button plain @click="centerDialogVisible = true"> Click to open Dialog </bk-button>

  <bk-dialog v-model="centerDialogVisible" title="Notice" width="500" destroy-on-close center>
    <span>
      Notice: before the dialog is opened for the first time, this node and the one below will not
      be rendered.
    </span>
    <div>
      <strong>Extra content (Not rendered)</strong>
    </div>
    <template #footer>
      <div class="dialog-footer">
        <bk-button @click="centerDialogVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="centerDialogVisible = false"> Confirm </bk-button>
      </div>
    </template>
  </bk-dialog>
</template>

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

const centerDialogVisible = ref(false)
</script>

隐藏源码

可拖拽 Dialog

尝试拖动 Dialog 的 header 区域。

将 draggable 设置为 true 即可启用拖拽功能。若同时设置 overflow 为 true，则允许 Dialog 拖出视口范围。

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

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

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

  <bk-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">
        <bk-button @click="customDraggingVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="customDraggingVisible = false"> Confirm </bk-button>
      </div>
    </template>
  </bk-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 属性即可开启全屏 Dialog。

<template>
  <bk-button plain @click="dialogVisible = true"> Open the fullscreen Dialog </bk-button>

  <bk-dialog v-model="dialogVisible" fullscreen>
    <span>It's a fullscreen Dialog</span>
    <template #footer>
      <div class="dialog-footer">
        <bk-button @click="dialogVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="dialogVisible = false"> Confirm </bk-button>
      </div>
    </template>
  </bk-dialog>
</template>

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

const dialogVisible = ref(false)
</script>

隐藏源码

TIP

当 fullscreen 为 true 时，width、top 和 draggable 属性将不再生效。

非模态 Dialog

将 modal 设置为 false 可隐藏 Dialog 的遮罩层（overlay）。新增的 modal-penetrable 属性可用于使遮罩层可穿透（此时 modal 必须为 false）。

<template>
  <bk-button plain @click="dialogVisible = true"> Open the modal Dialog </bk-button>

  <bk-dialog v-model="dialogVisible" :modal="false" modal-penetrable>
    <span>It's a modal Dialog</span>
    <template #footer>
      <div class="dialog-footer">
        <bk-button @click="dialogVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="dialogVisible = false"> Confirm </bk-button>
      </div>
    </template>
  </bk-dialog>
</template>

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

const dialogVisible = ref(false)
</script>

隐藏源码

自定义动画

通过 transition 属性自定义 Dialog 的动画效果。该属性接受以下两种值：

• 动画名称（字符串）
• Vue Transition 配置对象（对象）

示例包括缩放（scale）、滑动（slide）、淡入淡出（fade）、弹跳（bounce）等动画，以及使用对象配置并包含自定义事件处理器的用法。

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

  <bk-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>
      <bk-button @click="dialogVisible = false">Cancel</bk-button>
      <bk-button type="primary" @click="dialogVisible = false"> Confirm </bk-button>
    </template>
  </bk-dialog>
</template>

<script lang="ts" setup>
import { computed, ref } from "vue"
import type { DialogTransition } from "vue-business-kit"

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

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

事件顺序

打开开发者工具控制台（Ctrl + Shift + J），查看 Dialog 各事件的触发顺序。

<template>
  <bk-button plain @click="dialogVisible = true"> Open the event Dialog </bk-button>

  <bk-dialog
    v-model="dialogVisible"
    modal-class="overide-animation"
    :before-close="
      (doneFn) => {
        console.log('before-close'), doneFn()
      }
    "
    @open="console.log('open')"
    @open-auto-focus="console.log('open-auto-focus')"
    @opened="console.log('opened')"
    @close="console.log('close')"
    @close-auto-focus="console.log('close-auto-focus')"
    @closed="console.log('closed')"
  >
    <span>It's a event Dialog</span>
    <template #footer>
      <div class="dialog-footer">
        <bk-button @click="dialogVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="dialogVisible = false"> Confirm </bk-button>
      </div>
    </template>
  </bk-dialog>
</template>

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

const dialogVisible = ref(false)
</script>

隐藏源码

Dialog API

Dialog 属性

Element Plus Dialog 原生属性

属性名	说明	类型	默认值
model-value / v-model	Dialog 是否显示	boolean	false
title	Dialog 的标题，也可通过具名插槽传入	string	''
width	Dialog 的宽度，默认为 50%	string / number	''
fullscreen	是否全屏显示 Dialog	boolean	false
top	Dialog 的 margin-top 值，默认为 15vh	string	''
modal	是否显示遮罩层	boolean	true
modal-penetrable	遮罩层是否可穿透（需配合 modal=false 使用）	boolean	false
modal-class	遮罩层的自定义类名	string	—
header-class	头部容器的自定义类名	string	—
body-class	主体容器的自定义类名	string	—
footer-class	底部容器的自定义类名	string	—
append-to-body	是否将 Dialog 自身插入至 body 元素下（嵌套 Dialog 必须设为 true）	boolean	false
append-to	指定 Dialog 挂载的 HTML 元素（会覆盖 append-to-body）	CSSSelector / HTMLElement	body
lock-scroll	Dialog 显示时是否禁止 body 滚动	boolean	true
open-delay	打开 Dialog 的延迟时间（毫秒）	number	0
close-delay	关闭 Dialog 的延迟时间（毫秒）	number	0
close-on-click-modal	是否可通过点击遮罩层关闭 Dialog	boolean	true
close-on-press-escape	是否可通过按下 ESC 键关闭 Dialog	boolean	true
show-close	是否显示关闭按钮	boolean	true
before-close	Dialog 关闭前的回调函数，会阻止 Dialog 关闭，调用 done 才真正关闭	(done: DoneFn) => void	—
draggable	是否启用拖拽功能	boolean	false
overflow	拖拽时是否允许超出视口	boolean	false
center	是否使 header 和 footer 水平居中	boolean	false
align-center	是否使整个 Dialog 在屏幕中水平垂直居中	boolean	false
destroy-on-close	关闭时是否销毁 Dialog 中的元素	boolean	false
close-icon	自定义关闭图标（默认为 Close）	string / Component	—
z-index	Dialog 的 z-index 层级	number	—
header-aria-level	header 的 aria-level 属性	string	'2'
transition	Dialog 动画的自定义配置，可为字符串（过渡名）或对象（Vue Transition 配置）	string / object (TransitionProps)	'dialog-fade'

Dialog 插槽

Element Plus Dialog 原生插槽

插槽名	说明
default	Dialog 的默认内容
header	Dialog 的头部内容；替换此插槽会移除标题，但不会移除关闭按钮
footer	Dialog 的底部内容

Dialog 事件

Element Plus Dialog 原生事件

事件名	说明	回调参数
open	Dialog 打开时触发	() => void
opened	Dialog 打开动画结束后触发	() => void
close	Dialog 关闭时触发	() => void
closed	Dialog 关闭动画结束后触发	() => void
open-auto-focus	Dialog 打开并完成自动聚焦后触发	() => void
close-auto-focus	Dialog 关闭并恢复焦点后触发	() => void

Dialog Exposes

Element Plus Dialog Exposes

方法名	说明	签名
resetPosition	重置 Dialog 位置（用于可拖拽场景）	() => void
handleClose	手动关闭 Dialog	() => void

常见问题（FAQ）

在单文件组件（SFC）中使用 Dialog，scoped 样式不生效

典型问题：#10515

说明：由于 Dialog 使用 Teleport 渲染，建议将根节点的样式写在全局样式中。

Dialog 显示/隐藏时页面元素发生抖动或位移

典型问题：#10481

建议：将滚动区域限制在 Vue 挂载的节点内（例如 <div id="app" />），并对 body 设置 overflow: hidden 样式。