# Toast 组件

## 组件说明

通知反馈组件，基于 Ant Design notification 封装，用于操作完成后向用户展示反馈信息。通知从右上角滑出，默认 3 秒后自动消失，最多同时显示 3 条通知。

## 组件位置

```
src/components/Toast/Toast.jsx
```

## 全局配置

```javascript
notification.config({
  placement: 'topRight',  // 通知位置：右上角
  top: 24,                // 距离顶部 24px
  duration: 3,            // 默认显示 3 秒
  maxCount: 3,            // 最多同时显示 3 条
})
```

## API 方法

组件以静态方法的形式提供，无需实例化，直接调用即可。

### Toast.success()

显示成功通知（绿色图标）。

#### 参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| message | string | 是 | - | 主要消息内容 |
| description | string | 否 | '' | 详细描述 |
| duration | number | 否 | 3 | 显示时长（秒），0 表示不自动关闭 |

#### 使用示例

```jsx
import Toast from '../components/Toast/Toast'

// 简单成功提示
Toast.success('操作成功')

// 带详细描述
Toast.success('删除成功', '用户 "admin" 已成功删除')

// 自定义显示时长（5秒）
Toast.success('保存成功', '您的设置已保存', 5)

// 不自动关闭
Toast.success('操作成功', '请注意后续操作', 0)
```

### Toast.error()

显示错误通知（红色图标）。

#### 参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| message | string | 是 | - | 主要消息内容 |
| description | string | 否 | '' | 详细描述 |
| duration | number | 否 | 3 | 显示时长（秒） |

#### 使用示例

```jsx
// 简单错误提示
Toast.error('操作失败')

// 带错误详情
Toast.error('删除失败', '该用户下还有关联数据，无法删除')

// API 错误处理
try {
  await api.deleteUser(userId)
  Toast.success('删除成功')
} catch (error) {
  Toast.error('删除失败', error.message)
}
```

### Toast.warning()

显示警告通知（橙色图标）。

#### 参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| message | string | 是 | - | 主要消息内容 |
| description | string | 否 | '' | 详细描述 |
| duration | number | 否 | 3 | 显示时长（秒） |

#### 使用示例

```jsx
// 警告提示
Toast.warning('操作警告', '此操作可能影响系统稳定性')

// 权限警告
Toast.warning('权限不足', '您没有执行此操作的权限')

// 数据警告
Toast.warning('数据异常', '检测到部分数据可能不完整')
```

### Toast.info()

显示信息通知（蓝色图标）。

#### 参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| message | string | 是 | - | 主要消息内容 |
| description | string | 否 | '' | 详细描述 |
| duration | number | 否 | 3 | 显示时长（秒） |

#### 使用示例

```jsx
// 信息提示
Toast.info('系统提示', '系统将在5分钟后进行维护')

// 操作提示
Toast.info('导入中', '正在导入数据，请稍候...')

// 功能提示
Toast.info('新功能上线', '我们上线了新的数据导出功能')
```

### Toast.custom()

显示自定义通知，支持所有 Ant Design notification 配置。

#### 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| config | Object | 是 | 完整的 notification 配置对象 |

#### 使用示例

```jsx
import { Button } from 'antd'

// 带操作按钮的通知
Toast.custom({
  message: '新版本可用',
  description: '发现新版本 v2.0.0，是否立即更新？',
  duration: 0,
  btn: (
    <Button type="primary" size="small" onClick={() => {
      console.log('更新')
      notification.close('update-key')
    }}>
      立即更新
    </Button>
  ),
  key: 'update-key',
})

// 自定义图标和样式
Toast.custom({
  message: '自定义通知',
  description: '这是一个自定义样式的通知',
  icon: <StarOutlined style={{ color: '#faad14' }} />,
  style: {
    background: '#fffbe6',
  },
})
```

## 完整使用示例

### 配合 ConfirmDialog 使用

```jsx
import ConfirmDialog from '../components/ConfirmDialog/ConfirmDialog'
import Toast from '../components/Toast/Toast'

const handleDeleteUser = (record) => {
  ConfirmDialog.delete({
    itemName: `用户名：${record.userName}`,
    itemInfo: `姓名：${record.name}`,
    onOk() {
      return new Promise((resolve) => {
        setTimeout(() => {
          const newUsers = filteredUsers.filter((u) => u.id !== record.id)
          setFilteredUsers(newUsers)
          resolve()
          Toast.success('删除成功', `用户 "${record.userName}" 已成功删除`)
        }, 1000)
      })
    },
  })
}
```

### 批量操作反馈

```jsx
const handleBatchDelete = () => {
  ConfirmDialog.batchDelete({
    count: selectedRowKeys.length,
    items: selectedUsers,
    onOk() {
      return new Promise((resolve) => {
        setTimeout(() => {
          const count = selectedRowKeys.length
          const newUsers = filteredUsers.filter((u) => !selectedRowKeys.includes(u.id))
          setFilteredUsers(newUsers)
          setSelectedRowKeys([])
          resolve()
          Toast.success('批量删除成功', `已成功删除 ${count} 个用户`)
        }, 1000)
      })
    },
  })
}
```

### 异步操作反馈

```jsx
const handleSaveUser = async (userData) => {
  try {
    setLoading(true)
    await api.updateUser(userData)
    setShowEditDrawer(false)
    Toast.success('保存成功', '用户信息已更新')
    fetchUsers()  // 重新加载列表
  } catch (error) {
    Toast.error('保存失败', error.message)
  } finally {
    setLoading(false)
  }
}
```

### 多步骤操作反馈

```jsx
const handleImportData = async () => {
  try {
    Toast.info('导入开始', '正在验证数据格式...')

    await api.validateData()
    Toast.info('验证通过', '正在导入数据...')

    const result = await api.importData()
    Toast.success('导入完成', `成功导入 ${result.count} 条数据`)

  } catch (error) {
    if (error.type === 'validation') {
      Toast.warning('验证失败', error.message)
    } else {
      Toast.error('导入失败', error.message)
    }
  }
}
```

### 表单提交反馈

```jsx
const handleSubmit = async (values) => {
  try {
    await api.createUser(values)
    Toast.success('创建成功', `用户 "${values.userName}" 已成功创建`)
    setShowEditDrawer(false)
    fetchUsers()
  } catch (error) {
    if (error.code === 'DUPLICATE') {
      Toast.warning('用户名已存在', '请使用其他用户名')
    } else {
      Toast.error('创建失败', error.message)
    }
  }
}
```

### 带按钮的持久通知

```jsx
const showUpdateNotification = () => {
  const key = `update-${Date.now()}`

  Toast.custom({
    message: '发现新版本',
    description: '系统发现新版本 v2.0.0，建议立即更新',
    duration: 0,  // 不自动关闭
    key,
    btn: (
      <Space>
        <Button
          type="link"
          size="small"
          onClick={() => notification.close(key)}
        >
          稍后
        </Button>
        <Button
          type="primary"
          size="small"
          onClick={() => {
            notification.close(key)
            handleUpdate()
          }}
        >
          立即更新
        </Button>
      </Space>
    ),
  })
}
```

## 使用场景

1. **操作成功反馈** - 增删改操作成功后的提示
2. **操作失败反馈** - 操作失败时显示错误信息
3. **警告提示** - 权限不足、数据异常等警告
4. **信息通知** - 系统公告、功能提示等
5. **进度通知** - 多步骤操作的进度反馈
6. **版本更新通知** - 带操作按钮的持久通知

## 最佳实践

### 消息文案

```jsx
// 好的做法：简洁明了
Toast.success('删除成功', '用户已删除')

// 避免：冗余重复
Toast.success('删除成功', '删除用户成功')  // ❌
```

### 显示时长

```jsx
// 简单提示：3秒（默认）
Toast.success('保存成功')

// 重要信息：5秒
Toast.warning('权限不足', '请联系管理员', 5)

// 需要用户操作：不自动关闭
Toast.custom({
  message: '需要您的确认',
  description: '...',
  duration: 0,
  btn: <Button>...</Button>,
})
```

### 类型选择

```jsx
// 成功：操作完成
Toast.success('保存成功')

// 错误：操作失败、异常
Toast.error('保存失败', error.message)

// 警告：权限、数据问题
Toast.warning('权限不足')

// 信息：提示、公告
Toast.info('系统维护通知')
```

## 样式特性

- **圆角设计**：8px 圆角，现代化视觉效果
- **阴影效果**：0 4px 12px rgba(0, 0, 0, 0.15)
- **彩色图标**：
  - 成功：绿色 (#52c41a)
  - 错误：红色 (#ff4d4f)
  - 警告：橙色 (#faad14)
  - 信息：蓝色 (#1677ff)

## 注意事项

1. 通知从右上角滑出，默认 3 秒后自动消失
2. 最多同时显示 3 条通知，超出的会排队等待
3. `duration: 0` 表示通知不自动关闭，需手动关闭或调用 API 关闭
4. 通知内容不宜过长，建议 message 不超过 20 字，description 不超过 50 字
5. 频繁操作时避免连续显示大量通知，可以考虑合并提示
6. 配合 ConfirmDialog 使用时，在 `onOk` 回调中显示操作结果
7. 错误通知建议显示具体错误信息，帮助用户排查问题