Message Box 弹框
一组模拟系统消息框的模态对话框,主要用于提示信息、确认操作和提问消息。
提示
从设计上来说,MessageBox 提供了对系统 alert、confirm 和 prompt 的模拟,因此其内容应当简单。 对于更复杂的内容,请使用 Dialog。
消息提示
消息提示会中断用户操作,直到用户确认。
通过调用 ElMessageBox.alert 方法即可打开消息提示。 它模拟了系统的 alert,无法通过按下 ESC 或点击框外关闭。 在本例中,接收了两个参数 message 和 title。 值得注意的是,当窗口关闭时,它会返回一个 Promise 对象用于后续处理。 如果你不确定目标浏览器是否支持 Promise,你应该引入第三方 polyfill 或像本例一样使用回调函数。
确认消息
确认消息用于询问用户的确认。
调用 ElMessageBox.confirm 方法即可打开确认消息,它模拟了系统的 confirm。 我们还可以通过传递第三个属性 options(一个字面量对象)来高度自定义 Message Box。 属性 type 指示消息类型,其值可以是 primary、success、error、info 和 warning。 请注意,第二个属性 title 必须是 string 类型,如果是 object 类型,它将被作为 options 属性处理。 在这里,我们使用 Promise 来处理后续操作。 primary 类型已在 2.9.11 中添加。
提交内容
提交内容用于需要用户输入的情况。
调用 ElMessageBox.prompt 方法即可打开提交内容对话框,它模拟了系统的 prompt。 您可以使用 inputPattern 参数指定自己的正则表达式模式。 使用 inputValidator 指定校验方法,它应返回 Boolean 或 String。 返回 false 或 String 表示校验失败,返回的字符串将用作 inputErrorMessage。 此外,您可以使用 inputPlaceholder 参数自定义输入框的占位符。
使用 VNode
message 属性可以是一个 VNode。
使用带有操作处理函数的 VNode 2.14.0
您可以在 message 中接收 { confirm, cancel, close } 作为参数,这允许自定义内容以编程方式触发相同的 MessageBox 操作并自动关闭实例。
自定义内容
可以自定义显示各种内容。
上述三种方法都是 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 赋值为用户提供的内容。
区分取消与关闭
在某些情况下,点击取消按钮和关闭按钮可能具有不同的含义。
默认情况下,当用户取消(点击取消按钮)和关闭(点击关闭按钮或遮罩层、按 ESC 键)MessageBox 时,Promise 的 reject 回调和 callback 的参数都是 'cancel'。 如果将 distinguishCancelAndClose 设置为 true,则上述两种操作的参数分别为 'cancel' 和 'close'。
居中布局
MessageBox 的内容可以居中显示。
将 center 设置为 true 即可使内容居中。
自定义图标
图标可以自定义为任何 Vue 组件或 渲染函数 (JSX)。
可拖拽
MessageBox 可以被拖拽。
将 draggable 设置为 true 允许用户拖拽 MessageBox。 设置 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)
App 上下文继承 > 2.0.4
现在消息框接收 context 作为消息构造器的第二个(如果您使用的是消息框变体,则为第四个)参数,这允许您将当前 app 的上下文注入到消息中,从而继承 app 的所有属性。
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 / Function 2.14.0 | — |
| dangerouslyUseHTMLString | message 是否被当作 HTML 字符串处理 | boolean | false |
| type | 消息类型,用于图标显示 | 枚举 | '' |
| icon | 自定义图标组件,覆盖 type | string / Component | '' |
| 关闭图标 2.9.5 | 自定义关闭图标组件,默认是 Close | string / Component | '' |
| customClass | MessageBox 的自定义类名 | string | '' |
| 自定义样式 | MessageBox 的自定义内联样式 | CSSProperties | {} |
| 遮罩层 | 是否显示遮罩层 | boolean | true |
| 遮罩层类名 | 遮罩层的自定义类名 | string | — |
| 回调函数 | 如果您不倾向于使用 Promise,可以使用 MessageBox 关闭的回调 | Function | null |
| showClose | 是否显示 MessageBox 的关闭图标 | boolean | true |
| 关闭前回调 | MessageBox 关闭前的回调,它将阻止 MessageBox 关闭 | Function | null |
| 是否区分取消与关闭 | 是否区分取消和关闭 MessageBox | boolean | false |
| 锁定滚动 | MessageBox 弹出时是否锁定 body 滚动 | boolean | true |
| 显示取消按钮 | 是否显示取消按钮 | boolean | false (当使用 confirm 和 prompt 调用时为 true) |
| 显示确认按钮 | 是否显示确认按钮 | boolean | true |
| 取消按钮文本 | 取消按钮的文本内容 | string | 取消 |
| 确认按钮文本 | 确认按钮的文本内容 | string | 确定 |
| 取消按钮类型 2.13.1 | 取消按钮的类型 | 枚举 | — |
| 确认按钮类型 2.13.1 | 确认按钮的类型 | 枚举 | 主要 |
| 取消按钮加载图标 2.7.7 | 取消按钮的加载图标内容 | string / Component | 加载中 |
| 确认按钮加载图标 2.7.7 | 确认按钮的加载图标内容 | string / Component | 加载中 |
| 取消按钮类名 | 取消按钮的自定义类名 | string | '' |
| 确认按钮类名 | 确认按钮的自定义类名 | string | '' |
| 点击遮罩关闭 | 是否可通过点击遮罩层关闭 MessageBox | boolean | true (当使用 alert 调用时为 false) |
| 按 ESC 关闭 | 是否可通过按下 ESC 键关闭 MessageBox | boolean | true (当使用 alert 调用时为 false) |
| Hash 改变时关闭 | 当 hash 改变时是否关闭 MessageBox | boolean | true |
| 显示输入框 | 是否显示输入框 | boolean | false (当使用 prompt 调用时为 true) |
| 输入框占位符 | 输入框占位文本 | string | '' |
| 输入框类型 | 输入框的类型,更多请参阅 MDN | string | 文本 |
| 输入框初始值 | 输入框的初始值 | string | '' |
| 输入正则 | 输入框的正则表达式 | 正则表达式 | null |
| 输入验证器 | 输入框的校验函数。应返回布尔值或字符串。如果返回字符串,它将被赋值给 inputErrorMessage | Function/ undefined | undefined |
| 输入错误消息 | 校验失败时的错误消息 | string | 非法输入 |
| 居中 | 是否将内容居中对齐 | boolean | false |
| draggable | MessageBox 是否可拖拽 | boolean | false |
| 溢出 2.5.4 | 可拖拽的 MessageBox 是否可以超出视口范围 | boolean | false |
| 圆角按钮 | 是否使用圆角按钮 | boolean | false |
| 按钮尺寸 | 确认和取消按钮的自定义尺寸 | string | default |
| 插入至 2.2.19 | 设置消息框的根元素 | CSSSelector / HTMLElement | — |