Maas-Model-platform/docs/inside/tingwu-refactor.md

通义听悟页面重构文档

重构日期

2026-01-31

重构目标

将通义听悟页面从 Ant Design 组件重构为 Tailwind 自定义组件，与其他通义应用（多模态翻译、图像翻译等）保持一致的视觉风格和交互体验。

重构内容

1. 组件替换对照表

原组件 (Ant Design)	新组件 (Tailwind)	说明
Tabs	TabNavigation	自定义 Tab 组件，支持图标
Card	div with Tailwind	白色圆角卡片，统一样式
Button	button with Tailwind	渐变按钮，统一交互
message	useToast hook	全局 Toast 通知系统
Alert	自定义提示框	使用 Tailwind 样式

2. 导入变更

删除的导入

// ❌ 删除
import { Card, Button, Tabs, message, Space, Alert } from 'antd';
import { ThunderboltOutlined } from '@ant-design/icons';
import { Mic } from '../icons/commonIcons';

新增的导入

// ✅ 新增
import { Mic, FileAudio, BookText, CheckCircle, Loader2 } from 'lucide-react';
import TabNavigation, { TabItem } from '../components/TabNavigation';
import { useToast } from '../contexts/NotificationContext';

3. 主要变更

3.1 Tab 导航

之前 (Ant Design):

<Tabs 
  activeKey={activeTab} 
  onChange={setActiveTab}
  items={[
    {
      key: 'offline',
      label: '离线转写',
      children: (...)
    },
    {
      key: 'phrases',
      label: '热词管理',
      children: (...)
    }
  ]}
/>

之后 (Tailwind):

// Tab 配置
const tabs: TabItem<TingwuTab>[] = [
  { id: 'offline', label: '离线转写', icon: FileAudio },
  { id: 'phrases', label: '热词管理', icon: BookText }
];

// 渲染
<div className="bg-white rounded-2xl border border-gray-100 shadow-sm p-6">
  <TabNavigation
    tabs={tabs}
    activeTab={activeTab}
    onTabChange={(tabId) => setActiveTab(tabId as TingwuTab)}
  />
</div>

{/* 条件渲染内容 */}
{activeTab === 'offline' && (...)}
{activeTab === 'phrases' && (...)}

3.2 卡片组件

之前 (Ant Design):

<Card title="1. 上传音视频文件">
  <FileUpload onUploadSuccess={handleUploadSuccess} />
</Card>

之后 (Tailwind):

<div className="bg-white rounded-2xl border border-gray-100 shadow-sm p-6">
  <h3 className="text-sm font-bold text-gray-900 mb-4">1. 上传音视频文件</h3>
  <FileUpload onUploadSuccess={handleUploadSuccess} />
</div>

3.3 提示消息

之前 (Ant Design):

message.success('文件上传成功');
message.error('加载任务列表失败');

之后 (useToast):

const { showToast } = useToast();

showToast('文件上传成功，请配置参数后开始转写', 'success');
showToast('加载任务列表失败', 'error');

3.4 成功提示框

之前 (Ant Design):

<Alert
  message="文件已上传"
  description={`文件名：${fileName}`}
  type="success"
  showIcon
  className="mt-4"
/>

之后 (Tailwind):

<div className="mt-4 p-4 bg-green-50 border border-green-200 rounded-xl flex items-start space-x-3">
  <CheckCircle className="w-5 h-5 text-green-600 flex-shrink-0 mt-0.5" />
  <div className="flex-1">
    <p className="text-sm font-medium text-green-900">文件已上传</p>
    <p className="text-xs text-green-700 mt-1">文件名：{fileName}</p>
  </div>
</div>

3.5 按钮

之前 (Ant Design):

<Button
  type="primary"
  size="large"
  block
  loading={submitting}
  disabled={!fileUrl}
  onClick={handleSubmit}
  style={{
    background: 'linear-gradient(135deg, #3B82F6 0%, #A78BFA 100%)',
    border: 'none',
    height: '48px',
    fontSize: '16px',
    fontWeight: 'bold',
  }}
>
  开始转写
</Button>

之后 (Tailwind):

<button
  onClick={handleSubmit}
  disabled={!fileUrl || submitting}
  className="w-full h-12 bg-gradient-to-r from-blue-600 to-purple-600 text-white rounded-xl text-base font-bold hover:from-blue-700 hover:to-purple-700 disabled:opacity-50 disabled:cursor-not-allowed transition-all shadow-lg shadow-blue-500/20 flex items-center justify-center space-x-2"
>
  {submitting ? (
    <>
      <Loader2 className="w-5 h-5 animate-spin" />
      <span>处理中...</span>
    </>
  ) : (
    <span>开始转写</span>
  )}
</button>

4. 新增功能

4.1 返回按钮

<ToolboxAppLayout
  icon={<Mic className="w-6 h-6" />}
  title="通义听悟"
  description="智能音视频转写与分析服务"
  showBackButton={true}  // ✅ 新增
>

4.2 类型安全

type TingwuTab = 'offline' | 'phrases';  // ✅ 新增类型定义

const [activeTab, setActiveTab] = useState<TingwuTab>('offline');

5. 保留的组件

以下组件保持不变，继续复用：

• ✅ FileUpload - 文件上传组件
• ✅ TaskConfig - 任务配置组件
• ✅ TaskList - 任务列表组件
• ✅ PhraseManager - 热词管理组件

这些组件内部可能仍使用 Ant Design，但不影响主页面的一致性。

样式统一

卡片样式

bg-white rounded-2xl border border-gray-100 shadow-sm p-6

标题样式

text-sm font-bold text-gray-900 mb-4

输入框样式

w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-blue-500

渐变按钮样式

bg-gradient-to-r from-blue-600 to-purple-600 text-white rounded-xl font-bold hover:from-blue-700 hover:to-purple-700 transition-all shadow-lg shadow-blue-500/20

迁移步骤

1. 备份原文件

   cp frontend/pages/TingwuWorkshop.tsx frontend/pages/TingwuWorkshop.backup.tsx
   

2. 替换文件

   cp frontend/pages/TingwuWorkshop.new.tsx frontend/pages/TingwuWorkshop.tsx
   

3. 删除临时文件

   rm frontend/pages/TingwuWorkshop.new.tsx
   

4. 测试功能

   • 文件上传
   • 任务创建
   • Tab 切换
   • 热词管理
   • Toast 通知

优势

1. 视觉一致性

• ✅ 与其他通义应用（多模态翻译、图像翻译）保持一致
• ✅ 统一的卡片、按钮、输入框样式
• ✅ 统一的 Tab 导航体验

2. 性能优化

• ✅ 移除 Ant Design 依赖，减小 bundle 体积
• ✅ 使用 Tailwind 的 Tree-shaking
• ✅ 更快的首次加载速度

3. 可维护性

• ✅ 统一的组件库（TabNavigation, useToast）
• ✅ 类型安全（TypeScript 类型定义）
• ✅ 更清晰的代码结构

4. 用户体验

• ✅ 统一的交互模式
• ✅ 更流畅的动画效果
• ✅ 更好的响应式设计

注意事项

1. 子组件兼容性

   • FileUpload, TaskConfig, TaskList, PhraseManager 组件可能仍使用 Ant Design
   • 如需完全移除 Ant Design，需要进一步重构这些子组件

2. 功能验证

   • 确保所有功能正常工作
   • 特别注意文件上传和任务创建流程

3. 样式调整

   • 根据实际效果微调间距和颜色
   • 确保在不同屏幕尺寸下显示正常

后续优化建议

1. 重构子组件

   • 将 FileUpload 重构为 Tailwind 版本
   • 将 TaskConfig 重构为 Tailwind 版本
   • 将 TaskList 重构为 Tailwind 版本
   • 将 PhraseManager 重构为 Tailwind 版本

2. 完全移除 Ant Design

   • 检查项目中其他使用 Ant Design 的地方
   • 逐步替换为自定义组件
   • 最终从 package.json 中移除 antd 依赖

3. 组件库建设

   • 提取通用的卡片组件
   • 提取通用的按钮组件
   • 提取通用的表单组件

参考文档

• TabNavigation 组件
• useToast Hook
• MultimodalTranslation 页面 - 参考示例