Message 消息提示

常用于主动操作后的即时反馈。与 Notification 相比，Message 更轻量，适合保存成功、提交失败、字段校验提醒等短消息。

基础用法

直接调用 ElMessage 即可显示消息，默认展示在页面顶部并在 3 秒后自动消失。message 可以是字符串，也可以是 VNode。

<template>
  <el-button plain @click="open">Show message</el-button>
  <el-button plain @click="openVNode">VNode</el-button>
</template>

<script setup lang="ts">
import { h } from 'vue'
import { ElMessage } from 'element-plus'

const open = () => {
  ElMessage('项目状态已更新')
}

const openVNode = () => {
  ElMessage({
    message: h('p', { style: 'line-height: 1; font-size: 14px' }, [
      h('span', null, 'Message can be '),
      h('i', { style: 'color: teal' }, 'VNode'),
    ]),
  })
}
</script>

不同状态

通过 type 设置消息类型，常用来表示成功、警告、信息和错误反馈。primary 类型可用于品牌强调。

<template>
  <el-button plain @click="openMessage('success')">Success</el-button>
  <el-button plain @click="openMessage('warning')">Warning</el-button>
  <el-button plain @click="openMessage('error')">Error</el-button>
</template>

<script setup lang="ts">
import { ElMessage } from 'element-plus'

const openMessage = (type: 'success' | 'warning' | 'info' | 'error') => {
  ElMessage({
    message: `这是一条 ${type} 消息`,
    type,
  })
}
</script>

Plain

设置 plain 后，消息背景会更轻，适合弱提示或低干扰场景。

<el-button plain @click="ElMessage({ message: '保存成功', type: 'success', plain: true })">
  Success
</el-button>

可关闭

设置 showClose 可以显示关闭按钮。duration 控制自动关闭时间，设置为 0 时不会自动关闭。

<script setup lang="ts">
import { ElMessage } from 'element-plus'

const open = () => {
  ElMessage({
    showClose: true,
    message: '这条消息可以手动关闭',
    type: 'success',
  })
}

const openPersistent = () => {
  ElMessage({
    showClose: true,
    duration: 0,
    message: '这条消息不会自动关闭',
  })
}
</script>

HTML 内容

设置 dangerouslyUseHTMLString 后，message 会作为 HTML 片段处理。只应传入可信内容，不要把用户输入直接传给 message。

<script setup lang="ts">
import { ElMessage } from 'element-plus'

const openHTML = () => {
  ElMessage({
    dangerouslyUseHTMLString: true,
    message: '<strong>这是一条 <i>HTML</i> 消息</strong>',
  })
}
</script>

分组消息合并

设置 grouping 后，相同内容的消息会被合并，并显示重复次数。分组消息不支持 VNode 类型内容。

<script setup lang="ts">
import { ElMessage } from 'element-plus'

const open = () => {
  ElMessage({
    message: '项目正在同步，请稍候',
    grouping: true,
    type: 'success',
  })
}
</script>

显示位置

通过 placement 可以控制消息出现位置，支持顶部、顶部两侧、底部和底部两侧。

<script setup lang="ts">
import { ElMessage } from 'element-plus'

const openMsg = (placement = 'top') => {
  ElMessage({
    message: `这条消息显示在 ${placement}`,
    type: 'success',
    placement,
  })
}
</script>

自定义样式

offset 可以控制消息距离视口边缘的距离；customClass 可以添加自定义类名；icon 可以覆盖状态图标。

<script setup lang="ts">
import { ElMessage } from 'element-plus'
import { Check } from '@element-plus/icons-vue'

const open = () => {
  ElMessage({
    message: '已应用自定义样式',
    customClass: 'message-soft',
    offset: 64,
  })
}

const openIcon = () => {
  ElMessage({
    message: '已完成同步',
    icon: Check,
  })
}
</script>

指定挂载节点

通过 appendTo 可以指定 Message 的根元素，默认挂载到 document.body。

<template>
  <div class="message-append-target">
    <el-button plain @click="open">挂载到当前区域</el-button>
  </div>
</template>

<script setup lang="ts">
import { ElMessage } from 'element-plus'

const open = () => {
  ElMessage({
    message: '这条消息挂载在指定节点下',
    appendTo: '.message-append-target',
  })
}
</script>

手动关闭

ElMessage 调用后会返回当前消息实例，可以通过实例的 close 方法关闭。也可以调用 ElMessage.closeAll() 关闭全部消息。

<script setup lang="ts">
import { ref } from 'vue'
import { ElMessage } from 'element-plus'

const messageHandler = ref()

const open = () => {
  messageHandler.value = ElMessage({
    message: '这条消息需要手动关闭',
    duration: 0,
    showClose: true,
  })
}

const close = () => {
  messageHandler.value?.close()
}

const closeAll = () => {
  ElMessage.closeAll()
}
</script>

全局方法

Element Plus 会在 app.config.globalProperties 上注册 $message。在组合式 API 中更推荐单独引入 ElMessage 使用。

import { ElMessage } from 'element-plus'

ElMessage('这是一条消息')
ElMessage.success('保存成功')
ElMessage.closeAll()

应用上下文

Message 可以接收应用上下文作为第二个参数，用于继承当前应用的插件、全局属性等上下文。

import { getCurrentInstance } from 'vue'
import { ElMessage } from 'element-plus'

const { appContext } = getCurrentInstance()!

ElMessage(
  {
    message: '继承当前应用上下文',
  },
  appContext,
)

Message API

Message 配置项

名称	说明	类型	默认值
message	消息文字	string | VNode | Function	''
type	消息类型	primary | success | warning | info | error	info
plain	是否为朴素样式	boolean	false
icon	自定义图标，会覆盖 type 的图标	string | Component	-
dangerouslyUseHTMLString	是否将 message 作为 HTML 片段处理	boolean	false
customClass	自定义类名	string	''
duration	显示时间，单位毫秒，设为 0 时不会自动关闭	number	3000
showClose	是否显示关闭按钮	boolean	false
onClose	关闭时的回调函数，参数为被关闭的 message 实例	function	-
offset	距离视口边缘的距离，顶部位置为上边距，底部位置为下边距	number	16
placement	消息出现位置	top | top-left | top-right | bottom | bottom-left | bottom-right	top
appendTo	设置 message 的根元素	CSSSelector | HTMLElement	document.body
grouping	合并内容相同的消息，不支持 VNode 类型消息	boolean	false
repeatNum	重复次数，配合 grouping 时作为初始数量	number	1

Message 方法

名称	说明	类型
close	关闭当前 Message	Function