mirror of
https://gitee.com/element-plus/element-plus.git
synced 2024-12-16 02:11:48 +08:00
d7c7e86955
Co-authored-by: 无星 <32910694@qq.com>
589 lines
19 KiB
Markdown
589 lines
19 KiB
Markdown
## MessageBox 弹框
|
||
模拟系统的消息提示框而实现的一套模态对话框组件,用于消息提示、确认消息和提交内容。
|
||
|
||
:::tip
|
||
从场景上说,MessageBox 的作用是美化系统自带的 `alert`、`confirm` 和 `prompt`,因此适合展示较为简单的内容。如果需要弹出较为复杂的内容,请使用 Dialog。
|
||
:::
|
||
|
||
### 消息提示
|
||
|
||
当用户进行操作时会被触发,该对话框中断用户操作,直到用户确认知晓后才可关闭。
|
||
|
||
:::demo 调用`$alert`方法即可打开消息提示,它模拟了系统的 `alert`,无法通过按下 ESC 或点击框外关闭。此例中接收了两个参数,`message`和`title`。值得一提的是,窗口被关闭后,它默认会返回一个`Promise`对象便于进行后续操作的处理。若不确定浏览器是否支持`Promise`,可自行引入第三方 polyfill 或像本例一样使用回调进行后续处理。
|
||
```html
|
||
<template>
|
||
<el-button type="text" @click="open">点击打开 Message Box</el-button>
|
||
</template>
|
||
|
||
<script>
|
||
export default {
|
||
methods: {
|
||
open() {
|
||
this.$alert('这是一段内容', '标题名称', {
|
||
confirmButtonText: '确定',
|
||
callback: action => {
|
||
this.$message({
|
||
type: 'info',
|
||
message: `action: ${ action }`
|
||
});
|
||
}
|
||
});
|
||
}
|
||
}
|
||
}
|
||
</script>
|
||
<!--
|
||
<setup>
|
||
|
||
import { defineComponent } from 'vue';
|
||
import { ElMessageBox } from 'element-plus';
|
||
import { ElMessage } from 'element-plus';
|
||
|
||
export default defineComponent({
|
||
setup() {
|
||
|
||
const open = () => {
|
||
ElMessageBox.alert('这是一段内容', '标题名称', {
|
||
confirmButtonText: '确定',
|
||
callback: (action) => {
|
||
ElMessage({
|
||
type: 'info',
|
||
message: `action: ${action}`,
|
||
});
|
||
},
|
||
});
|
||
};
|
||
|
||
return {
|
||
open,
|
||
};
|
||
},
|
||
});
|
||
|
||
</setup>
|
||
-->
|
||
```
|
||
:::
|
||
|
||
### 确认消息
|
||
|
||
提示用户确认其已经触发的动作,并询问是否进行此操作时会用到此对话框。
|
||
|
||
:::demo 调用`$confirm`方法即可打开消息提示,它模拟了系统的 `confirm`。Message Box 组件也拥有极高的定制性,我们可以传入`options`作为第三个参数,它是一个字面量对象。`type`字段表明消息类型,可以为`success`,`error`,`info`和`warning`,无效的设置将会被忽略。注意,第二个参数`title`必须定义为`String`类型,如果是`Object`,会被理解为`options`。在这里我们用了 Promise 来处理后续响应。
|
||
|
||
```html
|
||
<template>
|
||
<el-button type="text" @click="open">点击打开 Message Box</el-button>
|
||
</template>
|
||
|
||
<script>
|
||
export default {
|
||
methods: {
|
||
open() {
|
||
this.$confirm('此操作将永久删除该文件, 是否继续?', '提示', {
|
||
confirmButtonText: '确定',
|
||
cancelButtonText: '取消',
|
||
type: 'warning'
|
||
}).then(() => {
|
||
this.$message({
|
||
type: 'success',
|
||
message: '删除成功!'
|
||
});
|
||
}).catch(() => {
|
||
this.$message({
|
||
type: 'info',
|
||
message: '已取消删除'
|
||
});
|
||
});
|
||
}
|
||
}
|
||
}
|
||
</script>
|
||
<!--
|
||
<setup>
|
||
|
||
import { defineComponent } from 'vue';
|
||
import { ElMessageBox } from 'element-plus';
|
||
import { ElMessage } from 'element-plus';
|
||
|
||
export default defineComponent({
|
||
setup() {
|
||
|
||
const open = () => {
|
||
ElMessageBox.confirm('此操作将永久删除该文件, 是否继续?', '提示', {
|
||
confirmButtonText: '确定',
|
||
cancelButtonText: '取消',
|
||
type: 'warning',
|
||
})
|
||
.then(() => {
|
||
ElMessage({
|
||
type: 'success',
|
||
message: '删除成功!',
|
||
});
|
||
})
|
||
.catch(() => {
|
||
ElMessage({
|
||
type: 'info',
|
||
message: '已取消删除',
|
||
});
|
||
});
|
||
};
|
||
|
||
return {
|
||
open,
|
||
};
|
||
},
|
||
});
|
||
|
||
</setup>
|
||
-->
|
||
```
|
||
:::
|
||
|
||
### 提交内容
|
||
|
||
当用户进行操作时会被触发,中断用户操作,提示用户进行输入的对话框。
|
||
|
||
:::demo 调用`$prompt`方法即可打开消息提示,它模拟了系统的 `prompt`。可以用`inputPattern`字段自己规定匹配模式,或者用`inputValidator`规定校验函数,可以返回`Boolean`或`String`,返回`false`或字符串时均表示校验未通过,同时返回的字符串相当于定义了`inputErrorMessage`字段。此外,可以用`inputPlaceholder`字段来定义输入框的占位符。
|
||
|
||
```html
|
||
<template>
|
||
<el-button type="text" @click="open">点击打开 Message Box</el-button>
|
||
</template>
|
||
|
||
<script>
|
||
export default {
|
||
methods: {
|
||
open() {
|
||
this.$prompt('请输入邮箱', '提示', {
|
||
confirmButtonText: '确定',
|
||
cancelButtonText: '取消',
|
||
inputPattern: /[\w!#$%&'*+/=?^_`{|}~-]+(?:\.[\w!#$%&'*+/=?^_`{|}~-]+)*@(?:[\w](?:[\w-]*[\w])?\.)+[\w](?:[\w-]*[\w])?/,
|
||
inputErrorMessage: '邮箱格式不正确'
|
||
}).then(({ value }) => {
|
||
this.$message({
|
||
type: 'success',
|
||
message: '你的邮箱是: ' + value
|
||
});
|
||
}).catch(() => {
|
||
this.$message({
|
||
type: 'info',
|
||
message: '取消输入'
|
||
});
|
||
});
|
||
}
|
||
}
|
||
}
|
||
</script>
|
||
|
||
<!--
|
||
<setup>
|
||
|
||
import { defineComponent } from 'vue';
|
||
import { ElMessageBox } from 'element-plus';
|
||
import { ElMessage } from 'element-plus';
|
||
|
||
export default defineComponent({
|
||
setup() {
|
||
|
||
const open = () => {
|
||
ElMessageBox.prompt('请输入邮箱', '提示', {
|
||
confirmButtonText: '确定',
|
||
cancelButtonText: '取消',
|
||
inputPattern: /[\w!#$%&'*+/=?^_`{|}~-]+(?:\.[\w!#$%&'*+/=?^_`{|}~-]+)*@(?:[\w](?:[\w-]*[\w])?\.)+[\w](?:[\w-]*[\w])?/,
|
||
inputErrorMessage: '邮箱格式不正确',
|
||
})
|
||
.then(({ value }) => {
|
||
ElMessage({
|
||
type: 'success',
|
||
message: `你的邮箱是: ${value}`,
|
||
});
|
||
})
|
||
.catch(() => {
|
||
ElMessage({
|
||
type: 'info',
|
||
message: '取消输入',
|
||
});
|
||
});
|
||
};
|
||
|
||
return {
|
||
open,
|
||
};
|
||
},
|
||
});
|
||
|
||
</setup>
|
||
-->
|
||
```
|
||
:::
|
||
|
||
### 自定义
|
||
|
||
可自定义配置不同内容。
|
||
|
||
:::demo 以上三个方法都是对`$msgbox`方法的再包装。本例直接调用`$msgbox`方法,使用了`showCancelButton`字段,用于显示取消按钮。另外可使用`cancelButtonClass`为其添加自定义样式,使用`cancelButtonText`来自定义按钮文本(Confirm 按钮也具有相同的字段,在文末的字段说明中有完整的字段列表)。此例还使用了`beforeClose`属性,它的值是一个方法,会在 MessageBox 的实例关闭前被调用,同时暂停实例的关闭。它有三个参数:`action`、实例本身和`done`方法。使用它能够在关闭前对实例进行一些操作,比如为确定按钮添加`loading`状态等;此时若需要关闭实例,可以调用`done`方法(若在`beforeClose`中没有调用`done`,则实例不会关闭)。
|
||
|
||
```html
|
||
<template>
|
||
<el-button type="text" @click="open">点击打开 Message Box</el-button>
|
||
</template>
|
||
|
||
<script>
|
||
import { h } from 'vue';
|
||
|
||
export default {
|
||
methods: {
|
||
open() {
|
||
this.$msgbox({
|
||
title: '消息',
|
||
message: h('p', null, [
|
||
h('span', null, '内容可以是 '),
|
||
h('i', { style: 'color: teal' }, 'VNode')
|
||
]),
|
||
showCancelButton: true,
|
||
confirmButtonText: '确定',
|
||
cancelButtonText: '取消',
|
||
beforeClose: (action, instance, done) => {
|
||
if (action === 'confirm') {
|
||
instance.confirmButtonLoading = true;
|
||
instance.confirmButtonText = '执行中...';
|
||
setTimeout(() => {
|
||
done();
|
||
setTimeout(() => {
|
||
instance.confirmButtonLoading = false;
|
||
}, 300);
|
||
}, 3000);
|
||
} else {
|
||
done();
|
||
}
|
||
}
|
||
}).then(action => {
|
||
this.$message({
|
||
type: 'info',
|
||
message: 'action: ' + action
|
||
});
|
||
});
|
||
}
|
||
}
|
||
}
|
||
</script>
|
||
|
||
<!--
|
||
<setup>
|
||
|
||
import { defineComponent, h } from 'vue';
|
||
import { ElMessage } from 'element-plus';
|
||
|
||
export default defineComponent({
|
||
setup() {
|
||
|
||
const open = () => {
|
||
ElMessageBox({
|
||
title: '消息',
|
||
message: h('p', null, [
|
||
h('span', null, '内容可以是 '),
|
||
h('i', { style: 'color: teal' }, 'VNode'),
|
||
]),
|
||
showCancelButton: true,
|
||
confirmButtonText: '确定',
|
||
cancelButtonText: '取消',
|
||
beforeClose: (action, instance, done) => {
|
||
if (action === 'confirm') {
|
||
instance.confirmButtonLoading = true;
|
||
instance.confirmButtonText = '执行中...';
|
||
setTimeout(() => {
|
||
done();
|
||
setTimeout(() => {
|
||
instance.confirmButtonLoading = false;
|
||
}, 300);
|
||
}, 3000);
|
||
} else {
|
||
done();
|
||
}
|
||
},
|
||
}).then((action) => {
|
||
ElMessage({
|
||
type: 'info',
|
||
message: `action: ${action}`,
|
||
});
|
||
}).catch((e) => {
|
||
console.log(e);
|
||
});
|
||
};
|
||
|
||
return {
|
||
open,
|
||
};
|
||
},
|
||
});
|
||
|
||
</setup>
|
||
-->
|
||
```
|
||
:::
|
||
|
||
:::tip
|
||
弹出层的内容可以是 `VNode`,所以我们能把一些自定义组件传入其中。每次弹出层打开后,Vue 会对新老 `VNode` 节点进行比对,然后将根据比较结果进行最小单位地修改视图。这也许会造成弹出层内容区域的组件没有重新渲染,例如 [#8931](https://github.com/ElemeFE/element/issues/8931)。当这类问题出现时,解决方案是给 `VNode` 加上一个不相同的 key,参考[这里](https://jsfiddle.net/zhiyang/ezmhq2ef/)。
|
||
:::
|
||
|
||
### 使用 HTML 片段
|
||
|
||
`message` 属性支持传入 HTML 片段。
|
||
|
||
:::demo 将`dangerouslyUseHTMLString`属性设置为 true,`message` 就会被当作 HTML 片段处理。
|
||
|
||
```html
|
||
<template>
|
||
<el-button type="text" @click="open">点击打开 Message Box</el-button>
|
||
</template>
|
||
|
||
<script>
|
||
export default {
|
||
methods: {
|
||
open() {
|
||
this.$alert('<strong>这是 <i>HTML</i> 片段</strong>', 'HTML 片段', {
|
||
dangerouslyUseHTMLString: true
|
||
});
|
||
}
|
||
}
|
||
}
|
||
</script>
|
||
<!--
|
||
<setup>
|
||
|
||
import { defineComponent } from 'vue';
|
||
import { ElMessageBox } from 'element-plus';
|
||
|
||
export default defineComponent({
|
||
setup() {
|
||
|
||
const open = () => {
|
||
ElMessageBox.alert('<strong>这是 <i>HTML</i> 片段</strong>', 'HTML 片段', {
|
||
dangerouslyUseHTMLString: true,
|
||
});
|
||
};
|
||
|
||
return {
|
||
open,
|
||
};
|
||
},
|
||
});
|
||
|
||
</setup>
|
||
-->
|
||
```
|
||
:::
|
||
|
||
:::warning
|
||
`message` 属性虽然支持传入 HTML 片段,但是在网站上动态渲染任意 HTML 是非常危险的,因为容易导致 [XSS 攻击](https://en.wikipedia.org/wiki/Cross-site_scripting)。因此在 `dangerouslyUseHTMLString` 打开的情况下,请确保 `message` 的内容是可信的,**永远不要**将用户提交的内容赋值给 `message` 属性。
|
||
:::
|
||
|
||
### 区分取消与关闭
|
||
|
||
有些场景下,点击取消按钮与点击关闭按钮有着不同的含义。
|
||
|
||
:::demo 默认情况下,当用户触发取消(点击取消按钮)和触发关闭(点击关闭按钮或遮罩层、按下 ESC 键)时,Promise 的 reject 回调和`callback`回调的参数均为 'cancel'。如果将`distinguishCancelAndClose`属性设置为 true,则上述两种行为的参数分别为 'cancel' 和 'close'。
|
||
|
||
```html
|
||
<template>
|
||
<el-button type="text" @click="open">点击打开 Message Box</el-button>
|
||
</template>
|
||
|
||
<script>
|
||
export default {
|
||
methods: {
|
||
open() {
|
||
this.$confirm('检测到未保存的内容,是否在离开页面前保存修改?', '确认信息', {
|
||
distinguishCancelAndClose: true,
|
||
confirmButtonText: '保存',
|
||
cancelButtonText: '放弃修改'
|
||
})
|
||
.then(() => {
|
||
this.$message({
|
||
type: 'info',
|
||
message: '保存修改'
|
||
});
|
||
})
|
||
.catch(action => {
|
||
this.$message({
|
||
type: 'info',
|
||
message: action === 'cancel'
|
||
? '放弃保存并离开页面'
|
||
: '停留在当前页面'
|
||
})
|
||
});
|
||
}
|
||
}
|
||
}
|
||
</script>
|
||
<!--
|
||
<setup>
|
||
|
||
import { defineComponent } from 'vue';
|
||
import { ElMessageBox } from 'element-plus';
|
||
import { ElMessage } from 'element-plus';
|
||
|
||
export default defineComponent({
|
||
setup() {
|
||
|
||
const open = () => {
|
||
ElMessageBox.confirm('检测到未保存的内容,是否在离开页面前保存修改?', '确认信息', {
|
||
distinguishCancelAndClose: true,
|
||
confirmButtonText: '保存',
|
||
cancelButtonText: '放弃修改',
|
||
})
|
||
.then(() => {
|
||
ElMessage({
|
||
type: 'info',
|
||
message: '保存修改',
|
||
});
|
||
})
|
||
.catch((action) => {
|
||
ElMessage({
|
||
type: 'info',
|
||
message: action === 'cancel'
|
||
? '放弃保存并离开页面'
|
||
: '停留在当前页面',
|
||
});
|
||
});
|
||
};
|
||
|
||
return {
|
||
open,
|
||
};
|
||
},
|
||
});
|
||
|
||
</setup>
|
||
-->
|
||
```
|
||
:::
|
||
|
||
### 居中布局
|
||
内容支持居中布局
|
||
|
||
:::demo 将 `center` 设置为 `true` 即可开启居中布局
|
||
|
||
```html
|
||
<template>
|
||
<el-button type="text" @click="open">点击打开 Message Box</el-button>
|
||
</template>
|
||
|
||
<script>
|
||
export default {
|
||
methods: {
|
||
open() {
|
||
this.$confirm('此操作将永久删除该文件, 是否继续?', '提示', {
|
||
confirmButtonText: '确定',
|
||
cancelButtonText: '取消',
|
||
type: 'warning',
|
||
center: true
|
||
}).then(() => {
|
||
this.$message({
|
||
type: 'success',
|
||
message: '删除成功!'
|
||
});
|
||
}).catch(() => {
|
||
this.$message({
|
||
type: 'info',
|
||
message: '已取消删除'
|
||
});
|
||
});
|
||
}
|
||
}
|
||
}
|
||
</script>
|
||
<!--
|
||
<setup>
|
||
|
||
import { defineComponent } from 'vue';
|
||
import { ElMessageBox } from 'element-plus';
|
||
import { ElMessage } from 'element-plus';
|
||
|
||
export default defineComponent({
|
||
setup() {
|
||
|
||
const open = () => {
|
||
ElMessageBox.confirm('此操作将永久删除该文件, 是否继续?', '提示', {
|
||
confirmButtonText: '确定',
|
||
cancelButtonText: '取消',
|
||
type: 'warning',
|
||
center: true,
|
||
}).then(() => {
|
||
ElMessage({
|
||
type: 'success',
|
||
message: '删除成功!',
|
||
});
|
||
}).catch(() => {
|
||
ElMessage({
|
||
type: 'info',
|
||
message: '已取消删除',
|
||
});
|
||
});
|
||
};
|
||
|
||
return {
|
||
open,
|
||
};
|
||
},
|
||
});
|
||
|
||
</setup>
|
||
-->
|
||
```
|
||
:::
|
||
|
||
### 全局方法
|
||
|
||
如果你完整引入了 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)`
|
||
|
||
### 单独引用
|
||
|
||
如果单独引入 `MessageBox`:
|
||
|
||
```javascript
|
||
import { ElMessageBox } from 'element-plus';
|
||
```
|
||
|
||
那么对应于上述四个全局方法的调用方法依次为:ElMessageBox, ElMessageBox.alert, ElMessageBox.confirm 和 ElMessageBox.prompt,调用参数与全局方法相同。
|
||
|
||
### Options
|
||
|
||
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|
||
|---------- |-------------- |---------- |-------------------------------- |-------- |
|
||
| title | MessageBox 标题 | string | — | — |
|
||
| message | MessageBox 消息正文内容 | string / VNode | — | — |
|
||
| dangerouslyUseHTMLString | 是否将 message 属性作为 HTML 片段处理 | boolean | — | false |
|
||
| type | 消息类型,用于显示图标 | string | success / info / warning / error | — |
|
||
| iconClass | 自定义图标的类名,会覆盖 `type` | string | — | — |
|
||
| customClass | MessageBox 的自定义类名 | string | — | — |
|
||
| callback | 若不使用 Promise,可以使用此参数指定 MessageBox 关闭后的回调 | function(action, instance),action 的值为'confirm', 'cancel'或'close', instance 为 MessageBox 实例,可以通过它访问实例上的属性和方法 | — | — |
|
||
| showClose | MessageBox 是否显示右上角关闭按钮 | boolean | — | true |
|
||
| beforeClose | MessageBox 关闭前的回调,会暂停实例的关闭 | function(action, instance, done),action 的值为'confirm', 'cancel'或'close';instance 为 MessageBox 实例,可以通过它访问实例上的属性和方法;done 用于关闭 MessageBox 实例 | — | — |
|
||
| distinguishCancelAndClose | 是否将取消(点击取消按钮)与关闭(点击关闭按钮或遮罩层、按下 ESC 键)进行区分 | boolean | — | false |
|
||
| lockScroll | 是否在 MessageBox 出现时将 body 滚动锁定 | boolean | — | true |
|
||
| showCancelButton | 是否显示取消按钮 | boolean | — | false(以 confirm 和 prompt 方式调用时为 true) |
|
||
| showConfirmButton | 是否显示确定按钮 | boolean | — | true |
|
||
| cancelButtonText | 取消按钮的文本内容 | string | — | 取消 |
|
||
| confirmButtonText | 确定按钮的文本内容 | string | — | 确定 |
|
||
| cancelButtonClass | 取消按钮的自定义类名 | string | — | — |
|
||
| confirmButtonClass | 确定按钮的自定义类名 | string | — | — |
|
||
| closeOnClickModal | 是否可通过点击遮罩关闭 MessageBox | boolean | — | true(以 alert 方式调用时为 false) |
|
||
| closeOnPressEscape | 是否可通过按下 ESC 键关闭 MessageBox | boolean | — | true(以 alert 方式调用时为 false) |
|
||
| closeOnHashChange | 是否在 hashchange 时关闭 MessageBox | boolean | — | true |
|
||
| showInput | 是否显示输入框 | boolean | — | false(以 prompt 方式调用时为 true)|
|
||
| inputPlaceholder | 输入框的占位符 | string | — | — |
|
||
| inputType | 输入框的类型 | string | — | text |
|
||
| inputValue | 输入框的初始文本 | string | — | — |
|
||
| inputPattern | 输入框的校验表达式 | regexp | — | — |
|
||
| inputValidator | 输入框的校验函数。可以返回布尔值或字符串,若返回一个字符串, 则返回结果会被赋值给 inputErrorMessage | function | — | — |
|
||
| inputErrorMessage | 校验未通过时的提示文本 | string | — | 输入的数据不合法! |
|
||
| center | 是否居中布局 | boolean | — | false |
|
||
| roundButton | 是否使用圆角按钮 | boolean | — | false |
|
||
| buttonSize | 自定义确认按钮及取消按钮的大小 | string | mini / small / medium / large | small |
|