Maas-Model-platform/frontend/utils/migrationGuide.md

通知系统迁移指南

概述

本指南说明如何将项目中的原生 alert() 和 confirm() 替换为新的通知系统。

快速开始

1. 导入 Hooks

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

2. 在组件中使用

const MyComponent = () => {
  const { showToast } = useToast();
  const { showConfirm } = useConfirm();
  
  // ... 组件逻辑
};

替换模式

Alert 替换

模式 1: 简单提示

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

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

模式 2: 错误提示

// ❌ 旧代码
alert('操作失败，请重试');

// ✅ 新代码
showToast('操作失败，请重试', 'error');

模式 3: 多行消息

// ❌ 旧代码
alert(`音色创建成功！\n\n音色ID: ${voiceId}\n状态: 可用`);

// ✅ 新代码
showToast(`音色创建成功！音色ID: ${voiceId}，状态: 可用`, 'success');

Confirm 替换

模式 1: 简单确认

// ❌ 旧代码
if (!confirm('确定要删除这条记录吗？')) return;
// 执行删除

// ✅ 新代码
const confirmed = await showConfirm({
  message: '确定要删除这条记录吗？'
});
if (!confirmed) return;
// 执行删除

模式 2: 危险操作（删除）

// ❌ 旧代码
if (!confirm('确定要删除这条记录吗？')) return;

// ✅ 新代码
const confirmed = await showConfirm({
  title: '确认删除',
  message: '确定要删除这条记录吗？',
  confirmText: '删除',
  cancelText: '取消',
  danger: true
});
if (!confirmed) return;

模式 3: 自定义按钮文本

// ❌ 旧代码
if (!confirm('确定要保存更改吗？')) return;

// ✅ 新代码
const confirmed = await showConfirm({
  title: '保存更改',
  message: '确定要保存当前的更改吗？',
  confirmText: '保存',
  cancelText: '取消'
});
if (!confirmed) return;

模式 4: 多行消息

// ❌ 旧代码
if (!confirm(`确定要删除选中的 ${count} 个文档吗？`)) return;

// ✅ 新代码
const confirmed = await showConfirm({
  title: '批量删除',
  message: `确定要删除选中的 ${count} 个文档吗？\n\n此操作不可恢复，请谨慎操作。`,
  confirmText: '确定删除',
  cancelText: '取消',
  danger: true
});
if (!confirmed) return;

需要替换的文件列表

高优先级（用户常用功能）

• frontend/components/audio/CloningPanel.tsx - 声音克隆
• frontend/components/audio/SynthesisPanel.tsx - 语音合成
• frontend/components/audio/LongTextPanel.tsx - 长文本转语音
• frontend/pages/MultimodalTranslation.tsx - 多模态翻译
• frontend/pages/ImageTranslation.tsx - 图片翻译
• frontend/pages/DataMining.tsx - 数据挖掘

中优先级（管理功能）

• frontend/pages/InvoiceManagement.tsx - 发票管理
• frontend/pages/InvoiceApply.tsx - 发票申请
• frontend/pages/Billing.tsx - 账单
• frontend/pages/DeepResearch.tsx - 深度研究
• frontend/pages/ResearchHistory.tsx - 研究历史

低优先级（辅助组件）

• frontend/components/ocr/ImageUploadZone.tsx - 图片上传
• frontend/components/HistoryTable.examples.tsx - 示例代码

注意事项

1. 异步处理: showConfirm 返回 Promise，需要使用 await 或 .then()
2. 函数必须是 async: 使用 showConfirm 的函数需要声明为 async
3. Toast 自动消失: Toast 会在 2.5 秒后自动消失，无需手动关闭
4. Confirm 等待响应: Confirm 对话框会等待用户点击按钮才关闭

测试清单

替换完成后，请测试以下场景：

• Toast 成功提示正常显示
• Toast 错误提示正常显示
• Toast 自动消失
• Confirm 对话框正常弹出
• Confirm 点击确定返回 true
• Confirm 点击取消返回 false
• Confirm 点击背景遮罩关闭
• Confirm 点击 X 按钮关闭
• 危险操作显示红色按钮
• 普通操作显示蓝色按钮