shadcn-ui-expert

shadcn-ui 专家

shadcn-ui 是一套设计精美、易于访问的 React 组件，使用 TypeScript、Tailwind CSS 和 Radix UI 基础组件构建。本技能将指导你进行组件选择、实现、自定义和遵循最佳实践。

快速入门

安装

首先，在项目中初始化 shadcn-ui：

npx shadcn-ui@latest init

这会创建用于配置的 components.json 文件。选择你的框架：

• Next.js（推荐使用 App Router）
• Vite
• Remix
• Astro
• Laravel
• Gatsby
• React Router
• TanStack Router/Start

安装组件

使用 CLI 安装单个组件：

# Install a button component
npx shadcn-ui@latest add button

# Install form components
npx shadcn-ui@latest add form input select checkbox

# Install a data table
npx shadcn-ui@latest add data-table

或者直接让我“添加一个登录表单”——我可以使用 MCP 服务，通过自然语言处理安装。

组件分类

表单和输入组件

适用于：收集数据、用户输入、验证

• form - 使用 React Hook Form 构建复杂表单
• input - 文本字段
• textarea - 多行文本
• select - 下拉选择
• checkbox - 布尔输入
• radio-group - 从选项中单选
• switch - 切换布尔状态
• date-picker - 日期选择
• combobox - 支持搜索和自动补全的选择框

布局和导航

适用于：应用结构、导航流程、内容组织

• sidebar - 可折叠侧边导航
• tabs - 标签页内容
• accordion - 可折叠分区
• breadcrumb - 导航路径
• navigation-menu - 下拉菜单
• scroll-area - 自定义可滚动区域

覆盖层和对话框

适用于：模态框、确认操作、浮动内容

• dialog - 模态对话框
• alert-dialog - 确认提示
• drawer - 适合移动设备的侧面面板
• popover - 浮动弹出框
• tooltip - 悬停提示信息
• dropdown-menu - 下拉菜单
• context-menu - 右键菜单

数据展示

适用于：展示结构化数据

• table - 基本 HTML 表格
• data-table - 支持排序、筛选和分页的高级表格
• avatar - 用户个人资料图片
• badge - 状态标签
• card - 内容容器

反馈和状态

适用于：用户反馈、加载状态、提醒

• alert - 提醒消息
• toast - 通知
• progress - 进度条
• skeleton - 加载占位内容
• spinner - 加载指示器

组件选择指南

选择合适的组件时，可以问自己以下问题：

1. 用户正在与什么交互？

   • 文本输入 → 使用 input
   • 从选项中选择 → 使用 select 或 combobox
   • 是/否判断 → 使用 checkbox 或 switch
   • 多个字段 → 使用 form

2. 应该如何显示？

   • 与其他内容同行显示 → input、select
   • 屏幕居中显示 → dialog
   • 从侧边滑出 → drawer
   • 信息提示 → tooltip

3. 使用场景是什么？

   • 位于表单中 → 使用 form 搭配 field 组件
   • 独立按钮 → 使用 button
   • 位于表格中 → 使用表格行单元格或 data-table

4. 是否需要验证？

   • 需要 → 组合使用 form、field 和 React Hook Form
   • 不需要 → 使用简单组件（input、select）

常见实现模式

带验证的基本表单

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, FormField, FormItem, FormLabel, FormControl } from "@/components/ui/form"
import { Input } from "@/components/ui/input"

const formSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
})

export function LoginForm() {
  const form = useForm<z.infer<typeof formSchema>>({
    resolver: zodResolver(formSchema),
  })

  function onSubmit(values: z.infer<typeof formSchema>) {
    console.log(values)
  }

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-8">
        <FormField
          control={form.control}
          name="email"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Email</FormLabel>
              <FormControl>
                <Input placeholder="[email protected]" {...field} />
              </FormControl>
            </FormItem>
          )}
        />
        <Button type="submit">Submit</Button>
      </form>
    </Form>
  )
}

对话框模式

import { Button } from "@/components/ui/button"
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"

export function DeleteDialog() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="destructive">Delete</Button>
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Are you sure?</DialogTitle>
          <DialogDescription>
            This action cannot be undone.
          </DialogDescription>
        </DialogHeader>
        <div className="flex gap-3 justify-end">
          <Button variant="outline">Cancel</Button>
          <Button variant="destructive">Delete</Button>
        </div>
      </DialogContent>
    </Dialog>
  )
}

样式和自定义

所有组件都使用 Tailwind CSS 设置样式。可通过以下方式自定义外观：

1. Tailwind 类

直接向组件添加类：

<Button className="w-full text-lg">Full Width</Button>
<Input className="rounded-lg border-2" />

2. CSS 变量（主题颜色）

shadcn/ui 使用 CSS 变量设置主题。编辑 app/globals.css：

@layer base {
  :root {
    --primary: 222.2 47.4% 11.2%;
    --secondary: 210 40% 96%;
  }
}

3. 深色模式

在你的框架中启用深色模式：

• Next.js：在 next.config.js 中配置
• Vite：在 tailwind.config.js 中添加深色类检测
• 组件会自动响应 dark 类

4. 组件变体

许多组件内置了多种变体：

<Button variant="outline" />
<Button variant="ghost" />
<Button variant="destructive" />
<Badge variant="secondary" />

组合和最佳实践

1. 优先组合，而非自定义

组合小型组件，而不是修改大型组件：

// ✅ Good: Compose components
<Card>
  <CardHeader>
    <CardTitle>Title</CardTitle>
  </CardHeader>
  <CardContent>
    <Form>...</Form>
  </CardContent>
</Card>

// ❌ Avoid: Over-modifying single component
<CustomDialog withHeader={true} withForm={true} />

2. 使用类型安全

借助 TypeScript 确保属性安全：

import { Button } from "@/components/ui/button"
import type { ButtonProps } from "@/components/ui/button"

type CustomButtonProps = ButtonProps & {
  label: string
}

3. 内置无障碍功能

shadcn/ui 使用内置无障碍功能的 Radix UI 基元：

• 键盘导航
• ARIA 属性
• 屏幕阅读器支持
• 焦点管理

只需正确使用组件，无障碍功能便会自动生效。

4. 性能

• 组件精简且模块化
• 支持树摇
• 除 Radix UI 外没有运行时开销
• 如有需要，可对频繁重新渲染的组件使用 React.memo

框架专属说明

Next.js

• 使用 shadcn-ui@latest add form 集成 React Hook Form
• 结合 Server Actions 提交表单
• 暗色模式可通过 next-themes 实现

Vite

• 确保 tailwind.config.js 包含组件路径
• 使用 Vite 的 HMR 加快开发速度

Remix

• 表单可使用 remix 表单操作
• 使用路由切换实现乐观更新

常见自定义任务

更改主色

初始化时编辑 components.json，或手动更新 globals.css 中的 CSS 变量。

添加自定义组件

按照 shadcn/ui 的模式，在 components/ui/ 中创建自己的组件：

// components/ui/my-component.tsx
import * as React from "react"

export interface MyComponentProps
  extends React.HTMLAttributes<HTMLDivElement> {}

const MyComponent = React.forwardRef<HTMLDivElement, MyComponentProps>(
  ({ className, ...props }, ref) => (
    <div
      ref={ref}
      className={className}
      {...props}
    />
  )
)
MyComponent.displayName = "MyComponent"

export { MyComponent }

为多个品牌设置主题

使用 CSS 变量层：

.brand-a {
  --primary: 220 90% 56%;
  --secondary: 0 0% 100%;
}

.brand-b {
  --primary: 0 100% 50%;
  --secondary: 200 100% 50%;
}

验证与表单

使用 React Hook Form + Zod

复杂表单的最佳实践，支持客户端验证：

npm install react-hook-form zod @hookform/resolvers

使用 TanStack Form

满足高级表单需求的替代方案：

npm install @tanstack/react-form

如需特定表单模式（登录、注册、多步骤等），请向我咨询。

故障排除

组件样式不正确

• ✅ 确认 Tailwind 已在 tailwind.config.js 中正确配置
• ✅ 检查 components.json 中的 path 设置是否正确
• ✅ 添加组件后运行 npm install

TypeScript 错误

• ✅ 确保组件从 /components/ui/name 导入
• ✅ 组件已内置适当的 TypeScript 支持

表单验证不起作用

• ✅ 安装 zod 和 @hookform/resolvers
• ✅ 将 zodResolver 与 useForm 配合使用

后续步骤

如需了解特定任务的详细指南：

• COMPONENT_GUIDE.md - 深入了解各个组件
• FORMS_GUIDE.md - 构建复杂表单
• PATTERNS.md - 常见 UI 模式及组合
• CUSTOMIZATION.md - 主题与样式指南

资源

• shadcn/ui 文档
• Radix UI 基元
• Tailwind CSS
• React Hook Form
• Zod 验证