Toast

基础反馈

基于 Bootstrap 5 的 Toast 轻量通知组件，支持页眉/正文结构、堆叠显示、九种容器方位、颜色变体与自动隐藏（悬停暂停），过渡动画由 useReducer 驱动并支持减少动态效果偏好

Component Demo

Basic usage and examples of the Toast component

基础用法

堆叠显示

看到我了吗？这是一条 Toast 消息。

第二条消息堆叠在下方。

位置控制

演示区域

颜色变体

Hello, world! This is a toast message.

自动隐藏

自定义内容

API Documentation

Complete API reference for the Toast component

Props

Common Props

属性名	类型	默认值	描述
`autohide`	`boolean`	`true`	是否在 `delay` 毫秒后自动隐藏，鼠标悬停在 Toast 上时暂停计时，移出后重新计时
`delay`	`number`	`5000`	自动隐藏延时（毫秒），`autohide` 为 `false` 时忽略
`duration`	`number`	`300`	显示与隐藏过渡动画时长（毫秒），系统开启减少动态效果时自动为 0
`show`	`boolean`	-	受控的显示状态，为 `false` 时播放退出动画后卸载；未提供时组件自行管理（初始显示）
`onClose`	`() => void`	-	请求关闭回调，由关闭按钮或自动隐藏触发，受控模式下由使用者更新 `show`
`variant`	`ToastVariant`	-	颜色变体，对应 Bootstrap 的 `text-bg-*` 工具类
`role`	`AriaRole`	`'alert'`	无障碍角色，不重要的通知可改为 `"status"`
`aria-live`	`'assertive' \| 'off' \| 'polite'`	`'assertive'`	无障碍实时区域属性，通知整个 Toast 的变更
`aria-atomic`	`boolean`	`true`	无障碍原子性，确保 Toast 内容作为整体被读屏软件播报
`children`	`ReactNode`	-	Toast 内容，配合 `ToastHeader`、`ToastBody` 等子组件使用
`className`	`string`	-	自定义类名
`...rest`	`HTMLAttributes`	-	透传原生 div 元素的所有属性（如 `onClick`、`onMouseEnter` 等）

ToastContainer

属性名	类型	默认值	描述
`position`	`ToastPosition`	`'absolute'`	容器定位方式，`static` 用于将多条 Toast 堆叠在文档流中，`fixed` 用于固定到视口
`placement`	`ToastPlacement`	-	容器方位（左上、顶部居中、右上、左中、居中、右中、左下、底部居中、右下），映射为 Bootstrap 定位工具类；未提供时需自行通过 `className` 指定位置
`children`	`ReactNode`	-	容器内容，通常为一条或多条 `Toast`
`className`	`string`	-	自定义类名
`...rest`	`HTMLAttributes`	-	透传原生 div 元素的所有属性（如 `aria-live` 等）

ToastHeader

属性名	类型	默认值	描述
`closeButton`	`boolean`	`true`	是否渲染关闭按钮
`closeLabel`	`string`	`'Close'`	关闭按钮的无障碍标签
`children`	`ReactNode`	-	页眉内容，如标题、时间等
`className`	`string`	-	自定义类名
`...rest`	`HTMLAttributes`	-	透传原生 div 元素的所有属性

ToastBody

属性名	类型	默认值	描述
`children`	`ReactNode`	-	正文内容
`className`	`string`	-	自定义类名
`...rest`	`HTMLAttributes`	-	透传原生 div 元素的所有属性

ToastClose

属性名	类型	默认值	描述
`aria-label`	`string`	`'Close'`	无障碍标签
`type`	`string`	`'button'`	按钮类型
`onClick`	`MouseEventHandler<HTMLButtonElement>`	-	点击关闭按钮时触发的额外回调
`children`	`ReactNode`	-	按钮内容
`className`	`string`	-	自定义类名
`...rest`	`ButtonHTMLAttributes`	-	透传原生 button 元素的所有属性

Type Definitions

ToastVariant

Toast 颜色变体类型

export type ToastVariant =
  'danger' | 'dark' | 'info' | 'light' | 'primary' | 'secondary' | 'success' | 'warning';

ToastPlacement

Toast 容器方位类型

export type ToastPlacement =
  | 'bottom-center'
  | 'bottom-end'
  | 'bottom-start'
  | 'middle-center'
  | 'middle-end'
  | 'middle-start'
  | 'top-center'
  | 'top-end'
  | 'top-start';

ToastPosition

Toast 容器定位方式类型

export type ToastPosition = 'absolute' | 'fixed' | 'static';

ToastAnimationStatus

Toast 过渡动画状态类型

export type ToastAnimationStatus = 'closed' | 'closing' | 'opened' | 'opening';

ToastProps

Toast 组件属性接口

export interface ToastProps extends HTMLAttributes<HTMLDivElement> {
  autohide?: boolean;
  children?: ReactNode;
  className?: string;
  delay?: number;
  duration?: number;
  onClose?: () => void;
  role?: AriaRole;
  show?: boolean;
  variant?: ToastVariant;
}

ToastContainerProps

Toast 容器组件属性接口

export interface ToastContainerProps extends HTMLAttributes<HTMLDivElement> {
  children?: ReactNode;
  className?: string;
  placement?: ToastPlacement;
  position?: ToastPosition;
}

ToastHeaderProps

Toast 页眉组件属性接口

export interface ToastHeaderProps extends HTMLAttributes<HTMLDivElement> {
  children?: ReactNode;
  className?: string;
  closeButton?: boolean;
  closeLabel?: string;
}

ToastBodyProps

Toast 正文组件属性接口

export interface ToastBodyProps extends HTMLAttributes<HTMLDivElement> {
  children?: ReactNode;
  className?: string;
}

ToastCloseProps

Toast 关闭按钮组件属性接口

export interface ToastCloseProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  children?: ReactNode;
  className?: string;
}

ToastContextValue

Toast 上下文，供 ToastHeader、ToastClose 等子组件消费

export interface ToastContextValue {
  close: () => void;
  status: ToastAnimationStatus;
  variant?: ToastVariant;
}