shadcn/ui 组件模式

使用 shadcn/ui 构建可访问、可定制的 UI 组件的专家指南。

安装

OpenClaw / Moltbot / Clawbot

bash
npx clawhub@latest install shadcn-ui

使用场景

• - 使用 shadcn/ui 搭建新项目
• 安装或配置单个组件
• 使用 React Hook Form 和 Zod 验证构建表单
• 创建可访问的 UI 组件（按钮、对话框、下拉菜单、侧边面板）
• 使用 Tailwind CSS 自定义组件样式
• 使用 shadcn/ui 实现设计系统
• 使用 TypeScript 构建 Next.js 应用

什么是 shadcn/ui？

一个可复用组件的集合，你可以将其复制到项目中——而不是一个 npm 包。代码归你所有。基于 Radix UI（可访问性）和 Tailwind CSS（样式）构建。

快速开始

bash

新建 Next.js 项目

安装组件

核心概念

cn 工具函数

合并 Tailwind 类名并解决冲突——每个组件中都会用到：

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

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

类方差授权（CVA）

管理组件变体——每个 shadcn/ui 组件背后的模式：

tsx
import { cva, type VariantProps } from class-variance-authority

const buttonVariants = cva(
inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors,
{
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,
secondary: bg-secondary text-secondary-foreground hover:bg-secondary/90,
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 },
}
)

核心组件

按钮

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

// 变体：default | destructive | outline | secondary | ghost | link
// 尺寸：default | sm | lg | icon
点击我

// 加载状态


请稍候

// 作为链接（使用 Radix Slot）

前往仪表盘

带验证的表单

标准模式：Zod 模式 + React Hook Form + shadcn 表单组件。

bash
npx shadcn@latest add form input select checkbox textarea

tsx
use client

import { zodResolver } from @hookform/resolvers/zod
import { useForm } from react-hook-form
import * as z from zod
import { Button } from @/components/ui/button
import {
Form, FormControl, FormDescription,
FormField, FormItem, FormLabel, FormMessage,
} from @/components/ui/form
import { Input } from @/components/ui/input
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from @/components/ui/select

const formSchema = z.object({
username: z.string().min(2, 用户名至少需要2个字符。),
email: z.string().email(请输入有效的邮箱地址。),
role: z.enum([admin, user, guest]),
})

export function ProfileForm() {
const form = useForm>({
resolver: zodResolver(formSchema),
defaultValues: { username: , email: , role: user },
})

function onSubmit(values: z.infer) {
console.log(values)
}

return (