Toast 组件概述

Toast 用于在页面中以临时浮层的形式向用户提供操作反馈或事件提示，支持自动关闭、拖拽关闭、Promise 集成等高级交互。

---

安装

npm install @heroui/toast
# 或
yarn add @heroui/toast
# pnpm / bun 同理

若已全局安装 @heroui/react，此步可跳过。

---

引入

import { ToastProvider, addToast, closeAll, Toast } from '@heroui/toast'

• ToastProvider：初始化上下文，必须在根组件包裹后才可使用 addToast。
• addToast(options)：新增一条 Toast；
• closeAll()：关闭所有当前可见的 Toast；
• <Toast />：底层组件，通常无需手动使用。

---

基本使用

<ToastProvider maxVisibleToasts={3} placement="bottom-right">
  <Button
    onPress={() => {
      addToast({
        title: '操作成功',
        description: '文件已上传',
        color: 'success',
      })
    }}
  >
    显示 Toast
  </Button>
</ToastProvider>

• maxVisibleToasts（默认 3）：最多同时显示的 Toast 数量；
• placement（默认 "bottom-right"）：Toast 出现的位置。

---

API 详情

ToastProviderProps

属性	类型	默认值	说明
maxVisibleToasts	number	3	最大可见 Toast 数
placement	"bottom-right" | ... | "top-center"	"bottom-right"	出现位置
disableAnimation	boolean	false	是否禁用动画
toastOffset	number	0	与视口边缘的偏移量（px）
toastProps	ToastProps	—	传递给所有 Toast 的全局 Prop
regionProps	ToastRegionProps	—	自定义 ToastRegion 属性

来源：toast-provider.tsx

---

核心函数

• addToast(opts: ToastProps & ToastOptions): void
• closeAll(): void

  来源：toast-provider.tsx

---

ToastProps

属性	类型	默认值	说明
title	ReactNode	—	标题
description	ReactNode	—	描述文字
color	"default" | "primary" | ... | "danger"	"default"	颜色主题
severity	同 color	"default"	严重性，用于自动映射默认图标
variant	"solid" | "bordered" | "flat"	"flat"	视觉风格
radius	"none" | "sm" | ... | "full"	"md"	圆角
timeout	number	6000	自动关闭时间（ms）
shouldShowTimeoutProgress	boolean	false	是否显示自动关闭进度条
promise	Promise<any>	—	若传入 Promise，完成后自动关闭
icon, loadingIcon	ReactNode	—	自定义主图标 / 加载图标
closeIcon	ReactNode	—	自定义关闭按钮图标
endContent	ReactNode	—	右侧额外内容
hideIcon, hideCloseButton	boolean	false	隐藏图标 / 隐藏关闭按钮
onClose	() => void	—	关闭回调
classNames	Partial<Record<ToastSlots, string>>	—	按 slot 自定义 CSS 类

来源：文档与源码

---

ToastRegionProps

属性	类型	默认值	说明
className	string	—	根节点自定义类名
classNames	Partial<Record<"base", string>>	—	仅支持 base slot

来源：toast-region.tsx

---

数据属性（Data Attributes）

• data-has-title：是否有标题
• data-has-description：是否有描述
• data-animation：当前动画状态 (entering/queued/exiting/undefined)
• data-placement：位置标识
• data-drag-value：拖拽偏移值

  来源：文档

---

Slot 列表

• base / title / description / icon / loadingIcon
• content / motionDiv / progressTrack / progressIndicator
• closeButton / closeIcon

  来源：文档

---

可访问性

• <div role="alert">
• 所有 Toast 渲染于 ToastRegion，当无 Toast 时该区域自动从 DOM 移除
• 关闭按钮默认 aria-label="Close"

  来源：文档

---

示例汇总

1. 基本示例：

   <ToastProvider>
     <Button onPress={() => addToast({ title: '提示', description: '操作完成' })}>
       显示 Toast
     </Button>
   </ToastProvider>

2. Promise 支持：自动展示加载中图标，3s 后关闭

   addToast({
     title: '上传中',
     promise: uploadFile(),
     timeout: 3000,
     shouldShowTimeoutProgress: true,
   })

3. 自定义样式 & 额外内容：

   addToast({
     title: '升级提示',
     endContent: <Button size="sm">升级</Button>,
     classNames: { base: 'bg-background border-l-4 border-warning' },
     color: 'warning',
   })

---