Toast 轻提示

新粗野主义风格通知提示系统，提供 useToast 组合式函数、5 种变体和 ToastContainer 用于渲染。

预览

Preview

变体

尺寸

悬停暂停（pauseOnHover）

将鼠标悬停在提示上可暂停倒计时与进度条，移出后从剩余时间继续。点击下方按钮显示一条 10 秒提示进行体验，可切换开关对比行为。

安装

pnpm dlx brutx-vue@latest add toast

用法

<script setup>
import { ToastContainer } from 'brutx-ui-vue'
</script>

<template>
    <router-view />
    <ToastContainer />
</template>

使用 useToast

<script setup>
import { useToast } from 'brutx-ui-vue'

const { success, error, warning, info, addToast } = useToast()

function handleSave() {
    success('Saved!', 'Your changes have been saved.')
}

function handleError() {
    error('Error', 'Something went wrong. Please try again.')
}
</script>

<template>
    <button @click="handleSave">Save</button>
    <button @click="handleError">Trigger Error</button>
</template>

自定义提示

<script setup>
import { useToast } from 'brutx-ui-vue'

const { addToast } = useToast()

function showCustomToast() {
    addToast({
        variant: 'warning',
        title: 'Warning',
        description: 'Your session will expire in 5 minutes.',
        duration: 10000,
    })
}
</script>

悬停暂停

Toast 默认启用 pauseOnHover（默认值 true）：鼠标移入提示时暂停倒计时与顶部进度条动画，移出后从剩余时间继续，便于用户阅读较长内容。设置 :pause-on-hover="false" 可禁用该行为。

注意：pauseOnHover 是 <Toast> 组件自身的 prop，不通过 useToast 的 addToast / ToastItem 传递。在自定义 ToastContainer 渲染 <Toast> 时直接绑定即可。

<script setup>
import { useToast, ToastContainer, Toast } from 'brutx-ui-vue'

const { toasts, addToast, removeToast } = useToast()
</script>

<template>
    <ToastContainer position="bottom-right">
        <Toast
            v-for="toast in toasts"
            :key="toast.id"
            :duration="toast.duration"
            :pause-on-hover="true"
            @close="removeToast(toast.id)"
        />
    </ToastContainer>

    <button @click="addToast({ title: '悬停我', description: '将鼠标移到提示上可暂停倒计时。', duration: 10000 })">
        显示可暂停提示
    </button>
</template>

变体

变体	背景	图标
default	bg-brutal-bg	Zap
success	bg-brutal-success	CheckCircle
error	bg-brutal-destructive	AlertCircle
warning	bg-brutal-accent	AlertTriangle
info	bg-brutal-secondary	Info

所有变体统一使用 text-brutal-fg 文字颜色和 shadow-brutal-lg 阴影。

尺寸

尺寸	宽度
sm	w-72 (288px)
default	w-80 (320px)
lg	w-96 (384px)

数据类型

ToastItem

interface ToastItem {
    id: string
    variant?: 'default' | 'success' | 'error' | 'warning' | 'info'
    size?: 'sm' | 'default' | 'lg'
    title?: string
    description?: string
    duration?: number
}

PromiseToastOptions

interface PromiseToastOptions<T> {
    loading: string                                        // loading 状态文本
    success: string | ((data: T) => string)                // 成功文本或格式化函数
    error: string | ((error: Error) => string)             // 错误文本或格式化函数
    duration?: number                                      // 成功/错误后显示时长
    loadingVariant?: 'default' | 'success' | 'error' | 'warning' | 'info'  // loading 状态变体
    successVariant?: 'default' | 'success' | 'error' | 'warning' | 'info'  // 成功状态变体
    errorVariant?: 'default' | 'success' | 'error' | 'warning' | 'info'    // 错误状态变体
}

组合式函数

useToast

import { useToast } from 'brutx-ui-vue'

const {
    toasts,          // Ref<ToastItem[]> - 响应式提示列表
    addToast,        // (toast: Omit<ToastItem, 'id'>) => string
    removeToast,     // (id: string) => void
    clearToasts,     // () => void
    clearAllTimers,  // () => void
    success,         // (title: string, description?: string) => string
    error,           // (title: string, description?: string) => string
    warning,         // (title: string, description?: string) => string
    info,            // (title: string, description?: string) => string
    promise,         // <T>(promise: Promise<T> | (() => Promise<T>), options: PromiseToastOptions<T>) => Promise<T>
} = useToast()

返回值

属性	类型	说明
toasts	Ref<ToastItem[]>	响应式提示列表
addToast	(toast: Omit<ToastItem, 'id'>) => string	添加自定义提示，返回提示 ID
removeToast	(id: string) => void	移除指定提示
clearToasts	() => void	清除所有提示
clearAllTimers	() => void	清除所有定时器
success	(title: string, description?: string) => string	显示成功提示
error	(title: string, description?: string) => string	显示错误提示
warning	(title: string, description?: string) => string	显示警告提示
info	(title: string, description?: string) => string	显示信息提示
promise	<T>(promise: Promise<T> | (() => Promise<T>), options: PromiseToastOptions<T>) => Promise<T>	自动追踪 Promise 状态

provideToast

在应用根组件调用 provideToast() 提供 toast 实例，子组件中 useToast() 会自动注入该实例。

<!-- App.vue -->
<script setup>
import { provideToast } from 'brutx-ui-vue'

provideToast()
</script>

注意：若未调用 provideToast()，useToast() 会回退到共享单例并输出警告。生产应用推荐在根组件显式调用 provideToast()；共享单例仅作为兼容兜底。测试、多应用同页或热更新场景可调用 destroyBrutxFallbacks() 集中清理 toast/theme/message 的 fallback 状态。

Promise Toast

自动追踪 Promise 状态，显示 loading → success/error 流程：

<script setup>
import { useToast } from 'brutx-ui-vue'

const { promise } = useToast()

async function handleSave() {
    await promise(saveData(), {
        loading: '保存中...',
        success: '保存成功！',
        error: '保存失败，请重试',
    })
}
</script>

API 参考

Toast

Toast — 属性

名称	类型	默认值	说明
variant	"default" | "error" | "info" | "success" | "warning" | undefined	"default"	设置提示的语义和视觉类型，如成功、警告、信息或错误。
详情 声明类型 NonNullable<"default" | "success" | "warning" | "info" | "error" | null | undefined> | undefined 字面量 "default" "error" "info" "success" "warning" 默认值详情 声明 'default' 来源: packages/ui/src/components/toast/Toast.vue 解析值 "default" 来源 Toast.vue:17 packages/ui/src/components/toast/Toast.vue
size	"default" | "lg" | "sm" | undefined	"default"	设置提示容器的尺寸变体。
详情 声明类型 NonNullable<"default" | "lg" | "sm" | null | undefined> | undefined 字面量 "default" "lg" "sm" 默认值详情 声明 'default' 来源: packages/ui/src/components/toast/Toast.vue 解析值 "default" 来源 Toast.vue:18 packages/ui/src/components/toast/Toast.vue
title	string | undefined	undefined	提示标题文字；省略时不渲染标题区域。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/toast/Toast.vue 解析值 undefined 来源 Toast.vue:19 packages/ui/src/components/toast/Toast.vue
description	string | undefined	undefined	提示正文说明文字；省略时不渲染描述区域。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/toast/Toast.vue 解析值 undefined 来源 Toast.vue:20 packages/ui/src/components/toast/Toast.vue
duration	number | undefined	5000	提示自动关闭前的显示时长，单位为毫秒；设为 0 时不自动关闭。
详情 声明类型 number | undefined 默认值详情 声明 DEFAULT_TOAST_DURATION 来源: packages/ui/src/components/toast/Toast.vue 解析值 5000 来源 Toast.vue:21 packages/ui/src/components/toast/Toast.vue
pauseOnHover	boolean | undefined	true	鼠标悬停时暂停自动关闭计时和进度动画，离开后继续剩余计时。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 true 来源: packages/ui/src/components/toast/Toast.vue 解析值 true 来源 Toast.vue:22 packages/ui/src/components/toast/Toast.vue
class	string | undefined	undefined	追加到提示根容器的 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/toast/Toast.vue 解析值 undefined 来源 Toast.vue:23 packages/ui/src/components/toast/Toast.vue
iconSize	IconSize | undefined	"xl"	设置类型图标的尺寸。
详情 声明类型 IconSize | undefined 字面量 "2xl" "lg" "md" "sm" "xl" "xs" 关联类型 IconSize 类型定义 — IconSize export type IconSize = NonNullable<VariantProps<typeof iconSizeVariants>['size']> 默认值详情 声明 'xl' 来源: packages/ui/src/components/toast/Toast.vue 解析值 "xl" 来源 Toast.vue:24 packages/ui/src/components/toast/Toast.vue
count	number | undefined	1	显示同类提示聚合数量；大于 1 时呈现计数标记。
详情 声明类型 number | undefined 默认值详情 声明 1 来源: packages/ui/src/components/toast/Toast.vue 解析值 1 来源 Toast.vue:25 packages/ui/src/components/toast/Toast.vue

Toast — 事件

名称	签名或类型	说明
@close	[]	提示离场动画完成后发出，用于通知调用方移除该提示。
详情 声明类型 [] 来源 Toast.vue packages/ui/src/components/toast/Toast.vue

Toast — 插槽

名称	签名或类型	说明
#default	{}	显示在标题和描述之后的自定义补充内容。
详情 声明类型 {} 来源 Toast.vue packages/ui/src/components/toast/Toast.vue

ToastContainer

ToastContainer — 属性

名称	类型	默认值	说明
position	ToastPosition | undefined	"bottom-right"	设置提示容器在视口中的预设位置，或通过 x、y 和 anchor 指定偏移位置。
详情 声明类型 ToastPosition | undefined 字面量 "bottom-center" "bottom-left" "bottom-right" "top-center" "top-left" "top-right" 关联类型 ToastPosition 类型定义 — ToastPosition export type ToastPosition = | 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' | { x: number; y: number; anchor?: 'top-left' | 'bottom-left' | 'top-right' | 'bottom-right' } 默认值详情 声明 'bottom-right' 来源: packages/ui/src/components/toast/ToastContainer.vue 解析值 "bottom-right" 来源 ToastContainer.vue:22 packages/ui/src/components/toast/ToastContainer.vue
stack	ToastStackOptions | undefined	{ "expandDirection": "down", "gap": 12, "maxVisible": 5 } 按实例调用工厂函数	设置可见提示数量上限、提示间距以及容器展开方向。
详情 声明类型 ToastStackOptions | undefined 关联类型 ToastStackOptions 类型定义 — ToastStackOptions export interface ToastStackOptions { maxVisible?: number gap?: number expandDirection?: 'down' | 'up' } 默认值详情 声明 () => ({ maxVisible: DEFAULT_TOAST_MAX_VISIBLE, gap: DEFAULT_TOAST_GAP_PX, expandDirection: DEFAULT_EXPAND_DIRECTION, }) 来源: packages/ui/src/components/toast/ToastContainer.vue 解析值 { "expandDirection": "down", "gap": 12, "maxVisible": 5 } 来源 ToastContainer.vue:23 packages/ui/src/components/toast/ToastContainer.vue
class	string | undefined	undefined	追加到固定定位提示容器的 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/toast/ToastContainer.vue 解析值 undefined 来源 ToastContainer.vue:24 packages/ui/src/components/toast/ToastContainer.vue

ToastContainer — 插槽

名称	签名或类型	说明
#default	{}	自定义容器内容；提供时由调用方渲染和管理提示列表，未提供时容器自动渲染 useToast 中的提示。
详情 声明类型 {} 来源 ToastContainer.vue packages/ui/src/components/toast/ToastContainer.vue

可访问性

• 键盘操作：支持 Escape 关闭当前提示
• ARIA 属性：Toast 容器使用 role="status" 和 aria-live="polite" 通知屏幕阅读器
• 动效降级：尊重 prefers-reduced-motion 系统设置，自动禁用或简化动画