Message 消息提示

用于主动操作后的反馈提示。与 Notification 的区别是后者更多用于系统级通知的被动提醒。

基础用法

从顶部出现，3 秒后自动消失。

基础用法

不同状态

用来显示「成功、警告、消息、错误」类的操作反馈。

不同状态

可关闭

可以添加关闭按钮。默认的 Message 是不可以被人工关闭的，如果需要可手动关闭的 Message，可以使用 showClose 属性。同时，设置 duration 为 0 可以使消息不自动关闭。

可关闭

文字居中

使用 center 属性让文字水平居中。

文字居中

使用 HTML 片段

设置 dangerouslyUseHTMLString 为 true 可以使 message 属性被当作 HTML 片段处理。

警告

message 属性虽然支持传入 HTML 片段，但是动态渲染任意 HTML 是非常危险的。请确保 message 的内容是可信的，永远不要将用户提交的内容赋值给 message 属性。

使用 HTML 片段

分组合并

设置 grouping 为 true，内容相同的 message 将被合并。

分组合并

展示位置

设置 placement 属性可以控制消息出现的位置。

展示位置

在 Nuxt 中使用

Message 组件完全支持 Nuxt 3/4 环境。作为一个函数调用的指令式组件，它在 SSR（服务端渲染）时会自动进行环境检测，确保消息弹出逻辑仅在 Web 浏览器端执行。

Nuxt 中使用

SSR 注意事项：

• ✅ 安全调用：在模板或 setup 顶层直接调用函数是安全的，内部已处理 window 检测
• ✅ 自动导入：在 Nuxt 项目中，YhMessage 函数及其调用别名会自动导入，无需手动 import
• ⚠️ 服务端限制：在 Nuxt 的 asyncData 或 fetch 服务端执行阶段调用消息提示是无效的（因为此时没有 DOM 容器）
• 💡 样式一致性：Message 的样式会伴随 CSS 异步加载，确保首屏激活后的视觉风格与 SSR 页面保持高度统一

错误捕获建议

在 Nuxt 的 useFetch 拦截器或 onError 钩子中，可以直接使用 YhMessage.error 来为用户提供友好的服务端报错信息提示。

调用方式

YhMessage 支持多种调用方式，可以根据项目需求选择合适的方式。

组合式 API（推荐）

在 <script setup> 中直接导入使用：

<template>
  <yh-button @click="showMessage">显示消息</yh-button>
</template>

<script setup lang="ts">
import { YhMessage } from '@yh-ui/yh-ui'

const showMessage = () => {
  YhMessage.success('这是一条成功消息')
}
</script>

选项式 API

YH-UI 为 app.config.globalProperties 添加了全局方法 $message，在选项式 API 中可以使用 this.$message 调用：

<template>
  <yh-button @click="showMessage">显示消息</yh-button>
</template>

<script>
export default {
  methods: {
    showMessage() {
      this.$message.success('这是一条成功消息')
    }
  }
}
</script>

单独引用

import { YhMessage } from '@yh-ui/yh-ui'

API

方法

方法名	说明	参数
YhMessage	显示消息	options | string
YhMessage.success	显示成功消息	options | string
YhMessage.warning	显示警告消息	options | string
YhMessage.info	显示信息消息	options | string
YhMessage.error	显示错误消息	options | string
YhMessage.closeAll	关闭所有消息	-

Props

属性名	说明	类型	默认值
message	消息内容。当前模板只会把 props 里的内容按纯文本或 HTML 处理，虽然类型里声明了 VNode，但当前实现不会把该 props 作为 vnode 渲染。	string | VNode	undefined
type	消息类型	'success' | 'warning' | 'info' | 'error'	'info'
icon	自定义图标 props。类型已声明，但当前实现并不会消费它；如需自定义图标请使用 icon 插槽。	string | VNode	undefined
show-close	是否显示关闭按钮	boolean	false
duration	显示时间（毫秒），设为 0 不自动关闭	number	3000
offset	组件实例使用的偏移量。通过服务式 API 调用时，未传入时顶部系列位置从 64 开始，底部系列位置从 20 开始。	number	20
dangerously-use-html-string	是否将 message 作为 HTML 片段处理	boolean	false
center	是否居中显示	boolean	false
on-close	关闭时触发的回调。	() => void	undefined
z-index	z-index 层级	number	—
custom-class	自定义类名	string	—
grouping	是否支持分组合并	boolean	false
repeat-num	分组消息的重复计数，主要由服务实现维护。	number	undefined
placement	消息展示位置	'top' | 'top-left' | 'top-right' | 'bottom' | 'bottom-left' | 'bottom-right'	'top'
theme-overrides	组件级主题覆盖变量。	ComponentThemeVars	undefined

Events

事件名	说明	参数
destroy	离场过渡结束后触发。	() => void

Slots

插槽名	说明
default	自定义消息内容。
icon	自定义图标内容。

Expose

调用 YhMessage 会返回当前 Message 的实例。如果需要手动关闭实例，可以调用它的 close 方法。

方法名	说明	类型
close	关闭当前 Message	() => void
visible	当前可见状态	Ref<boolean>

主题变量

变量名	说明	默认值
--yh-message-bg-color	背景颜色	var(--yh-bg-color-overlay)
--yh-message-border-color	边框颜色	var(--yh-border-color-lighter)
--yh-message-shadow	阴影	var(--yh-shadow-lg)
--yh-message-text-color	文字颜色	var(--yh-text-color-primary)
--yh-message-close-color	关闭按钮颜色	var(--yh-text-color-secondary)
--yh-message-close-hover-color	关闭按钮悬停颜色	var(--yh-text-color-primary)

类型导出

名称	说明
YhMessageProps	内部 Message 组件 Props 类型
YhMessageEmits	内部 Message 组件事件类型
YhMessageSlots	内部 Message 组件插槽类型
YhMessageExpose	内部 Message 组件 Expose 类型
YhMessageInstance	单条消息的公开实例类型
YhMessageOptions	YhMessage(...) 服务配置类型
YhMessageHandler	返回的处理器类型
YhMessageContext	内部运行时上下文类型
YhMessageFn	消息函数签名类型
YhMessageType	消息类型联合类型
YhMessagePlacement	消息展示位置联合类型