Skip to content

Notification 通知 ​

悬浮出现在页面角落,显示全局的通知提醒消息。

基础用法 ​

通知组件适合用于系统级通知的被动提醒。

基础用法

不同状态 ​

用来显示「成功、警告、消息、错误」类的系统通知。

不同状态

自定义弹出位置 ​

使用 position 属性可以设置通知弹出的位置。

自定义弹出位置

自定义时长 ​

设置 duration 属性为 0 可以让通知不自动关闭。

自定义时长

使用 HTML 片段 ​

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

警告

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

使用 HTML 片段

隐藏关闭按钮 ​

设置 showClose 为 false 可以隐藏关闭按钮。

隐藏关闭按钮

限制数量 ​

使用 max 属性可以限制同一位置最多显示的通知数量。当超过限制时,会自动关闭最早的通知。

限制数量

函数形式的 message 2.8.0 ​

message 可以是 VNode,支持返回值为 VNode 的函数。

警告

message 属性虽然支持传入 HTML 片段,但是动态渲染任意 HTML 是非常危险的,因为很容易导致 XSS 攻击。 因此在 dangerouslyUseHTMLString 打开的情况下,请确保 message 的内容是可信的,永远不要将用户提交的内容赋值给 message 属性。

函数形式的 message

在 Nuxt 中使用 ​

Notification 组件与 Nuxt 3/4 深度集成。作为指令式组件,它会自动识别服务端/客户端环境,确保通知弹窗仅在客户端浏览器中执行,避免 SSR 阶段的报错。

Nuxt 中使用

SSR 注意事项:

  • ✅ 安全环境识别:函数内部已封装环境检测,在 Nuxt 的 setup 或生命周期中调用是安全的
  • ✅ 自动导入:在 Nuxt 项目中,YhNotification 函数会被自动扫描并导入,无需额外手动 import
  • ✅ 样式预加载:组件样式会随 Nuxt 页面渲染自动注入,确保弹出时的视觉效果符合预期
  • ⚠️ 服务端限制:在 useAsyncData 或服务端 Middleware 中调用此函数不会有任何视觉输出(因为没有 DOM)
  • 💡 全局方法:Nuxt 插件会自动将 $notify 挂载到全局,你也可以在选项式组件中通过 this.$notify 调用

错误日志集成

结合 Nuxt 的 app:error 钩子,你可以使用 YhNotification.error 来捕获并展示全局未处理的运行时错误。

调用方式 ​

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

组合式 API Hook (useNotification) ​

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

vue
<template>
  <yh-button @click="showNotification">显示通知</yh-button>
</template>

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

const notification = useNotification()

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

组合式 API (直接导入) ​

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

vue
<template>
  <yh-button @click="showNotification">显示通知</yh-button>
</template>

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

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

选项式 API ​

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

vue
<template>
  <yh-button @click="showNotification">显示通知</yh-button>
</template>

<script>
export default {
  methods: {
    showNotification() {
      this.$notify.success('成功', '操作成功!')
    }
  }
}
</script>

单独引用 ​

typescript
import { YhNotification } from '@yh-ui/yh-ui'

API ​

方法 ​

方法名说明参数
YhNotification显示通知options
YhNotification.success显示成功通知(title, message | options)
YhNotification.warning显示警告通知(title, message | options)
YhNotification.info显示信息通知(title, message | options)
YhNotification.error显示错误通知(title, message | options)
YhNotification.closeAll关闭所有通知-

Props ​

属性名说明类型默认值
title标题文本。stringundefined
message通知内容string | VNode | (() => VNode)—
type通知类型'success' | 'warning' | 'info' | 'error'—
icon自定义图标 props。类型已声明,但当前模板不会直接渲染该 props 的值;如需自定义图标请使用 icon 插槽。string | VNodeundefined
showClose是否显示关闭按钮booleantrue
duration显示时间(毫秒),设为 0 不自动关闭number4500
offset距离窗口边缘的偏移量(px)number16
position弹出位置'top-right' | 'top-left' | 'top-center' | 'bottom-right' | 'bottom-left' | 'bottom-center''top-right'
dangerouslyUseHTMLString是否将 message 作为 HTML 片段处理booleanfalse
onClose关闭时的回调函数() => void—
onClick点击通知时的回调函数() => void—
zIndexz-index 层级number—
customClass自定义类名string—
max同一位置允许存在的最大通知数。超出时会先关闭该位置最早创建的通知。numberundefined
theme-overrides组件级主题覆盖变量。ComponentThemeVarsundefined

Events ​

事件名说明参数
destroy离场过渡结束后触发。() => void
click点击通知根节点时触发。() => void

返回值 ​

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

方法说明
close关闭当前 Notification
typescript
const handler = YhNotification.success('成功', '消息内容')

// 手动关闭
handler.close()

Slots ​

插槽名说明
default自定义内容区域
icon自定义图标区域

Expose ​

名称说明类型
visible通知可见状态Ref<boolean>
close关闭当前通知() => void

主题变量 ​

Notification 组件当前实际消费的专属 CSS 变量如下:

变量名说明默认值
--yh-notification-bg-color背景颜色var(--yh-bg-color-overlay)
--yh-notification-border-color边框颜色var(--yh-border-color-lighter)
--yh-notification-shadow阴影var(--yh-shadow-lg)
--yh-notification-title-color标题颜色var(--yh-text-color-primary)
--yh-notification-content-color内容颜色var(--yh-text-color-regular)

类型导出 ​

名称说明
YhNotificationProps内部 Notification 组件 Props 类型
YhNotificationEmits内部 Notification 组件事件类型
YhNotificationSlots内部 Notification 组件插槽类型
YhNotificationExpose内部 Notification 组件 Expose 类型
YhNotificationInstance单条通知的公开实例类型
YhNotificationOptionsYhNotification(...) 服务配置类型
YhNotificationHandler返回的处理器类型
YhNotificationContext内部运行时上下文类型
YhNotificationFn通知函数签名类型
YhNotificationType通知类型联合类型
YhNotificationPosition通知位置联合类型

Released under the MIT License.