Maas-Model-platform/docs/inside/notification-system-implementation.md

通知系统实现文档

概述

本文档记录了将项目中的原生 alert() 和 confirm() 替换为自定义通知系统的实现过程。

实现日期

2026-01-31

架构设计

组件结构

frontend/
├── components/
│   ├── Toast.tsx                    # Toast 通知组件（已存在）
│   ├── ConfirmDialog.tsx            # 确认对话框组件（新建）
│   └── NotificationExample.tsx      # 使用示例（新建）
├── contexts/
│   └── NotificationContext.tsx      # 通知系统 Context 和 Hooks（新建）
├── App.tsx                          # 添加 NotificationProvider
└── utils/
    └── migrationGuide.md            # 迁移指南（新建）

核心组件

1. ConfirmDialog 组件

• 模态对话框，用于替换 confirm()
• 支持自定义标题、消息、按钮文本
• 支持危险操作（红色按钮）和普通操作（蓝色按钮）
• 点击背景遮罩或 X 按钮可关闭

2. NotificationContext

• 提供全局的通知管理
• 管理 Toast 和 ConfirmDialog 的状态
• 导出 useToast 和 useConfirm hooks

3. useToast Hook

const { showToast } = useToast();
showToast('操作成功', 'success');
showToast('操作失败', 'error');

4. useConfirm Hook

const { showConfirm } = useConfirm();
const confirmed = await showConfirm({
  title: '确认删除',
  message: '确定要删除这条记录吗？',
  confirmText: '删除',
  cancelText: '取消',
  danger: true
});

已完成的替换

1. CloningPanel.tsx（声音克隆）

• ✅ 替换 5 处 alert() 为 showToast()
• 涉及场景：
  • 输入验证错误
  • 音频文件验证错误
  • 创建成功/失败提示

2. SynthesisPanel.tsx（语音合成）

• ✅ 替换 3 处 alert() 为 showToast()
• ✅ 替换 1 处 confirm() 为 showConfirm()
• 涉及场景：
  • 输入验证错误
  • 合成失败提示
  • 删除音色确认

3. MultimodalTranslation.tsx（多模态翻译）

• ✅ 替换 1 处 confirm() 为 showConfirm()
• 涉及场景：
  • 删除翻译记录确认

待替换的文件

高优先级

• frontend/components/audio/SynthesisPanel.tsx - 3 处 alert, 1 处 confirm
• frontend/components/audio/LongTextPanel.tsx - 2 处 alert
• frontend/pages/ImageTranslation.tsx - 2 处 alert, 2 处 confirm
• frontend/pages/DataMining.tsx - 9 处 alert, 4 处 confirm

中优先级

• frontend/pages/InvoiceManagement.tsx - 5 处 alert
• frontend/pages/InvoiceApply.tsx - 3 处 alert
• frontend/pages/Billing.tsx - 2 处 alert
• frontend/pages/DeepResearch.tsx - 1 处 confirm
• frontend/pages/ResearchHistory.tsx - 1 处 confirm

低优先级

• frontend/components/ocr/ImageUploadZone.tsx - 3 处 alert
• frontend/components/HistoryTable.examples.tsx - 1 处 confirm

使用指南

基本用法

1. 导入 Hooks

   import { useToast } from '../contexts/NotificationContext';
   import { useConfirm } from '../contexts/NotificationContext';
   

2. 在组件中使用

   const MyComponent = () => {
   const { showToast } = useToast();
   const { showConfirm } = useConfirm();
     
   const handleSave = async () => {
   try {
     await saveData();
     showToast('保存成功', 'success');
   } catch (error) {
     showToast('保存失败', 'error');
   }
   };
     
   const handleDelete = async () => {
   const confirmed = await showConfirm({
     title: '确认删除',
     message: '确定要删除吗？',
     danger: true
   });
       
   if (confirmed) {
     await deleteData();
     showToast('删除成功', 'success');
   }
   };
   };
   

替换模式

Alert → Toast

// 旧代码
alert('操作成功');

// 新代码
showToast('操作成功', 'success');

Confirm → showConfirm

// 旧代码
if (!confirm('确定删除吗？')) return;

// 新代码
const confirmed = await showConfirm({
  message: '确定删除吗？',
  danger: true
});
if (!confirmed) return;

优势

1. 更好的用户体验

   • 美观的 UI 设计
   • 平滑的动画效果
   • 非阻塞式通知

2. 更灵活的配置

   • 自定义标题、消息、按钮文本
   • 支持危险操作样式
   • 支持多行消息

3. 更好的可维护性

   • 统一的通知管理
   • 类型安全
   • 易于测试

4. 更好的可访问性

   • 支持键盘操作
   • 语义化的 HTML
   • ARIA 标签

技术细节

Toast 自动消失

• 默认 2.5 秒后自动消失
• 可通过 duration 参数自定义
• 支持手动关闭

Confirm 对话框

• 使用 Promise 返回用户选择
• 支持点击背景遮罩关闭
• 支持 ESC 键关闭（可扩展）

状态管理

• 使用 React Context 管理全局状态
• 避免 prop drilling
• 支持多个通知同时显示（可扩展）

后续优化建议

1. 支持多个 Toast 同时显示

   • 当前只支持一个 Toast
   • 可以改为队列模式

2. 支持更多通知类型

   • info（信息）
   • warning（警告）

3. 支持自定义位置

   • 顶部、底部、左侧、右侧

4. 支持键盘快捷键

   • ESC 关闭对话框
   • Enter 确认操作

5. 支持自定义动画

   • 滑入、淡入、缩放等

测试建议

1. 功能测试

   • Toast 正常显示和消失
   • Confirm 对话框正常弹出和关闭
   • 按钮点击正确返回结果

2. 边界测试

   • 长文本消息显示
   • 快速连续触发
   • 组件卸载时的清理

3. 可访问性测试

   • 键盘导航
   • 屏幕阅读器支持
   • 焦点管理

参考资料

• Toast 组件源码
• ConfirmDialog 组件源码
• NotificationContext 源码
• 使用示例
• 迁移指南