# 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，直接使用

## 快速开始

### 基本使用

```tsx
import { toast } from "@/components";

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

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

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

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

### 全局配置（可选）

```tsx
import { toast } from "@/components";

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

## 详细用法

### 1. 显示自定义提示

```tsx
import { toast } from "@/components";

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

### 2. 使用 ReactNode 作为消息内容

```tsx
import { toast } from "@/components";

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

### 3. 自定义图标

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

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

### 4. 手动关闭提示

```tsx
import { toast } from "@/components";

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

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

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

### 5. 在非 React 组件中使用

```tsx
// 可以在任何地方使用，包括工具函数、事件处理器等
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           | 最大显示数量 |

## 类型定义

```typescript
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`，但不推荐使用：

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

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

## 注意事项

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

## 迁移指南

### 从旧版本迁移

**旧版本（需要 Provider）：**

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

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

**新版本（直接使用）：**

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

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