399 lines
9.3 KiB
Markdown
399 lines
9.3 KiB
Markdown
# 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. 错误通知建议显示具体错误信息，帮助用户排查问题
|