LabelingSystem/TOAST_CUSTOM_IMPLEMENTATION.md

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 类型

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

使用方法

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 变量

测试

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

// 在任何组件中
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