消息弹出框
模拟系统的消息提示框而实现的一套模态对话框组件,用于消息提示、确认消息和提交内容。
提示
从场景上说,MessageBox 的作用是美化系统自带的 alert
、confirm
和 prompt
,因此适合展示较为简单的内容。 如果需要弹出较为复杂的内容,请使用 Dialog。
消息提示
消息提示,需要用户交互之后才会消失。
调用 ElMessageBox.alert
方法即可打开消息提示,它模拟了系统的 alert
,无法通过按下 ESC 或点击框外关闭。 此例中接收了两个参数,message
和 title
。 值得一提的是,窗口被关闭后,它会返回一个 Promise
对象便于进行后续操作的处理。 若不确定浏览器是否支持 Promise
,可使用传统的回调函数,正如本例所示。
确认消息
确认消息,用来向用户确认操作。
调用 ElMessageBox.confirm
方法即可打开消息确认框,它模拟了系统的 confirm
。 我们还可以通过第三个参数 options
为弹窗传入更多配置。 type
字段表明消息类型,可以为 primary
、success
、error
、info
和 warning
,无效的设置将会被忽略。 注意,第二个参数 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 实例关闭前的回调函数,它会在实例关闭前被调用,并且可以通过返回阻止实例的关闭。 它同时拥有三个参数:action
、instance
和 done
。 使用它能够在关闭前对实例进行一些操作,比如为确认按钮添加 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.4 为 true
可以拖动溢出视口。
全局方法
如果 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
作为消息构造函数的第二个(如果你使用消息框变体,则是第四个)参数,它允许你将当前应用程序的上下文注入到消息中,这允许你继承应用程序的所有属性。
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
import { ElMessageBox } from 'element-plus'
对应的方法是:ElMessageBox
、ElMessageBox.alert
、ElMessageBox.confirm
和 ElMessageBox.prompt
。 参数与上述相同。
API
配置项
名称 | 描述 | 类型 | 默认值 |
---|---|---|---|
自动聚焦 | MessageBox 打开时是否自动获得焦点 | boolean | true |
title | MessageBox 的标题 | string | '' |
message | MessageBox 的内容 | string / VNode / Function 2.2.17 | — |
dangerouslyUseHTMLString | message 是否被当作 HTML 字符串处理 | boolean | false |
type | 消息类型,用于显示图标 | 枚举 | '' |
icon | 自定义图标组件,该配置会覆盖 type 的图标 | string / Component | '' |
closeIcon 2.9.5 | 自定义关闭图标组件,默认为 Close | string / Component | '' |
customClass | MessageBox 的自定义类名 | string | '' |
customStyle | MessageBox 的自定义内联样式 | CSSProperties | {} |
modalClass | 遮罩层的自定义类名 | string | — |
回调函数 | 若不使用 Promise,可以使用此回调函数 | Function | null |
showClose | 是否显示 MessageBox 的关闭按钮 | boolean | true |
beforeClose | MessageBox 关闭前的回调,会暂停实例的关闭 | Function | null |
distinguishCancelAndClose | 是否区分取消和关闭 | boolean | false |
lockScroll | MessageBox 出现时是否锁定滚动条 | boolean | true |
showCancelButton | 是否显示取消按钮 | boolean | false (在 confirm 和 prompt 中为 true) |
showConfirmButton | 是否显示确定按钮 | boolean | true |
cancelButtonText | 取消按钮的文本内容 | string | 取消 |
confirmButtonText | 确认按钮的文本内容 | string | 确定 |
cancelButtonLoadingIcon 2.7.7 | 取消按钮的加载图标内容 | string / Component | 加载中 |
confirmButtonLoadingIcon 2.7.7 | 确认按钮的加载图标内容 | string / Component | 加载中 |
cancelButtonClass | 取消按钮的自定义类名 | string | '' |
confirmButtonClass | 确认按钮的自定义类名 | string | '' |
closeOnClickModal | 是否可通过点击遮罩层关闭 MessageBox | boolean | true (在 alert 中为 false) |
closeOnPressEscape | 是否可通过按下 ESC 关闭 MessageBox | boolean | true (在 alert 中为 false) |
closeOnHashChange | 当 hash 改变时是否关闭 MessageBox | boolean | true |
showInput | 是否显示输入框 | boolean | false (在 prompt 中为 true) |
inputPlaceholder | 输入框占位文本 | string | '' |
inputType | 输入框的类型 | string | 文本 |
inputValue | 输入框的初始值 | string | '' |
inputPattern | 输入框的正则表达式 | regexp | null |
inputValidator | 输入框的校验函数。应该返回一个 boolean 或 string。如果返回一个 string,它将被赋值给 inputErrorMessage | Function / undefined | undefined |
inputErrorMessage | 校验失败时的错误提示文本 | string | 输入的数据不合法 |
居中 | 是否居中布局 | boolean | false |
draggable | MessageBox 是否可以拖拽 | boolean | false |
overflow 2.5.4 | 可拖拽的 MessageBox 是否可以溢出视口 | boolean | false |
roundButton | 是否使用圆角按钮 | boolean | false |
buttonSize | 自定义确认和取消按钮的大小 | string | default |
appendTo 2.2.19 | 为消息框设置根元素 | CSSSelector / HTMLElement | — |