shadcn/ui 详解与实战案例

shadcn/ui 是近年来备受前端开发者青睐的 UI 组件库，与传统 UI 库（如 Ant Design、MUI）有本质区别。它不是一个通过 npm 安装的第三方依赖包，而是一套可直接复制到项目中的高质量组件源代码，赋予开发者完全的控制权。

核心定义：shadcn/ui 是什么？

• 本质：一套可复制的组件源代码集合。通过 CLI 工具，将选中的组件（如按钮、输入框）源代码直接拷贝到你的项目中。
• 技术栈：
  • 底层交互：基于 Radix UI（无样式、无障碍的原始组件）。
  • 样式层：完全使用 Tailwind CSS 实现，支持高度自定义。
  • 主要生态：面向 React（Next.js 尤为友好），正在向其他框架扩展。

核心理念与设计模式

shadcn/ui 的设计围绕“组件即你的代码”（Components as Your Own Code）展开：

1. 可组合架构：逻辑（自定义 Hook）与视图分离，便于复用和适配不同框架。
2. 复制-粘贴模式：使用 npx shadcn-ui add [组件名] 将组件代码直接添加到项目，你可以随意修改。
3. Tailwind 主题系统：通过 CSS 变量和 tailwind.config.js 实现全局一致的主题切换。

主要使用场景

适合以下项目：

• 对 UI 定制化要求极高的品牌项目。
• 追求长期可维护性和完全控制权的项目。
• 基于 Tailwind CSS 的现代 React/Next.js 项目。
• 需要构建内部设计系统的团队（可作为高质量起点）。

与传统 UI 库对比

维度	shadcn/ui	Ant Design / MUI
安装方式	复制源代码到项目，无 shadcn/ui 包依赖	npm 安装大型第三方依赖包
依赖	仅 radix-ui、tailwindcss 等基础依赖	依赖整个组件库
所有权与维护	你完全拥有并控制代码，可随意修改 需自行维护更新	依赖官方维护，升级获取新功能 深度定制困难
包体积与性能	按需引入，仅用到的代码打包，无冗余	整体导入（可 Tree Shaking 优化），体积较大
开发效率	初始配置稍复杂，但修改无障碍 需熟悉 Tailwind	快速上手，文档丰富 深度定制可能需要 hack

总结与技术选型建议

选择 shadcn/ui 的场景：

• 追求极致控制权和可维护性。
• 需要深度 UI 定制。
• 已使用 Tailwind CSS，接受一定学习成本。

选择传统 UI 库的场景：

• 需要快速原型或标准化项目。
• UI 设计较为常规。
• 希望依赖成熟社区，减少维护负担。

shadcn/ui 代表了一种新的前端开发范式：用“所有权”换取“极致灵活性”。它不是取代传统库，而是为有特定需求的团队提供更强大的选择。

实战案例：使用 shadcn/ui 构建 React 登录表单

以下是一个完整、可运行的登录表单示例，展示 shadcn/ui 的实际使用流程和优势。

步骤 1：创建项目并配置 Tailwind CSS

npm create vite@latest shadcn-login-demo -- --template react-ts
cd shadcn-login-demo

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

tailwind.config.js 配置：

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

在 src/index.css 添加：

@tailwind base;
@tailwind components;
@tailwind utilities;

步骤 2：安装依赖

npm install class-variance-authority clsx tailwind-merge lucide-react
npm install @radix-ui/react-slot @radix-ui/react-label
npm install react-hook-form zod @hookform/resolvers

步骤 3：创建核心 UI 组件（src/components/ui）

utils.ts (src/lib/utils.ts)

import { type ClassValue, clsx } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

button.tsx

import * as React from "react"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "@/lib/utils"

const buttonVariants = cva(
  "inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        ghost: "hover:bg-accent hover:text-accent-foreground",
        link: "text-primary underline-offset-4 hover:underline",
      },
      size: {
        default: "h-10 px-4 py-2",
        sm: "h-9 rounded-md px-3",
        lg: "h-11 rounded-md px-8",
        icon: "h-10 w-10",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  asChild?: boolean
}

const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, asChild = false, ...props }, ref) => {
    const Comp = asChild ? "button" : "button"
    return (
      <Comp
        className={cn(buttonVariants({ variant, size, className }))}
        ref={ref}
        {...props}
      />
    )
  }
)
Button.displayName = "Button"

export { Button, buttonVariants }

input.tsx、label.tsx、form.tsx（略）

（为节省篇幅，input、label、form 组件代码与原内容一致，可直接复制使用。核心是基于 Radix UI 和 react-hook-form 的封装。）

步骤 4：创建登录表单组件（src/components/login-form.tsx）

import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import * as z from "zod"
import { Button } from "@/components/ui/button"
import {
  Form,
  FormControl,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from "@/components/ui/form"
import { Input } from "@/components/ui/input"
import { useState } from "react"
import { Eye, EyeOff, Loader2 } from "lucide-react"

const formSchema = z.object({
  email: z.string().email({ message: "请输入有效的电子邮件地址" }),
  password: z.string().min(6, { message: "密码至少需要6个字符" }),
})

type FormValues = z.infer<typeof formSchema>

export default function LoginForm() {
  const [showPassword, setShowPassword] = useState(false)
  const [isLoading, setIsLoading] = useState(false)

  const form = useForm<FormValues>({
    resolver: zodResolver(formSchema),
    defaultValues: { email: "", password: "" },
  })

  async function onSubmit(values: FormValues) {
    setIsLoading(true)
    await new Promise(resolve => setTimeout(resolve, 1500))
    console.log("表单提交数据:", values)
    alert(`登录成功！\n邮箱: ${values.email}`)
    setIsLoading(false)
  }

  return (
    <div className="mx-auto max-w-md space-y-8 p-6">
      <div className="space-y-2 text-center">
        <h1 className="text-3xl font-bold">欢迎回来</h1>
        <p className="text-muted-foreground">请输入您的凭据以登录您的账户</p>
      </div>

      <Form {...form}>
        <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
          {/* 邮箱字段 */}
          <FormField control={form.control} name="email" render={({ field }) => (
            <FormItem>
              <FormLabel>电子邮件</FormLabel>
              <FormControl>
                <Input placeholder="name@example.com" {...field} disabled={isLoading} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )} />

          {/* 密码字段 */}
          <FormField control={form.control} name="password" render={({ field }) => (
            <FormItem>
              <FormLabel>密码</FormLabel>
              <div className="relative">
                <FormControl>
                  <Input type={showPassword ? "text" : "password"} placeholder="••••••••" {...field} disabled={isLoading} className="pr-10" />
                </FormControl>
                <Button type="button" variant="ghost" size="icon" className="absolute right-0 top-0 h-full px-3"
                  onClick={() => setShowPassword(!showPassword)} disabled={isLoading}>
                  {showPassword ? <EyeOff className="h-4 w-4" /> : <Eye className="h-4 w-4" />}
                </Button>
              </div>
              <FormMessage />
            </FormItem>
          )} />

          <div className="text-right">
            <a href="#" className="text-sm text-primary hover:underline" onClick={e => { e.preventDefault(); alert("密码重置功能开发中...") }}>
              忘记密码？
            </a>
          </div>

          <Button type="submit" className="w-full" disabled={isLoading}>
            {isLoading ? (
              <> <Loader2 className="mr-2 h-4 w-4 animate-spin" /> 登录中... </>
            ) : "登录"}
          </Button>

          <div className="text-center text-sm">
            <span className="text-muted-foreground">还没有账户？</span>
            <a href="#" className="ml-1 text-primary hover:underline" onClick={e => { e.preventDefault(); alert("注册功能开发中...") }}>
              立即注册
            </a>
          </div>
        </form>
      </Form>

      {/* 按钮变体演示 */}
      <div className="space-y-4 pt-8 border-t">
        <h3 className="font-medium">按钮变体演示：</h3>
        <div className="flex flex-wrap gap-2">
          <Button variant="default">默认</Button>
          <Button variant="secondary">次要</Button>
          <Button variant="outline">轮廓</Button>
          <Button variant="destructive">危险</Button>
          <Button variant="ghost">幽灵</Button>
          <Button variant="link">链接</Button>
        </div>
      </div>
    </div>
  )
}

步骤 5：修改 App.tsx

import LoginForm from "./components/login-form"

function App() {
  return (
    <div className="min-h-screen bg-gradient-to-br from-gray-50 to-gray-100 flex items-center justify-center p-4">
      <div className="w-full max-w-md bg-white rounded-2xl shadow-xl overflow-hidden">
        <LoginForm />
      </div>
      <div className="absolute bottom-4 right-4 text-xs text-gray-500">
        使用 shadcn/ui 构建的 React 登录表单
      </div>
    </div>
  )
}

export default App

步骤 6：运行项目

npm run dev

访问 http://localhost:5173 即可看到完整效果。

高级扩展建议

1. 主题系统：在全局 CSS 中定义 CSS 变量，支持明暗模式切换。
2. 添加更多组件：使用官方 CLI（如 npx shadcn-ui@latest add checkbox）快速扩展。

这个实战充分体现了 shadcn/ui 的优势：完全可控、类型安全、无障碍支持、易于定制。希望这份整理对你有帮助！如果需要进一步扩展或针对特定项目给出建议，欢迎继续交流。