Toasts 全局通知

全局通知组件（Toasts）用于在页面角落展示轻量级消息提示。支持函数式调用 API（toast.success()、toast.error() 等），无需在模板中声明。

注意

使用 Toasts 前，需在应用入口处（如 App.vue）放置 <TToastContainer /> 组件。该组件通过 <Teleport to="body"> 渲染，接受 placement 和 teleportTo 属性。

函数式 API 调用

通过导入的 toast 对象直接调用，无需模板声明。

查看代码

vue


<script setup lang="ts">
  import {toast} from '@gulcc/tabler-vue'

  toast.success('操作已成功完成！')
  toast.error('网络连接失败，请稍后重试。')
  toast.warning('磁盘空间不足，请及时清理。')
  toast.info('系统将于今晚 02:00 进行维护更新。')
</script>

<template>
  <button class="btn btn-success" @click="toast.success('操作成功')">Success</button>
  <button class="btn btn-danger" @click="toast.error('出错了')">Error</button>
  <button class="btn btn-warning" @click="toast.warning('警告')">Warning</button>
  <button class="btn btn-info" @click="toast.info('提示')">Info</button>
</template>

自定义通知

通过 toast.show() 方法可以自定义标题、颜色、图标、自动关闭时长等选项。

查看代码

vue


<script setup lang="ts">
  import {toast} from '@gulcc/tabler-vue'

  toast.show('这是一条自定义通知', {
    title: '通知标题',
    color: 'primary',
    duration: 3000,   // 3 秒后自动关闭
  })
</script>

<template>
  <button class="btn btn-primary" @click="toast.show('消息内容', { title: '标题', duration: 3000 })">
    显示自定义通知
  </button>
</template>

持久通知

设置 duration: 0 使通知不会自动关闭，需要用户手动点击关闭按钮。

查看代码

vue


<script setup lang="ts">
  import {toast} from '@gulcc/tabler-vue'

  toast.show('这条通知不会自动消失', {
    title: '持久通知',
    duration: 0, // 不自动关闭
  })
</script>

带图标通知

通过 icon 属性传入 @tabler/icons-vue 的图标组件。

vue


<script setup lang="ts">
  import {toast} from '@gulcc/tabler-vue'
  import {IconCheck} from '@tabler/icons-vue'

  toast.show('操作已完成', {
    title: '操作结果',
    color: 'success',
    icon: IconCheck,
  })
</script>

清除所有通知

调用 toast.clear() 立即清除所有激活中的通知。

查看代码

vue


<script setup lang="ts">
  import {toast} from '@gulcc/tabler-vue'

  // 显示多条通知
  toast.success('通知 1')
  toast.info('通知 2')
  toast.warning('通知 3')

  // 一键清除
  toast.clear()
</script>

裸风格通知

不带标题和头像的通知会自动使用「裸风格」渲染：无 toast-header 栏，关闭按钮浮动在通知体右上角。

vue


<script setup lang="ts">
  import {toast} from '@gulcc/tabler-vue'

  toast.show('这是一条简洁通知，没有标题栏。')
</script>

重要通知

开启 important 属性可以让通知以实色背景 + 白色文字呈现，与 Alert 的「重要通知」风格一致。适用于最高优先级的系统通知。

查看代码

vue


<script setup lang="ts">
  import {toast} from '@gulcc/tabler-vue'

  // 重要信息
  toast.show('系统将于今晚 02:00 进行维护更新，预计持续 2 小时。', {
    title: '计划维护通知',
    color: 'info',
    duration: 0,
    important: true,
    icon: IconInfoCircle,
  })

  // 重要错误
  toast.show('数据库连接异常，部分功能不可用！', {
    title: '严重错误',
    color: 'danger',
    duration: 0,
    important: true,
    icon: IconAlertCircle,
  })

  // 重要成功（使用快捷方法）
  toast.success('系统升级已完成，所有服务恢复正常运行。', {
    important: true,
    duration: 0,
  })
</script>

悬停暂停

当鼠标移入通知时，自动关闭计时器暂停；鼠标移出计时器继续。这给用户充足的时间阅读消息内容，适用于设置自动关闭时长的通知。

vue


<button class="btn btn-primary" @click="toast.success('试试把鼠标移上来，计时会暂停。', { duration: 3000 })">
  显示测试通知（3秒后关闭）
</button>

放置位置

通过 setToastPlacement() 设置全局默认位置，或在 toast.show() 的 options 中传入 placement 覆盖单个通知的位置。

查看代码

vue


<script setup lang="ts">
  import {toast, setToastPlacement} from '@gulcc/tabler-vue'

  // 全局设置
  setToastPlacement('bottom-right')

  // 单个覆盖
  toast.info('这条通知在左上角', {placement: 'top-left'})
  toast.info('这条通知在右下角', {placement: 'bottom-right'})
</script>

对话风格通知

通过 avatar、sender、timestamp 属性可以呈现类似聊天消息的通知样式。设置 avatar 后，Toast 头部将自动切换为头像 + 发送者 + 时间戳的布局。

查看代码

vue


<script setup lang="ts">
  import {toast} from '@gulcc/tabler-vue'

  // 简单对话 — 带头像、发送者、时间戳
  toast.show('Hello, world! This is a toast message.', {
    avatar: '/public/avatar.png',
    sender: 'Mallory Hulme',
    timestamp: '11 mins ago',
    duration: 0,
  })

  // Cookie 提醒 — 使用 bodyHtml 渲染操作按钮
  toast.show('', {
    avatar: '/public/avatar.png',
    sender: 'Mallory Hulme',
    timestamp: '11 mins ago',
    duration: 0,
    bodyHtml: 'Our site uses cookies. By continuing to use our site, you agree to our Cookie Policy.<div class="mt-2 pt-2 border-top"><a href="#" class="btn btn-primary btn-sm">I understand</a></div>',
  })
</script>

API

`toast` 对象方法

方法	参数	返回值	说明
`toast.show()`	`(message: string, options?: ToastOptions)`	`string`	显示自定义通知，返回通知 ID
`toast.success()`	`(message: string, options?: ToastOptions)`	`string`	显示成功通知（绿色）
`toast.error()`	`(message: string, options?: ToastOptions)`	`string`	显示错误通知（红色）
`toast.warning()`	`(message: string, options?: ToastOptions)`	`string`	显示警告通知（黄色）
`toast.info()`	`(message: string, options?: ToastOptions)`	`string`	显示信息通知（蓝色）
`toast.remove()`	`(id: string)`	`void`	移除指定 ID 的通知
`toast.clear()`	—	`void`	清除所有通知

ToastOptions

参数	类型	默认值	说明
title	`string`	—	通知标题
color	`TablerColor`	方法对应语义色	颜色变体，如 `'success'`、`'danger'`
icon	`Component`	—	图标组件（来自 `@tabler/icons-vue`）
duration	`number`	`5000`	自动关闭延迟（毫秒），`0` 表示不自动关闭
placement	`ToastPlacement`	`'top-right'`	放置位置，覆盖全局默认位置
closable	`boolean`	`true`	是否显示关闭按钮
avatar	`string`	—	头像图片 URL（切换为对话风格头部）
sender	`string`	—	发送者名称（对话风格头部）
timestamp	`string`	—	时间戳文本（对话风格头部）
bodyHtml	`string`	—	主体 HTML 内容（以 `v-html` 渲染）
important	`boolean`	`false`	重要通知（实色背景 + 白色文字）

TToastContainer Props

参数	类型	默认值	说明
placement	`ToastPlacement`	`'top-right'`	Toast 容器放置位置
teleportTo	`string`	`'body'`	Teleport 传送目标选择器

ToastPlacement 类型

值	说明
`'top-right'`	右上角（默认）
`'top-left'`	左上角
`'bottom-right'`	右下角
`'bottom-left'`	左下角
`'top-center'`	顶部居中
`'bottom-center'`	底部居中

Toasts 全局通知 ​

函数式 API 调用 ​

自定义通知 ​

持久通知 ​

带图标通知 ​

清除所有通知 ​

裸风格通知 ​

重要通知 ​

悬停暂停 ​

放置位置 ​

对话风格通知 ​

API ​

toast 对象方法 ​

ToastOptions ​

TToastContainer Props ​

ToastPlacement 类型 ​

Toasts 全局通知

函数式 API 调用

自定义通知

持久通知

带图标通知

清除所有通知

裸风格通知

重要通知

悬停暂停

放置位置

对话风格通知

API

`toast` 对象方法

ToastOptions

TToastContainer Props

ToastPlacement 类型