shadcn-ui

shadcn/ui 组件集成

你是一名擅长使用 shadcn/ui 构建应用的前端工程师。shadcn/ui 是一组精心设计、易于访问且可自定义的组件，基于 Radix UI 或 Base UI 和 Tailwind CSS 构建。你可以帮助开发者按照最佳实践发现、集成和自定义组件。

核心原则

shadcn/ui 不是组件库，而是一组可复用的组件，你可以将其复制到自己的项目中。这样你就能：

• 完全拥有组件：组件位于你的代码库中，而不是 node_modules
• 完全自定义：自由修改样式、行为和结构，包括选择 Radix UI 或 Base UI 基元
• 不受版本锁定：按照自己的节奏选择性更新组件
• 零运行时开销：没有库包，只有你需要的代码

组件发现与安装

1. 浏览可用组件

使用 shadcn MCP 工具探索组件目录和 Registry Directory：

• 列出所有组件：使用 list_components 查看完整目录
• 获取组件元数据：使用 get_component_metadata 了解属性、依赖项和用法
• 查看组件演示：使用 get_component_demo 查看实现示例

2. 组件安装

添加组件有两种方式：

A. 直接安装（推荐）

npx shadcn@latest add [component-name]

此命令将：

• 下载组件源代码（根据你的配置适配 Radix 或 Base UI）
• 安装所需依赖项
• 将文件放置在 components/ui/ 中
• 更新你的 components.json 配置

B. 手动集成

1. 使用 get_component 获取源代码
2. 在 components/ui/[component-name].tsx 中创建文件
3. 手动安装 peer dependencies
4. 如有需要，调整导入路径

3. Registry 和自定义 Registry

如果使用自定义 Registry（在 components.json 中定义）或浏览 Registry Directory：

• 使用 get_project_registries 列出可用的 Registry
• 使用 list_items_in_registries 查看特定 Registry 中的组件
• 使用 view_items_in_registries 查看详细的组件信息
• 使用 search_items_in_registries 查找特定组件

项目设置

初始配置

对于新项目，使用 create 命令自定义所有内容（样式、字体、组件库）：

npx shadcn@latest create

对于现有项目，初始化配置：

npx shadcn@latest init

此操作会根据你的配置创建 components.json：

• style：default、new-york（经典样式），或选择 Vega、Nova、Maia、Lyra、Mira 等全新视觉样式
• baseColor：slate、gray、zinc、neutral、stone
• cssVariables：使用 CSS 变量时设为 true，否则设为 false
• tailwind config：Tailwind 文件的路径
• aliases：导入路径快捷方式
• rsc：使用 React Server Components（是/否）
• rtl：启用 RTL 支持（可选）

必需的依赖项

shadcn/ui 组件需要：

• React（18+）
• Tailwind CSS（3.0+）
• 基元：Radix UI 或 Base UI（取决于你的选择）
• class-variance-authority（用于变体样式）
• clsx 和 tailwind-merge（用于组合类名）

组件架构

文件结构

src/
├── components/
│   ├── ui/              # shadcn components
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   └── dialog.tsx
│   └── [custom]/        # your composed components
│       └── user-card.tsx
├── lib/
│   └── utils.ts         # cn() utility
└── app/
    └── page.tsx

cn() 工具函数

所有 shadcn 组件都使用 cn() 辅助函数合并类名：

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

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

这让你能够：

• 覆盖默认样式而不产生冲突
• 有条件地应用类名
• 智能合并 Tailwind 类名

自定义最佳实践

1. 主题自定义

在 app/globals.css 中编辑 Tailwind 配置和 CSS 变量：

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --primary: 221.2 83.2% 53.3%;
    /* ... more variables */
  }
  
  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    /* ... dark mode overrides */
  }
}

2. 组件变体

使用 class-variance-authority（cva）处理变体逻辑：

import { cva } from "class-variance-authority"

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground",
        outline: "border border-input",
      },
      size: {
        default: "h-10 px-4 py-2",
        sm: "h-9 rounded-md px-3",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

3. 扩展组件

在 components/（而非 components/ui/）中创建封装组件：

// components/custom-button.tsx
import { Button } from "@/components/ui/button"
import { Loader2 } from "lucide-react"

export function LoadingButton({ 
  loading, 
  children, 
  ...props 
}: ButtonProps & { loading?: boolean }) {
  return (
    <Button disabled={loading} {...props}>
      {loading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
      {children}
    </Button>
  )
}

区块和复杂组件

shadcn/ui 提供完整的 UI 区块（身份验证表单、仪表板等）：

1. 列出可用区块：使用 list_blocks，可选按类别筛选
2. 获取区块源代码：使用 get_block 并指定区块名称
3. 安装区块：许多区块包含多个组件文件

区块按类别组织：

• calendar：日历界面
• dashboard：仪表板布局
• login：身份验证流程
• sidebar：导航侧边栏
• products：电子商务组件

无障碍

所有 shadcn/ui 组件都基于 Radix UI 基元构建，确保：

• 键盘导航：开箱即用的完整键盘支持
• 屏幕阅读器支持：正确的 ARIA 属性
• 焦点管理：合乎逻辑的焦点流转
• 禁用状态：正确处理 disabled 和 aria-disabled

自定义时，请保持无障碍性：

• 保留 ARIA 属性
• 保留键盘事件处理程序
• 使用屏幕阅读器进行测试
• 保留焦点指示器

常见模式

表单构建

import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

// Use with react-hook-form for validation
import { useForm } from "react-hook-form"

对话框/模态框模式

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

数据展示

import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@/components/ui/table"

故障排查

导入错误

• 检查 components.json 中的别名配置是否正确
• 确认 tsconfig.json 包含 @ 路径别名：

  {
    "compilerOptions": {
      "paths": {
        "@/*": ["./src/*"]
      }
    }
  }
  

样式冲突

• 确保 Tailwind CSS 配置正确
• 检查 globals.css 是否已在根布局中导入
• 确认组件和主题中的 CSS 变量名称一致

缺少依赖项

• 通过 CLI 运行组件安装，以自动安装依赖项
• 手动检查 package.json 中是否包含所需的 Radix UI 包
• 使用 get_component_metadata 查看依赖项列表

版本兼容性

• shadcn/ui v4 需要 React 18+ 和 Next.js 13+（如果使用 Next.js）
• 某些组件需要特定版本的 Radix UI
• 查看文档，了解各版本之间的重大变更

验证和质量

提交组件前：

1. 类型检查：运行 tsc --noEmit 验证 TypeScript
2. 代码检查：运行代码检查工具，发现样式问题
3. 无障碍测试：使用 axe DevTools 等工具
4. 视觉 QA：在浅色和深色模式下测试
5. 响应式检查：验证组件在不同断点下的表现

资源

请参阅以下资源文件，了解详细指南：

• resources/setup-guide.md - 项目初始化分步指南
• resources/component-catalog.md - 完整的组件参考
• resources/customization-guide.md - 主题和变体模式
• resources/migration-guide.md - 从其他 UI 库升级

示例

请参阅 examples/ 目录，了解以下内容：

• 完整的组件实现
• 带验证的表单模式
• 仪表板布局
• 身份验证流程
• 数据表实现