# Toast 自定义实现文档

## 概述

由于 UI 库的 Toast 组件使用 CSS Modules，类名被哈希化（如 `toast_toast__Zvlxi`），导致样式覆盖困难。因此，我们创建了一个完全自定义的 Toast 组件，不依赖 UI 库。

## 实现文件

### 1. Toast 组件
- **位置**: `web/apps/lq_label/src/components/toast/`
- **文件**:
  - `toast.tsx` - Toast 组件实现
  - `toast.module.scss` - Toast 样式
  - `index.ts` - 导出文件

### 2. Toast 服务
- **位置**: `web/apps/lq_label/src/services/toast.ts`
- **功能**: 提供全局 Toast 通知服务

### 3. Toast 容器
- **位置**: `web/apps/lq_label/src/components/toast-container/toast-container.tsx`
- **功能**: 连接 Toast 服务和 Toast 组件

## Toast 类型

```typescript
export enum ToastType {
  success = 'success',  // 成功提示 - 绿色
  error = 'error',      // 错误提示 - 红色
  info = 'info',        // 信息提示 - 黑色
  warning = 'warning',  // 警告提示 - 橙色
}
```

## 使用方法

```typescript
import { toast } from '../../services/toast';

// 成功提示
toast.success('操作成功！');
toast.success('保存成功', '成功', 3000);

// 错误提示
toast.error('操作失败！');
toast.error('保存失败，请重试', '错误', 5000);

// 信息提示
toast.info('这是一条信息');
toast.info('系统通知', '提示', 4000);

// 警告提示
toast.warning('请注意！');
toast.warning('数据可能不完整', '警告', 4000);
```

## 样式特性

### 1. 设计令牌
所有样式使用项目的设计令牌（Design Tokens）：
- `--color-positive-*` - 成功颜色
- `--color-negative-*` - 错误颜色
- `--color-neutral-inverted-*` - 信息颜色
- `--color-warning-*` - 警告颜色
- `--spacing-*` - 间距
- `--corner-radius-*` - 圆角
- `--font-size-*` - 字体大小

### 2. 视觉效果
- 最小高度: 56px
- 圆角边框
- 阴影和模糊效果（backdrop-filter）
- 错误/警告类型左侧粗边框（4px）
- 平滑动画（cubic-bezier）

### 3. 响应式设计
- 桌面端: 最大宽度 420px，居中显示
- 移动端: 宽度自适应，减小内边距

### 4. 交互
- 关闭按钮: 点击关闭
- 自动关闭: 可配置持续时间
- 退出动画: 平滑淡出

## 样式示例

### 成功提示
- 背景: 白色
- 标题: 绿色（kale-700）
- 消息: 深灰色（sand-800）
- 左侧粗边框: 深绿色（kale-800）
- 边框: 绿色（kale-700）

### 错误提示
- 背景: 白色
- 标题: 红色（persimmon-700）
- 消息: 深灰色（sand-800）
- 左侧粗边框: 深红色（persimmon-800）
- 边框: 红色（persimmon-700）

### 信息提示
- 背景: 深灰色（sand-900）
- 文字: 白色
- 无粗边框

### 警告提示
- 背景: 白色
- 标题: 橙色（canteloupe-700）
- 消息: 深灰色（sand-800）
- 左侧粗边框: 深橙色（canteloupe-800）
- 边框: 橙色（canteloupe-700）

## 优势

1. **完全可控**: 不受 UI 库 CSS Modules 限制
2. **样式一致**: 使用项目设计令牌
3. **性能优化**: 轻量级实现，无额外依赖
4. **易于维护**: 代码清晰，结构简单
5. **响应式**: 适配桌面和移动端

## 清理的文件

以下文件已被删除或替换：
- `web/apps/lq_label/src/components/toast-container/toast-container.module.scss` - 已删除（旧的样式覆盖文件）

## 注意事项

1. **不要使用 UI 库的 Toast**: 已完全移除对 `@humansignal/ui` Toast 组件的依赖
2. **使用自定义 Toast**: 所有 Toast 通知都应使用 `toast` 服务
3. **设计令牌**: 确保使用项目中实际存在的 CSS 变量

## 测试

重启前端服务器后，可以通过以下方式测试：

```typescript
// 在任何组件中
import { toast } from '../../services/toast';

// 测试不同类型的 Toast
toast.success('这是成功提示');
toast.error('这是错误提示');
toast.info('这是信息提示');
toast.warning('这是警告提示');
```

## 相关文件

- `web/apps/lq_label/src/components/toast/toast.tsx`
- `web/apps/lq_label/src/components/toast/toast.module.scss`
- `web/apps/lq_label/src/services/toast.ts`
- `web/apps/lq_label/src/components/toast-container/toast-container.tsx`
- `web/apps/lq_label/src/app/app.tsx` (ToastContainer 已集成)

## 更新日期

2025-01-23