Skip to content

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 Hook (useMessage) ​

在 <script setup> 中,推荐使用 useMessage 来获取全局 message 服务实例,保持与 Naive UI 等主流组件库 API 一致:

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

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

const message = useMessage()

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

组合式 API (直接导入) ​

您也可以直接导入 YhMessage 函数使用:

vue
<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 调用:

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

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

单独引用 ​

typescript
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 | VNodeundefined
type消息类型'success' | 'warning' | 'info' | 'error''info'
icon自定义图标 props。类型已声明,但当前实现并不会消费它;如需自定义图标请使用 icon 插槽。string | VNodeundefined
show-close是否显示关闭按钮booleanfalse
duration显示时间(毫秒),设为 0 不自动关闭number3000
offset组件实例使用的偏移量。通过服务式 API 调用时,未传入时顶部系列位置从 64 开始,底部系列位置从 20 开始。number20
dangerously-use-html-string是否将 message 作为 HTML 片段处理booleanfalse
center是否居中显示booleanfalse
on-close关闭时触发的回调。() => voidundefined
z-indexz-index 层级number—
custom-class自定义类名string—
grouping是否支持分组合并booleanfalse
repeat-num分组消息的重复计数,主要由服务实现维护。numberundefined
placement消息展示位置'top' | 'top-left' | 'top-right' | 'bottom' | 'bottom-left' | 'bottom-right''top'
theme-overrides组件级主题覆盖变量。ComponentThemeVarsundefined

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单条消息的公开实例类型
YhMessageOptionsYhMessage(...) 服务配置类型
YhMessageHandler返回的处理器类型
YhMessageContext内部运行时上下文类型
YhMessageFn消息函数签名类型
YhMessageType消息类型联合类型
YhMessagePlacement消息展示位置联合类型

Released under the MIT License.