1 概述

在现代前端开发中，组件库扮演着至关重要的角色，它们帮助开发者快速构建用户界面，提高开发效率。然而，传统的组件库往往在定制性和灵活性方面存在局限。当项目需要高度定制化的设计或特定的交互逻辑时，开发者常常发现自己受限于组件库的预设样式和行为。正是在这样的背景下，shadcn/ui 应运而生，它以一种独特的方式解决了这些痛点，为前端开发者提供了一个全新的 UI 构建范式。

shadcn/ui 并非一个传统的 npm 包形式的组件库，它更像是一个代码分发平台。这意味着你不会通过 npm install shadcn-ui 来安装它，而是通过命令行工具将组件的源代码直接添加到你的项目中。这种方法赋予了开发者对组件的完全控制权，你可以随意修改、扩展和定制每一个组件，使其完美契合项目的需求。

其核心特点包括：

• 极致的可定制性：基于 Radix UI Primitives 提供无障碍的基础组件，并结合 Tailwind CSS 进行样式定义，使得每一个组件都能深度定制，满足各种设计系统要求。
• 卓越的可访问性：得益于 Radix UI 的设计哲学，所有组件都内置了良好的可访问性支持，确保产品符合无障碍标准。
• 开发者完全控制：组件代码直接集成到项目中，开发者可以像编写自己的代码一样修改和维护，避免了传统组件库的“黑盒”问题。
• 轻量与高效：按需引入组件，只包含项目实际使用的代码，有效减少了最终打包体积，提升应用性能。
• TypeScript 优先：所有组件都使用 TypeScript 编写，提供了强大的类型支持和开发体验。

2 为什么选择 shadcn/ui

选择 shadcn/ui 意味着拥抱一种更加灵活和可控的开发模式。以下是几个选择 shadcn/ui 的主要理由：

• 开发者控制权：这是 shadcn/ui 最显著的优势。当组件代码直接位于你的项目之中时，你不再受限于组件库的 API 或主题配置。你可以根据需要修改任何一行代码，无论是调整样式、改变行为还是添加新的功能。这对于需要高度定制化或拥有独特设计系统的项目来说，是无价的。
• 灵活性和定制化：shadcn/ui 结合了 Radix UI 和 Tailwind CSS 的强大功能。Radix UI 提供了高质量、无样式的可访问组件原语，处理了复杂的交互逻辑和可访问性问题。而 Tailwind CSS 则提供了极大的样式灵活性，允许开发者通过组合实用程序类来构建任何设计，而无需编写自定义 CSS。这种组合使得组件的定制变得前所未有的简单和强大。
• 性能优化：由于组件是按需引入的，并且其代码直接合并到你的项目中，这意味着你的最终 bundle 中只包含你实际使用的组件代码。这避免了传统组件库可能带来的不必要代码膨胀，从而有助于提升应用的加载速度和整体性能。
• 与现代前端生态的良好集成：shadcn/ui 与 Next.js、Vite 等现代前端框架以及 TypeScript 提供了无缝的集成体验。它鼓励使用最新的前端技术栈，并提供了清晰的文档和示例，帮助开发者快速上手。

3 如何开始使用 shadcn/ui

开始使用 shadcn/ui 并不复杂，但需要一些前期的环境准备和配置步骤。本节将以一个典型的 React 项目为例，指导你如何初始化并添加第一个 shadcn/ui 组件。

3.1 环境准备

在开始之前，请确保你的开发环境中已安装以下工具：

• Node.js：版本 18.x 或更高。
• 包管理器：npm、yarn 或 pnpm（推荐 pnpm）。
• 一个 React 项目：可以是基于 Next.js、Vite 或其他框架创建的。

3.2 安装与配置

首先，导航到你的项目根目录，并运行 shadcn/ui 的初始化命令：

npx shadcn-ui@latest init

该命令会引导你完成一系列配置选项，包括：

• 样式库：选择 Tailwind CSS。
• 基础颜色：选择你喜欢的基础颜色。
• 全局 CSS 文件路径：通常是 src/app/globals.css 或 src/index.css。
• Tailwind CSS 配置文件路径：通常是 tailwind.config.js。
• 组件路径别名：推荐 @/components。
• 工具函数路径别名：推荐 @/lib/utils。
• React Server Components：根据你的项目是否使用 RSC 进行选择。

完成配置后，shadcn/ui 会在你的项目中创建必要的配置文件和目录结构。

3.3 添加第一个组件：以 Button 组件为例

现在，你可以开始添加第一个 shadcn/ui 组件了。我们以 Button 组件为例：

npx shadcn-ui@latest add button

运行此命令后，shadcn/ui 会将 Button 组件的 TypeScript 和 Tailwind CSS 代码下载到你配置的组件路径（例如 src/components/ui/button.tsx）中。现在，你可以在你的 React 组件中导入并使用它了：

// src/app/page.tsx 或其他 React 组件文件
import { Button } from "@/components/ui/button"

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-between p-24">
      <Button onClick={() => console.log("Button clicked!")}>
        点击我
      </Button>
    </main>
  )
}

通过这种方式，你就可以将 shadcn/ui 的组件逐步集成到你的项目中，并根据需要进行修改。

4 shadcn/ui 的核心概念

理解 shadcn/ui 的核心概念对于充分利用其优势至关重要。它主要围绕以下几个关键技术和思想构建：

4.1 Radix UI Primitives

Radix UI 是一个高质量、无样式、可访问的 UI 组件库，它专注于提供基础组件原语（Primitives）。这些原语处理了复杂的交互逻辑、键盘导航、焦点管理和可访问性属性（如 ARIA 属性），但不提供任何视觉样式。这意味着开发者可以完全自由地定义组件的外观，而无需担心底层交互的实现。

shadcn/ui 利用 Radix UI Primitives 作为其组件的功能骨架。例如，一个 Button 组件可能使用 Radix UI 的 Primitive.Button 来确保其具备正确的 HTML 语义和可访问性行为，而其视觉样式则完全由 Tailwind CSS 控制。

4.2 Tailwind CSS

Tailwind CSS 是一个实用程序优先的 CSS 框架，它通过提供大量低级别的实用程序类来帮助你直接在标记中构建任何设计。与传统的语义化 CSS 类（如 btn-primary）不同，Tailwind CSS 鼓励你通过组合 flex、pt-4、text-center、bg-blue-500 等类来构建样式。这种方法极大地提高了样式构建的灵活性和开发速度。

在 shadcn/ui 中，所有组件的样式都使用 Tailwind CSS 定义。这意味着当你将组件代码添加到项目中时，你可以直接在 JSX 中修改其 className 属性，或者在组件内部的 cn 函数（一个用于条件性地合并 Tailwind CSS 类的工具函数）中调整样式，从而实现无与伦比的定制能力。

4.3 组件代码的导入与修改

如前所述，shadcn/ui 的核心理念是代码所有权。当你通过 npx shadcn-ui@latest add <component-name> 命令添加一个组件时，实际上是将该组件的 TypeScript 和 Tailwind CSS 代码复制到你的项目中。这意味着：

• 完全可编辑：你可以像修改自己编写的代码一样修改这些组件。这包括调整 JSX 结构、修改 Tailwind CSS 类、添加新的 props 或改变内部逻辑。
• 易于维护：由于代码在你的项目中，你可以使用版本控制系统（如 Git）来跟踪对这些组件的修改，并将其与其他项目代码一起维护。
• 无版本锁定：你不会被组件库的版本更新所束缚。即使 shadcn/ui 发布了新版本，你也可以选择性地更新或不更新你的组件，或者手动合并你需要的更改。

这种模式使得 shadcn/ui 成为构建高度定制化设计系统的理想选择，它在提供高质量基础组件的同时，又赋予了开发者最大的自由度。

5 TypeScript React 代码示例

本节将通过具体的 TypeScript React 代码示例，展示如何在项目中有效地使用 shadcn/ui 组件，并进行简单的定制。

5.1 Button 组件的使用

Button 是一个基础且常用的组件。通过 shadcn/ui，你可以轻松地添加和定制它。

首先，确保你已经通过 npx shadcn-ui@latest add button 命令将 Button 组件添加到你的项目中。

// src/components/MyButtons.tsx
import React from 'react'
import { Button } from "@/components/ui/button"

const MyButtons: React.FC = () => {
  return (
    <div className="flex gap-4 p-8">
      <Button onClick={() => console.log("Default Button clicked!")}>
        默认按钮
      </Button>
      <Button variant="outline" onClick={() => console.log("Outline Button clicked!")}>
        边框按钮
      </Button>
      <Button variant="secondary" onClick={() => console.log("Secondary Button clicked!")}>
        次要按钮
      </Button>
      <Button variant="destructive" onClick={() => console.log("Destructive Button clicked!")}>
        危险按钮
      </Button>
      <Button disabled onClick={() => console.log("Disabled Button clicked!")}>
        禁用按钮
      </Button>
    </div>
  )
}

export default MyButtons

在上面的示例中，我们展示了 Button 组件的不同 variant 属性。这些 variant 是在 src/components/ui/button.tsx 文件中通过 cva (Class Variance Authority) 定义的，你可以直接修改该文件来添加或调整 variant 的样式。

5.2 Card 组件的使用

Card 组件常用于展示内容块。shadcn/ui 提供了灵活的 Card 组件，可以轻松地组合 CardHeader、CardTitle、CardDescription、CardContent 和 CardFooter 来构建复杂的卡片布局。

首先，添加 Card 组件：

npx shadcn-ui@latest add card

然后，在你的 React 组件中使用它：

// src/components/MyCard.tsx
import React from 'react'
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card"
import { Button } from "@/components/ui/button"

const MyCard: React.FC = () => {
  return (
    <Card className="w-[350px]">
      <CardHeader>
        <CardTitle>创建新项目</CardTitle>
        <CardDescription>部署你的新项目到 Vercel。</CardDescription>
      </CardHeader>
      <CardContent>
        <form>
          <div className="grid w-full items-center gap-4">
            <div className="flex flex-col space-y-1.5">
              <label htmlFor="name">项目名称</label>
              <input id="name" placeholder="你的项目名称" />
            </div>
            <div className="flex flex-col space-y-1.5">
              <label htmlFor="framework">框架</label>
              <select id="framework">
                <option value="next">Next.js</option>
                <option value="react">React</option>
                <option value="vue">Vue</option>
              </select>
            </div>
          </div>
        </form>
      </CardContent>
      <CardFooter className="flex justify-between">
        <Button variant="outline">取消</Button>
        <Button>部署</Button>
      </CardFooter>
    </Card>
  )
}

export default MyCard

这个示例展示了如何使用 Card 及其子组件来构建一个包含表单元素的卡片。你可以通过修改 className 属性来调整卡片的宽度、边距等样式。

5.3 自定义组件样式

shadcn/ui 的强大之处在于其易于定制。你可以通过多种方式修改组件的样式：

1. 直接修改组件文件：由于组件代码在你的项目中，你可以直接打开 src/components/ui/button.tsx 或 src/components/ui/card.tsx 文件，修改其中的 Tailwind CSS 类或 JSX 结构。例如，如果你想改变所有 Button 的默认圆角，可以直接修改 button.tsx 文件中的 rounded-md 类。

2. 通过 className 属性覆盖：对于单个组件实例，你可以通过传递 className 属性来添加或覆盖默认的 Tailwind CSS 类。例如：

   <Button className="bg-purple-500 hover:bg-purple-600 text-white">
     紫色按钮
   </Button>
   

3. 使用 cn 工具函数：shadcn/ui 推荐使用一个名为 cn 的工具函数（通常定义在 src/lib/utils.ts 中，基于 clsx 和 tailwind-merge）来合并和解决 Tailwind CSS 类的冲突。这使得条件性地应用样式变得非常方便。

   import { cn } from "@/lib/utils"
   
   interface CustomButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
     isActive?: boolean
   }
   
   const CustomButton: React.FC<CustomButtonProps> = ({ isActive, className, children, ...props }) => {
     return (
       <Button
         className={cn(
           "px-4 py-2 rounded-lg",
           isActive ? "bg-blue-500 text-white" : "bg-gray-200 text-gray-800",
           className
         )}
         {...props}
       >
         {children}
       </Button>
     )
   }
   
   // 使用示例
   <CustomButton isActive={true}>激活状态</CustomButton>
   <CustomButton isActive={false}>非激活状态</CustomButton>
   

通过这些方法，你可以灵活地控制 shadcn/ui 组件的样式，使其完美融入你的设计系统。

6 最佳实践与进阶

为了更高效、更优雅地使用 shadcn/ui，以下是一些最佳实践和进阶技巧：

6.1 主题定制

shadcn/ui 的主题定制主要通过修改 tailwind.config.js 文件和全局 CSS 变量来实现。你可以在 tailwind.config.js 中扩展颜色、字体、间距等，并在全局 CSS 文件（如 src/app/globals.css）中定义 CSS 变量，以支持亮/暗模式切换或其他主题需求。

例如，定义自定义颜色：

// tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...其他配置
  theme: {
    extend: {
      colors: {
        primary: {
          DEFAULT: "hsl(var(--primary))",
          foreground: "hsl(var(--primary-foreground))",
        },
        // ...其他颜色
      },
    },
  },
  // ...
}

/* src/app/globals.css */
@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --primary: 222.2 47.4% 11.2%;
    --primary-foreground: 210 40% 98%;
    /* ...其他变量 */
  }

  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    --primary: 217.2 91.2% 59.8%;
    --primary-foreground: 222.2 47.4% 11.2%;
    /* ...其他变量 */
  }
}

通过修改这些变量，你可以全局控制组件的颜色方案，实现品牌一致性。

6.2 组件扩展与组合

shadcn/ui 的组件是基础构建块，你可以将它们组合起来创建更复杂的 UI 模式。例如，你可以将 Input 和 Button 组合成一个搜索框组件，或者将多个 Card 组合成一个仪表盘布局。

此外，由于你拥有组件的源代码，你可以直接在现有组件的基础上进行扩展，添加新的 props 或逻辑，而无需等待上游库的更新。

6.3 与表单库集成

在实际应用中，shadcn/ui 组件经常需要与表单管理库（如 React Hook Form、Formik 或 Zod）集成。由于 shadcn/ui 组件是标准的 React 组件，它们可以无缝地与这些库配合使用。

例如，使用 React Hook Form 和 shadcn/ui 的 Input 组件：

// src/components/MyForm.tsx
import React from 'react'
import { useForm } from "react-hook-form"
import { z } from "zod"
import { zodResolver } from "@hookform/resolvers/zod"
import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import {
  Form,
  FormControl,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from "@/components/ui/form"

// 确保你已经添加了 input 和 form 组件
// npx shadcn-ui@latest add input
// npx shadcn-ui@latest add form

const formSchema = z.object({
  username: z.string().min(2, { message: "用户名至少需要 2 个字符" }),
  email: z.string().email({ message: "请输入有效的邮箱地址" }),
})

type FormData = z.infer<typeof formSchema>

const MyForm: React.FC = () => {
  const form = useForm<FormData>({
    resolver: zodResolver(formSchema),
    defaultValues: {
      username: "",
      email: "",
    },
  })

  const onSubmit = (values: FormData) => {
    console.log("表单提交数据:", values)
  }

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-8 p-8">
        <FormField
          control={form.control}
          name="username"
          render={({ field }) => (
            <FormItem>
              <FormLabel>用户名</FormLabel>
              <FormControl>
                <Input placeholder="shadcn" {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />
        <FormField
          control={form.control}
          name="email"
          render={({ field }) => (
            <FormItem>
              <FormLabel>邮箱</FormLabel>
              <FormControl>
                <Input type="email" placeholder="your@example.com" {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />
        <Button type="submit">提交</Button>
      </form>
    </Form>
  )
}

export default MyForm

这个示例展示了如何将 shadcn/ui 的 Input 和 Form 组件与 React Hook Form 结合，实现表单验证和提交。FormField 组件负责将表单状态和验证信息传递给 shadcn/ui 的 Input 组件，并显示验证错误信息。

7 总结

shadcn/ui 以其独特的代码分发模式，在前端组件库领域开辟了一条新路径。它不仅仅提供了一套美观、可访问的 UI 组件，更重要的是，它将控制权完全交还给开发者。通过结合 Radix UI 的强大功能和 Tailwind CSS 的灵活性，shadcn/ui 使得构建高度定制化、高性能的现代前端应用变得前所未有的简单和高效。

对于那些追求极致定制、注重性能优化，并且希望对项目代码拥有完全控制权的开发者和团队来说，shadcn/ui 无疑是一个极具吸引力的选择。它鼓励开发者深入理解和修改组件，从而更好地融入项目的整体架构和设计系统。随着前端技术的不断发展，shadcn/ui 这种“拥有代码而非依赖”的理念，很可能会成为未来前端开发的一个重要趋势。

8 参考文献

• shadcn/ui 官方网站
• Radix UI 官方网站
• Tailwind CSS 官方网站
• React Hook Form 官方网站
• Zod 官方网站