feat:init
This commit is contained in:
zhongyidian committed
1 parent
53d0eeac6b
commit
ae0c050010
494 files changed
+17701
-2318
No files matched your search
@@ -0,0 +1,222 @@
|
||||
# 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` 对象即可。
|
||||
Reference in new issue
Block a user