Message Box 弹框

一组模拟系统消息框的模态对话框,主要用于提示信息、确认操作和提问消息。

提示

从设计上来说,MessageBox 提供了对系统 alertconfirmprompt 的模拟,因此其内容应当简单。 对于更复杂的内容,请使用 Dialog。

消息提示

消息提示会中断用户操作,直到用户确认。

通过调用 ElMessageBox.alert 方法即可打开消息提示。 它模拟了系统的 alert,无法通过按下 ESC 或点击框外关闭。 在本例中,接收了两个参数 messagetitle。 值得注意的是,当窗口关闭时,它会返回一个 Promise 对象用于后续处理。 如果你不确定目标浏览器是否支持 Promise,你应该引入第三方 polyfill 或像本例一样使用回调函数。

确认消息

确认消息用于询问用户的确认。

调用 ElMessageBox.confirm 方法即可打开确认消息,它模拟了系统的 confirm。 我们还可以通过传递第三个属性 options(一个字面量对象)来高度自定义 Message Box。 属性 type 指示消息类型,其值可以是 primarysuccesserrorinfowarning。 请注意,第二个属性 title 必须是 string 类型,如果是 object 类型,它将被作为 options 属性处理。 在这里,我们使用 Promise 来处理后续操作。 primary 类型已在 2.9.11 中添加。

提交内容

提交内容用于需要用户输入的情况。

调用 ElMessageBox.prompt 方法即可打开提交内容对话框,它模拟了系统的 prompt。 您可以使用 inputPattern 参数指定自己的正则表达式模式。 使用 inputValidator 指定校验方法,它应返回 BooleanString。 返回 falseString 表示校验失败,返回的字符串将用作 inputErrorMessage。 此外,您可以使用 inputPlaceholder 参数自定义输入框的占位符。

使用 VNode

message 属性可以是一个 VNode。

使用带有操作处理函数的 VNode 2.14.0

您可以在 message 中接收 { confirm, cancel, close } 作为参数,这允许自定义内容以编程方式触发相同的 MessageBox 操作并自动关闭实例。

自定义内容

可以自定义显示各种内容。

上述三种方法都是 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 赋值为用户提供的内容。

区分取消与关闭

在某些情况下,点击取消按钮和关闭按钮可能具有不同的含义。

默认情况下,当用户取消(点击取消按钮)和关闭(点击关闭按钮或遮罩层、按 ESC 键)MessageBox 时,Promise 的 reject 回调和 callback 的参数都是 'cancel'。 如果将 distinguishCancelAndClose 设置为 true,则上述两种操作的参数分别为 'cancel' 和 'close'。

居中布局

MessageBox 的内容可以居中显示。

center 设置为 true 即可使内容居中。

自定义图标

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

可拖拽

MessageBox 可以被拖拽。

draggable 设置为 true 允许用户拖拽 MessageBox。 设置 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)

App 上下文继承 > 2.0.4

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

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 / Function 2.14.0
dangerouslyUseHTMLStringmessage 是否被当作 HTML 字符串处理booleanfalse
type消息类型,用于图标显示枚举''
icon自定义图标组件,覆盖 typestring / Component''
关闭图标 2.9.5自定义关闭图标组件,默认是 Closestring / Component''
customClassMessageBox 的自定义类名string''
自定义样式MessageBox 的自定义内联样式CSSProperties{}
遮罩层是否显示遮罩层booleantrue
遮罩层类名遮罩层的自定义类名string
回调函数如果您不倾向于使用 Promise,可以使用 MessageBox 关闭的回调Functionnull
showClose是否显示 MessageBox 的关闭图标booleantrue
关闭前回调MessageBox 关闭前的回调,它将阻止 MessageBox 关闭Functionnull
是否区分取消与关闭是否区分取消和关闭 MessageBoxbooleanfalse
锁定滚动MessageBox 弹出时是否锁定 body 滚动booleantrue
显示取消按钮是否显示取消按钮booleanfalse (当使用 confirm 和 prompt 调用时为 true)
显示确认按钮是否显示确认按钮booleantrue
取消按钮文本取消按钮的文本内容string取消
确认按钮文本确认按钮的文本内容string确定
取消按钮类型 2.13.1取消按钮的类型枚举
确认按钮类型 2.13.1确认按钮的类型枚举主要
取消按钮加载图标 2.7.7取消按钮的加载图标内容string / Component加载中
确认按钮加载图标 2.7.7确认按钮的加载图标内容string / Component加载中
取消按钮类名取消按钮的自定义类名string''
确认按钮类名确认按钮的自定义类名string''
点击遮罩关闭是否可通过点击遮罩层关闭 MessageBoxbooleantrue (当使用 alert 调用时为 false)
按 ESC 关闭是否可通过按下 ESC 键关闭 MessageBoxbooleantrue (当使用 alert 调用时为 false)
Hash 改变时关闭当 hash 改变时是否关闭 MessageBoxbooleantrue
显示输入框是否显示输入框booleanfalse (当使用 prompt 调用时为 true)
输入框占位符输入框占位文本string''
输入框类型输入框的类型,更多请参阅 MDNstring文本
输入框初始值输入框的初始值string''
输入正则输入框的正则表达式正则表达式null
输入验证器输入框的校验函数。应返回布尔值或字符串。如果返回字符串,它将被赋值给 inputErrorMessageFunction/ undefinedundefined
输入错误消息校验失败时的错误消息string非法输入
居中是否将内容居中对齐booleanfalse
draggableMessageBox 是否可拖拽booleanfalse
溢出 2.5.4可拖拽的 MessageBox 是否可以超出视口范围booleanfalse
圆角按钮是否使用圆角按钮booleanfalse
按钮尺寸确认和取消按钮的自定义尺寸stringdefault
插入至 2.2.19设置消息框的根元素CSSSelector / HTMLElement

来源

组件样式文档

贡献者