UI 组件替换指南

版本: 3.0.0 | 更新日期: 2026-02-01

本指南帮助您将现有的 shadcn/ui 或其他 UI 组件迁移到 MBE 设计系统。

概述

MBE 设计系统提供了一套统一的 UI 组件，替换原有的 shadcn/ui 组件。新组件具有:

• 统一的设计语言
• 毛玻璃效果 (Glass Morphism)
• 更好的暗色主题支持
• TypeScript 完整类型支持

组件对照表

详细替换指南

1. Card → GlassCard

旧代码

import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@/components/ui/card';

<Card>
  <CardHeader>
    <CardTitle>标题</CardTitle>
    <CardDescription>描述文字</CardDescription>
  </CardHeader>
  <CardContent>
    <p>内容区域</p>
  </CardContent>
  <CardFooter>
    <Button>操作按钮</Button>
  </CardFooter>
</Card>

新代码

import { GlassCard, Button } from '@mbe/ui';

<GlassCard hover className="p-6">
  <div className="mb-4">
    <h3 className="text-lg font-semibold">标题</h3>
    <p className="text-sm text-gray-400">描述文字</p>
  </div>
  <div className="mb-4">
    <p>内容区域</p>
  </div>
  <div>
    <Button variant="primary">操作按钮</Button>
  </div>
</GlassCard>

GlassCard 属性

2. Button 替换

旧代码

import { Button } from '@/components/ui/button';

<Button variant="default">默认</Button>
<Button variant="destructive">删除</Button>
<Button variant="outline">轮廓</Button>
<Button variant="secondary">次要</Button>
<Button variant="ghost">幽灵</Button>
<Button variant="link">链接</Button>
<Button disabled>禁用</Button>

新代码

import { Button } from '@mbe/ui';

<Button variant="primary">默认</Button>
<Button variant="danger">删除</Button>
<Button variant="outline">轮廓</Button>
<Button variant="secondary">次要</Button>
<Button variant="ghost">幽灵</Button>
<Button variant="ghost" className="underline">链接</Button>
<Button disabled>禁用</Button>

变体对照

新增功能

// 加载状态
<Button loading>加载中...</Button>

// 带图标
import { Plus } from 'lucide-react';
<Button icon={<Plus />}>新增</Button>

// 尺寸
<Button size="sm">小</Button>
<Button size="md">中</Button>
<Button size="lg">大</Button>

3. Badge 替换

旧代码

import { Badge } from '@/components/ui/badge';

<Badge>默认</Badge>
<Badge variant="secondary">次要</Badge>
<Badge variant="destructive">危险</Badge>
<Badge variant="outline">轮廓</Badge>

新代码

import { Badge } from '@mbe/ui';

<Badge variant="default">默认</Badge>
<Badge variant="primary">主要</Badge>
<Badge variant="success">成功</Badge>
<Badge variant="warning">警告</Badge>
<Badge variant="error">错误</Badge>
<Badge variant="info">信息</Badge>

变体对照

4. Input 替换

旧代码

import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';

<div>
  <Label htmlFor="email">邮箱</Label>
  <Input id="email" type="email" placeholder="请输入邮箱" />
</div>

新代码

import { Input } from '@mbe/ui';

<div>
  <label htmlFor="email" className="block text-sm font-medium mb-2">邮箱</label>
  <Input id="email" type="email" placeholder="请输入邮箱" />
</div>

// 带图标
import { Mail } from 'lucide-react';
<Input icon={<Mail />} type="email" placeholder="请输入邮箱" />

// 错误状态
<Input error errorMessage="邮箱格式不正确" />

5. Skeleton 替换

旧代码

import { Skeleton } from '@/components/ui/skeleton';

<Skeleton className="h-4 w-[250px]" />
<Skeleton className="h-4 w-[200px]" />

新代码

import { Skeleton } from '@mbe/ui';

<Skeleton className="h-4 w-[250px]" />
<Skeleton className="h-4 w-[200px]" />

Skeleton 组件用法基本相同，只需更改导入路径。

6. Toast 替换

旧代码

import { useToast } from '@/components/ui/use-toast';
import { Toaster } from '@/components/ui/toaster';

// 在根组件
<Toaster />

// 在组件中
const { toast } = useToast();
toast({
  title: "成功",
  description: "操作已完成",
});

新代码

import { useToast, ToastProvider } from '@mbe/ui';

// 在根组件
<ToastProvider>
  <App />
</ToastProvider>

// 在组件中
const { toast } = useToast();
toast.success('操作已完成');
toast.error('操作失败');
toast.warning('请注意');
toast.info('提示信息');

Toast 方法对照

批量替换脚本

使用搜索替换

在 VS Code 中使用正则表达式批量替换:

1. 打开搜索替换 (Ctrl+Shift+H)
2. 启用正则表达式模式

替换导入语句

搜索:

import \{ Card[^}]*\} from ['"]@/components/ui/card['"];?

替换:

import { GlassCard } from '@mbe/ui';

替换 Button 导入

搜索:

import \{ Button \} from ['"]@/components/ui/button['"];?

替换:

import { Button } from '@mbe/ui';

常见问题

Q: 样式不一致怎么办？

A: 确保已正确配置 Tailwind:

// tailwind.config.ts
import mbeConfig from '@mbe/tailwind-config';

export default {
  presets: [mbeConfig],
  content: [
    './node_modules/@mbe/ui/**/*.{js,ts,jsx,tsx}',
  ],
};

Q: TypeScript 类型报错？

A: 确保安装了最新版本:

pnpm add @mbe/ui@latest @mbe/design-tokens@latest

Q: 如何保持旧组件兼容？

A: 可以逐步迁移，两套组件可以共存:

// 旧组件
import { Card } from '@/components/ui/card';
// 新组件
import { GlassCard } from '@mbe/ui';

// 在同一页面中混用（过渡期）

迁移检查清单

• 更新 tailwind.config.ts 使用 @mbe/tailwind-config
• 在 globals.css 导入 @mbe/design-tokens/dist/tokens.css
• 替换 Card → GlassCard
• 替换 Button 导入和变体
• 替换 Badge 导入和变体
• 替换 Input 导入
• 替换 Skeleton 导入
• 替换 Toast 系统
• 添加 ToastProvider 到根组件
• 测试所有页面

相关文档

• 设计系统快速指南
• 系统架构

UI 组件替换指南 | MBE v3.0.0 | 2026-02-01