shanghai-residences/src/components/toast

Toast 提示组件

通用的 Toast 提示组件，支持多种类型、位置和自定义配置。无需 Provider 包裹，可直接使用。

功能特性

• ✅ 支持 4 种类型：success、error、warning、info
• ✅ 支持 7 个位置：top-left、top-center、top-right、center、bottom-left、bottom-center、bottom-right
• ✅ 自动消失和手动关闭
• ✅ 多个提示同时显示
• ✅ 流畅的动画效果（基于 framer-motion）
• ✅ 支持自定义图标和样式
• ✅ TypeScript 类型支持
• ✅ 无需 Provider，直接使用

快速开始

基本使用

import { toast } from "@/components";

// 显示成功提示
toast.success("操作成功！");

// 显示错误提示
toast.error("操作失败，请重试");

// 显示警告提示
toast.warning("请注意");

// 显示信息提示
toast.info("这是一条提示信息");

全局配置（可选）

import { toast } from "@/components";

// 配置默认位置和最大显示数量
toast.config({
  defaultPosition: "top-right",
  maxCount: 5,
});

详细用法

1. 显示自定义提示

import { toast } from "@/components";

toast.show({
  type: "info",
  title: "自定义标题",
  message: "这是一条自定义提示信息",
  duration: 3000, // 3秒后自动关闭，0 表示不自动关闭
  closable: true, // 是否显示关闭按钮
  position: "center", // 位置：center 表示屏幕中间
  onClose: () => {
    console.log("提示已关闭");
  },
});

2. 使用 ReactNode 作为消息内容

import { toast } from "@/components";

toast.success(
  <div>
    <strong>操作成功！</strong>
    <p>您的数据已保存</p>
  </div>
);

3. 自定义图标

import { toast } from "@/components";
import { CheckCircle } from "lucide-react";

toast.show({
  type: "success",
  message: "自定义图标",
  icon: <CheckCircle className="w-6 h-6" />,
});

4. 手动关闭提示

import { toast } from "@/components";

// 显示提示并保存 ID
const toastId = toast.success("这条提示可以手动关闭");

// 3秒后手动关闭
setTimeout(() => {
  toast.close(toastId);
}, 3000);

// 关闭所有提示
toast.closeAll();

5. 在非 React 组件中使用

// 可以在任何地方使用，包括工具函数、事件处理器等
import { toast } from "@/components";

export function handleApiError(error: Error) {
  toast.error(`请求失败: ${error.message}`);
}

API 参考

toast 对象

方法	说明	参数
config	全局配置	{ defaultPosition?: ToastPosition, maxCount?: number }
show	显示自定义提示	ToastOptions
success	显示成功提示	message: string | ReactNode, options?: Omit<ToastOptions, "type" | "message">
error	显示错误提示	message: string | ReactNode, options?: Omit<ToastOptions, "type" | "message">
warning	显示警告提示	message: string | ReactNode, options?: Omit<ToastOptions, "type" | "message">
info	显示信息提示	message: string | ReactNode, options?: Omit<ToastOptions, "type" | "message">
close	关闭指定提示	id: string
closeAll	关闭所有提示	-

ToastOptions

属性	类型	默认值	说明
type	ToastType	"info"	提示类型：success、error、warning、info
title	string	-	标题
message	string | ReactNode	-	消息内容（必填）
duration	number	3000	持续时间（毫秒），0 表示不自动关闭
closable	boolean	true	是否显示关闭按钮
icon	ReactNode	-	自定义图标
position	ToastPosition	-	位置（继承自全局配置的 defaultPosition）
onClose	() => void	-	关闭回调
className	string	-	自定义类名

toast.config() 配置项

属性	类型	默认值	说明
defaultPosition	ToastPosition	"top-right"	默认位置
maxCount	number	5	最大显示数量

类型定义

type ToastType = "success" | "error" | "warning" | "info";
type ToastPosition =
  | "top-left"
  | "top-center"
  | "top-right"
  | "center"
  | "bottom-left"
  | "bottom-center"
  | "bottom-right";

样式定制

组件使用 Tailwind CSS，支持通过 className 属性自定义样式。默认支持深色模式。

向后兼容

为了保持向后兼容，仍然支持旧的 useToast Hook 和 ToastProvider，但不推荐使用：

// 旧方式（不推荐，但仍然支持）
import { useToast, ToastProvider } from "@/components";

// 新方式（推荐）
import { toast } from "@/components";

注意事项

1. 无需 Provider：直接使用 toast 对象，无需在应用根组件包裹 Provider
2. 自动初始化：首次调用时会自动创建 Toast 容器
3. 位置分组：提示会自动根据位置分组显示
4. 数量限制：超过 maxCount 数量的提示会被自动移除（保留最新的）
5. 动画效果：提示关闭时会先触发动画，然后从 DOM 中移除
6. SSR 支持：组件会自动检测运行环境，在服务端不会渲染

迁移指南

从旧版本迁移

旧版本（需要 Provider）：

// App.tsx
<ToastProvider>
  <App />
</ToastProvider>;

// Component.tsx
const toast = useToast();
toast.success("成功！");

新版本（直接使用）：

// 任何地方直接使用
import { toast } from "@/components";
toast.success("成功！");

只需删除 ToastProvider 包裹，并将 useToast() 改为直接使用 toast 对象即可。