MessageBox 消息弹框

模拟系统的消息提示框而实现的一套模态对话框组件,用于消息提示、确认消息和提交内容。

TIP

从设计上来说,MessageBox 的作用是美化系统自带的 alertconfirmprompt,因此适合展示较为简单的内容。 如果需要弹出较为复杂的内容,请使用 Dialog。

消息提示

当用户进行操作时会被触发,该对话框中断用户操作,直到用户确认知晓后才可关闭。

确认消息

提示用户确认其已经触发的动作,并询问是否进行此操作时会用到此对话框。

提交内容

当需要用户输入内容时,可以使用 Prompt 类型的消息框。

个性化设置你的弹框

消息弹框可以被定制来展示各种内容。

TIP

弹出层的内容可以是 VNode,所以我们能把一些自定义组件传入其中。 每次弹出层打开后,Vue 会对新老 VNode 节点进行比对,然后将根据比较结果进行最小单位地修改视图。这也许会造成弹出层内容区域的组件没有重新渲染,例如 (#8931)。 当这类问题出现时,解决方案是给 VNode 加上一个不相同的 key,参考 这里

使用 HTML 片段

message 支持传入 HTML 片段来作为展示内容。

WARNING

message 属性虽然支持传入 HTML 片段,但是在网站上动态渲染任意 HTML 是非常危险的,因为容易导致 XSS 攻击。 因此在 dangerouslyUseHTMLString 打开的情况下,请确保 message 的内容是可信的,永远不要将用户提交的内容赋值给 message 属性。

区分取消操作与关闭操作

有些场景下,点击取消按钮与点击关闭按钮有着不同的含义。

居中布局

消息弹框支持使用居中布局。

自定义图标

图标可以使用任意Vue 组件或 渲染函数 (JSX)来自定义。

可拖动

设置 MessageBox 可以拖拽。

全局方法

如果你完整引入了 Element,它会为 app.config.globalProperties 添加如下全局方法:$msgbox$alert$confirm$prompt。 因此在 Vue instance 中可以采用本页面中的方式调用 MessageBox。 调用参数为:

  • $msgbox(options)
  • $alert(message, title, options)$alert(message, options)
  • $confirm(message, title, options)$confirm(message, options)
  • $prompt(message, title, options)$prompt(message, options)

应用程序上下文继承 > 2.0.4

现在 MessageBox 接受构造器的 context 作为第二个(如果你正在使用消息框变量的话) 参数,这个参数允许你将当前应用的上下文注入到消息中,这将允许你继承应用程序的所有属性。

import { getCurrentInstance } from 'vue'
import { ElMessageBox } from 'element-plus'

// 在你的 setup 方法中
const { appContext } = getCurrentInstance()!
// 你可以像这样传递参数:
ElMessageBox({}, appContext)
// 或者正在使用不同的调用方式
ElMessageBox.alert('Hello world!', 'Title', {}, appContext)

按需引入

如果你需要按需引入 MessageBox,那你可以像示例代码这样来引入。

import { ElMessageBox } from 'element-plus'

那么对应于上述四个全局方法的调用方法依次为:ElMessageBox, ElMessageBox.alert, ElMessageBox.confirmElMessageBox.prompt. The parameters are the same as above.

配置项

属性说明类型可选值默认值
autofocus打开 MessageBox 时是否自动获得焦点booleantrue
titleMessageBox 的标题string
messageMessageBox 的正文内容string
dangerouslyUseHTMLString是否将 message 作为 HTML 片段处理booleanfalse
type消息类型,用于图标显示stringsuccess / info / warning / error
icon自定义图标组件,会覆盖 type 的类型string / Component
custom-classMessageBox 的自定义类名string
custom-styleMessageBox 的自定义内联样式CSSProperties
callback若不使用 Promise,可以使用此参数指定 MessageBox 关闭后的回调function(action, instance),action 的值为'confirm', 'cancel'或'close', instance 为 MessageBox 实例, 可以通过它访问实例上的属性和方法
show-closeMessageBox 是否显示右上角关闭按钮booleantrue
before-closemessageBox 关闭前的回调,会暂停消息弹出框的关闭过程。function(action, instance, done),action的值为'confirm', 'cancel'或'close';instance为 MessageBox 实例,可以通过它访问实例上的属性和方法;done用于关闭 MessageBox 实例
distinguish-cancel-and-close是否将取消(点击取消按钮)与关闭(点击关闭按钮或遮罩层、按下 Esc 键)进行区分booleanfalse
lock-scroll是否在 MessageBox 出现时将 body 滚动锁定booleantrue
show-cancel-button是否显示取消按钮booleanfalse(以 confirm 和 prompt 方式调用时为 true)
show-confirm-button是否显示确定按钮booleantrue
cancel-button-text取消按钮的文本内容stringCancel
confirm-button-text确定按钮的文本内容stringOK
cancel-button-class取消按钮的自定义类名string
confirm-button-class确定按钮的自定义类名string
close-on-click-modal是否可通过点击遮罩层关闭 MessageBoxbooleantrue(以 alert 方式调用时为 false)
close-on-press-escape是否可通过按下 ESC 键关闭 MessageBoxbooleantrue(以 alert 方式调用时为 false)
close-on-hash-change是否在 hash 改变时关闭 MessageBoxbooleantrue
show-input是否显示输入框booleanfalse(以 prompt 方式调用时为 true)
input-placeholder输入框占位文本string
input-type输入框的类型stringtext
input-value输入框的初始文本string
input-pattern输入框的校验表达式regexp
input-validator输入框的校验函数。 应该返回一个 boolean 或者 string, 如果返回的是一个 string 类型,那么该返回值会被赋值给 inputErrorMessage 用于向用户展示错误消息。function
input-error-message校验未通过时的提示文本stringIllegal input
center是否居中布局booleanfalse
draggableMessageBox 是否可拖放booleanfalse
round-button是否使用圆角按钮booleanfalse
button-size自定义确认按钮及取消按钮的大小stringsmall / default / largedefault

源代码

组件文档

贡献者