消息弹出框

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

提示

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

消息提示

消息提示,需要用户交互之后才会消失。

调用 ElMessageBox.alert 方法即可打开消息提示,它模拟了系统的 alert,无法通过按下 ESC 或点击框外关闭。 此例中接收了两个参数,messagetitle。 值得一提的是,窗口被关闭后,它会返回一个 Promise 对象便于进行后续操作的处理。 若不确定浏览器是否支持 Promise,可使用传统的回调函数,正如本例所示。

确认消息

确认消息,用来向用户确认操作。

调用 ElMessageBox.confirm 方法即可打开消息确认框,它模拟了系统的 confirm。 我们还可以通过第三个参数 options 为弹窗传入更多配置。 type 字段表明消息类型,可以为 primarysuccesserrorinfowarning,无效的设置将会被忽略。 注意,第二个参数 title 必须是 string 类型,如果传入 object,它会被当成 options 使用。 在这里我们用了 Promise 来处理后续响应。 primary 是在 2.9.11 中被添加的。

提交内容

提交内容,当用户输入内容时使用。

调用 ElMessageBox.prompt 方法即可打开消息提示,它模拟了系统的 prompt。 你可以使用 inputPattern 字段,用来进行自定义的正则校验。 inputValidator 用于自定义的输入校验。它应该返回一个 Boolean 或者一个 string。 返回 false 或一个 string 表明校验未通过,这个 string 的返回值将会被用作 inputErrorMessage。 此外,您可以使用 inputPlaceholder 字段来为输入框设置一个占位符。

使用 VNode

message 可以是一个 VNode。

自定义

可自定义配置,以显示不同内容。

以上三个方法都是对 ElMessageBox 方法的再包装。 本例直接调用 ElMessageBox 方法,通过设置 showCancelButton 字段,来指定是否显示取消按钮。 另外,可用 cancelButtonClass 为其添加自定义样式,或者通过 cancelButtonText 来自定义按钮的文本(确认按钮也具有相同的字段,在文末的字段说明中有完整的字段列表)。 此例还使用了 beforeClose 属性。 它是一个在 MessageBox 实例关闭前的回调函数,它会在实例关闭前被调用,并且可以通过返回阻止实例的关闭。 它同时拥有三个参数:actioninstancedone。 使用它能够在关闭前对实例进行一些操作,比如为确认按钮添加 loading 状态; 你可以通过 done 函数来关闭 MessageBox 实例 (如果 beforeClose 没有在内部调用 done, 实例将不会被关闭)。

使用 HTML 字符串

message 属性支持 HTML 片段。

dangerouslyUseHTMLString 设置为 true,message 就会被当作 HTML 字符串处理。

警告

虽然 message 属性支持 HTML 字符串,但动态渲染任意 HTML 是非常危险的,因为它很容易导致 XSS 攻击。因此,当 dangerouslyUseHTMLString 打开的情况下,请确保 message 的内容是可信的,并且**永远不要**将用户提交的内容赋值给 message 属性。

区分取消与关闭

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

默认情况下,当用户通过点击取消按钮或关闭按钮或遮罩层关闭 MessageBox 时,callback 与 Promise 的 reject 回调函数的参数均为 'cancel'。 若将 distinguishCancelAndClose 属性设置为 true,则上述两种关闭操作的参数分别为 'cancel' 和 'close'。

内容居中

MessageBox 的内容可以居中。

center 设置为 true 即可开启居中布局。

自定义图标

图标可以自定义为任何 Vue 组件或 渲染函数 (JSX)

可拖拽

消息框可以拖动。

draggable 设置为 true 可以让用户拖动消息框。设置 overflow 2.5.4true 可以拖动溢出视口。

全局方法

如果 Element Plus 被完整引入,它会为 app.config.globalProperties 添加以下全局方法:$msgbox, $alert, $confirm$prompt。 因此在 Vue 实例中可以像本页面一样调用 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

现在消息框接收一个 context 作为消息构造函数的第二个(如果你使用消息框变体,则是第四个)参数,它允许你将当前应用程序的上下文注入到消息中,这允许你继承应用程序的所有属性。

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

// in your setup method
const { appContext } = getCurrentInstance()!
// You can pass it like:
ElMessageBox({}, appContext)
// or if you are using variants
ElMessageBox.alert('Hello world!', 'Title', {}, appContext)

局部导入

如果你更倾向于按需导入 MessageBox

ts
import { ElMessageBox } from 'element-plus'

对应的方法是:ElMessageBoxElMessageBox.alertElMessageBox.confirmElMessageBox.prompt。 参数与上述相同。

API

配置项

名称描述类型默认值
自动聚焦MessageBox 打开时是否自动获得焦点booleantrue
titleMessageBox 的标题string''
messageMessageBox 的内容string / VNode / Function 2.2.17
dangerouslyUseHTMLStringmessage 是否被当作 HTML 字符串处理booleanfalse
type消息类型,用于显示图标枚举''
icon自定义图标组件,该配置会覆盖 type 的图标string / Component''
closeIcon 2.9.5自定义关闭图标组件,默认为 Closestring / Component''
customClassMessageBox 的自定义类名string''
customStyleMessageBox 的自定义内联样式CSSProperties{}
modalClass遮罩层的自定义类名string
回调函数若不使用 Promise,可以使用此回调函数Functionnull
showClose是否显示 MessageBox 的关闭按钮booleantrue
beforeCloseMessageBox 关闭前的回调,会暂停实例的关闭Functionnull
distinguishCancelAndClose是否区分取消和关闭booleanfalse
lockScrollMessageBox 出现时是否锁定滚动条booleantrue
showCancelButton是否显示取消按钮booleanfalse (在 confirm 和 prompt 中为 true)
showConfirmButton是否显示确定按钮booleantrue
cancelButtonText取消按钮的文本内容string取消
confirmButtonText确认按钮的文本内容string确定
cancelButtonLoadingIcon 2.7.7取消按钮的加载图标内容string / Component加载中
confirmButtonLoadingIcon 2.7.7确认按钮的加载图标内容string / Component加载中
cancelButtonClass取消按钮的自定义类名string''
confirmButtonClass确认按钮的自定义类名string''
closeOnClickModal是否可通过点击遮罩层关闭 MessageBoxbooleantrue (在 alert 中为 false)
closeOnPressEscape是否可通过按下 ESC 关闭 MessageBoxbooleantrue (在 alert 中为 false)
closeOnHashChange当 hash 改变时是否关闭 MessageBoxbooleantrue
showInput是否显示输入框booleanfalse (在 prompt 中为 true)
inputPlaceholder输入框占位文本string''
inputType输入框的类型string文本
inputValue输入框的初始值string''
inputPattern输入框的正则表达式regexpnull
inputValidator输入框的校验函数。应该返回一个 boolean 或 string。如果返回一个 string,它将被赋值给 inputErrorMessageFunction/ undefinedundefined
inputErrorMessage校验失败时的错误提示文本string输入的数据不合法
居中是否居中布局booleanfalse
draggableMessageBox 是否可以拖拽booleanfalse
overflow 2.5.4可拖拽的 MessageBox 是否可以溢出视口booleanfalse
roundButton是否使用圆角按钮booleanfalse
buttonSize自定义确认和取消按钮的大小stringdefault
appendTo 2.2.19为消息框设置根元素CSSSelector / HTMLElement

来源

组件样式文档

贡献者