Toaster / toast

Toast 通知系统,基于 vue-sonner 封装。<Toaster /> 负责挂载容器,toast() 是命令式 API。

Anatomy

• Toaster挂载点,必须在应用根部渲染一次(推荐放在 App.vue / 根布局)
• toast命令式 API,可在任意组件 / 业务代码中调用以触发通知

必须挂载 Toaster

Vue 3 项目需要在 App.vue 或根布局手动渲染一次 <Toaster />。Nuxt 项目可通过 @tripo3d/design/nuxt 模块自动注入。

基本用法

本文档站已在根布局挂载了一份全局 <Toaster />,下方 demo 直接调用 toast() 即可看到效果。

默认通知

顶部居中(position='top-center')出现。

<script setup lang="ts">
import { Button, Toaster, toast } from '@tripo3d/design';
</script>

<template>
  <!-- 应用根部只需挂载一次 -->
  <Toaster />
  <Button @click="toast('操作成功')">触发默认</Button>
</template>

变体

语义化变体

success / error / warning / info / loading 均为 toast() 的方法。

<Button @click="toast.success('上传完成')">success</Button>
<Button @click="toast.error('网络错误')">error</Button>
<Button @click="toast.warning('低电量')">warning</Button>
<Button @click="toast.info('有新版本')">info</Button>
<Button @click="toast.loading('加载中...')">loading</Button>

Promise 通知

toast.promise

跟踪 Promise 生命周期,自动切换 loading / success / error。

<script setup lang="ts">
import { Button, toast } from '@tripo3d/design';

function upload() {
  return new Promise(resolve => setTimeout(resolve, 1500));
}
</script>

<template>
  <Button @click="toast.promise(upload(), {
    loading: '上传中...',
    success: '上传成功',
    error: '上传失败',
  })">
    触发 Promise
  </Button>
</template>

自定义位置

Toaster position

Toaster 组件的 position 控制所有 toast 的出现位置(默认 top-center)。该示例只展示用法,实际位置仍由文档站的全局 Toaster(top-center)决定。

<template>
  <Toaster position="bottom-right" />
  <Button @click="toast('右下角 toast')">在右下角弹出</Button>
</template>

API

Toaster Props

名称	类型	默认值	说明
position	'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'	'top-center'	所有 toast 的出现位置
class	string	—	挂载容器的额外 class

其余 props 透传至 vue-sonner ToasterProps(已内置 offset=72、mobile-offset=24 与默认样式)。

toast 命令式 API

方法	签名	说明
toast	(message, options?) => id	基础通知
toast.success	(message, options?) => id	成功样式
toast.error	(message, options?) => id	错误样式
toast.warning	(message, options?) => id	警告样式(背景红色)
toast.info	(message, options?) => id	信息样式
toast.loading	(message, options?) => id	加载态,会持续显示直到被 dismiss
toast.promise	(promise, { loading, success, error })	跟踪 Promise,自动切换 loading / success / error
toast.dismiss	(id?) => void	关闭指定 id 或全部 toast

可访问性

• 默认 aria-live="polite" 由 vue-sonner 管理,屏幕阅读器会朗读通知内容
• 错误类(toast.error)会使用 aria-live="assertive" 确保被及时播报
• 所有 toast 支持鼠标 hover 暂停自动关闭,支持键盘关闭