# shadcn/ui 专家使用 shadcn/ui 构建 UI 的综合指南——基于 Radix UI 原语和 Tailwind CSS 构建的复制粘贴组件库。组件不作为依赖项安装；它们被复制到您的项目中以获得完全所有权和定制。 ## 何时申请在以下情况下使用此技能： * 将 shadcn/ui 组件添加到 React 或 Next.js 项目 * 自定义组件样式、变体或行为 * 使用 CSS 变量设置 Tailwind CSS v4 主题 * 使用 shadcn/ui 实现深色模式 * 构建可访问的表单、对话框或数据表 * 在 shadcn/ui 组件和自定义实现之间进行选择 ## 核心概念 ### shadcn/ui 不是组件库 shadcn/ui 是您复制到项目中的可重用组件的集合。与传统图书馆的主要区别： * **没有 npm 包依赖** \-- 组件存在于您的代码库中 * **完全所有权** \--自由修改任何组件 * **Radix UI 基元** \-- 可访问的、无样式的无头组件 * **Tailwind CSS** \-- 通过实用程序类和 CSS 变量进行所有样式设置 * **CLI 驱动** \-- `npx shadcn@latest add button` 复制组件代码 ### 架构你的项目组件/ ui/ <- shadcn/ui 组件位于此处按钮.tsx 对话框.tsx 输入.tsx ... 库/ utils.ts <- cn() 实用程序（clsx + tailwind-merge） ## 设置 ### Next.js 应用程序路由器（推荐） # 在现有 Next.js 项目中初始化 shadcn/ui npx shadcn@最新 init # 这将创建： # - Components.json（配置） # - lib/utils.ts（cn 实用程序） # - globals.css 中的 Tailwind CSS 变量主题 **components.json 配置：** { "$schema": "https://ui.shadcn.com/schema.json", “风格”：“纽约”， “rsc”：正确， “tsx”：正确， “顺风”：{ "config": "tailwind.config.ts", "css": "app/globals.css", “baseColor”：“锌”， “cssVariables”：true }, “别名”：{ “组件”：“@/组件”， "utils": "@/lib/utils", "ui": "@/components/ui", “lib”：“@/lib”， “钩子”：“@/钩子” } } ### 投票+反应 # 初始化 npx shadcn@最新 init # Vite 需要 vite.config.ts 中的路径别名：从“路径”导入路径；导出默认的defineConfig({ 解决：{ 别名：{ '@': path.resolve(__dirname, './src'), }, }, }); ### Next.js 页面路由器与 App Router 相同，但在 Components.json 中设置 `rsc: false`，因为 Pages Router 不支持 React Server 组件。 ## 添加组件 # 添加单个组件 npx shadcn@最新添加按钮 # 添加多个组件 npx shadcn@latest 添加按钮卡输入标签 # 添加所有组件 npx shadcn@最新添加--全部 # 查看可用组件 npx shadcn@最新添加--列表 ### cn() 实用程序每个 shadcn/ui 组件都使用 `cn()` 进行条件类合并： // lib/utils.ts 从 'clsx' 导入 { clsx, type ClassValue }; 从 'tailwind-merge' 导入 { twMerge }；导出函数 cn(...输入: ClassValue[]) { 返回 twMerge(clsx(输入)); } `cn()` 将 `clsx` （条件类）与 `tailwind-merge` （解决 Tailwind 冲突）结合起来： <按钮类名={cn( 'bg-主要文本-白色', isDisabled && 'opacity-50 不允许光标', 大小 === 'lg' && 'px-8 py-4 文本-lg' )} > 提交 ## 使用 CSS 变量进行主题化 ### Tailwind CSS v4 主题设置 shadcn/ui 使用 CSS 自定义属性进行主题化，启用运行时主题切换： /* 全局.css */ @tailwind基地； @tailwind组件； @tailwind实用程序； @层基础{ ：根{ --背景：0 0% 100%； --前景：240 10% 3.9%； --卡：0 0% 100%； --卡前景：240 10% 3.9%； --弹出窗口：0 0% 100%； --popover-前景：240 10% 3.9%； ——小学：240 5.9% 10%； --主要前景：0 0% 98%； ——中学：240 4.8% 95.9%； --次要前景：240 5.9% 10%； --静音：240 4.8% 95.9%； --静音前景：240 3.8% 46.1%； --口音：240 4.8% 95.9%； --重音-前景：240 5.9% 10%； --破坏性：0 84.2% 60.2%； --破坏性前景：0 0% 98%； --边界：240 5.9% 90%； --输入：240 5.9% 90%； ——环：240 5.9% 10%； --半径：0.5rem； } .暗{ --背景：240 10% 3.9%； --前景：0 0% 98%； ——卡：240 10% 3.9%； --卡前景: 0 0% 98%; --弹出窗口：240 10% 3.9%； --popover-前景：0 0% 98%； --主要：0 0% 98%； --主前景：240 5.9% 10%； ——中学：240 3.7% 15.9%； --次要前景：0 0% 98%； --静音：240 3.7% 15.9%； --静音前景：240 5% 64.9%； --口音：240 3.7% 15.9%； --重音前景：0 0% 98%； --破坏性：0 62.8% 30.6%； --破坏性前景：0 0% 98%； ——边境：240 3.7% 15.9%； --输入：240 3.7% 15.9%； ——环：240 4.9% 83.9%； } } ### 深色模式实现对 Next.js 暗模式使用“next-themes”： // 应用程序/providers.tsx '使用客户端'；从“下一个主题”导入{ThemeProvider}；导出函数 Providers({ Children }: { Children: React.ReactNode }) { 返回（ {孩子} ）； } // 应用程序/layout.tsx 从 './providers' 导入 { Providers }；导出默认函数 RootLayout({ Children }) { 返回（ <正文> <提供商>{子级} ）； } 切换组件： '使用客户端'；从“下一个主题”导入{useTheme}；从'@/components/ui/button'导入{Button}；从 'lucide-react' 导入 { Moon, Sun }; 导出函数 ThemeToggle() { const { setTheme, 主题 } = useTheme(); 返回（ <按钮变体=“幽灵” 大小=“图标” onClick={() => setTheme(主题 === '暗' ? '亮' : '暗')} > 切换主题）； } ## 常见组件模式 ### 使用 React Hook Form + Zod 构建表单 '使用客户端'；从 '@hookform/resolvers/zod' 导入 { zodResolver }；从'react-hook-form'导入{useForm}；从 'zod' 导入 * as z；从'@/components/ui/button'导入{Button}；导入{ 形式，表单控件，表单字段，表单项，表单标签，表单消息，来自 '@/components/ui/form'; 从'@/components/ui/input'导入{输入}； const formSchema = z.object({ email: z.string().email('无效的电子邮件地址'), 密码: z.string().min(8, '密码必须至少8个字符'), }); 导出函数LoginForm() { const form = useForm>({ 解析器：zodResolver(formSchema), 默认值：{电子邮件：''，密码：''}， }); 函数 onSubmit(值: z.infer) { 控制台.log(值); } 返回（ <表格{...表格}>

<表单域控制={form.control} 姓名=“电子邮件” 渲染={({字段})=>( <表单项> 电子邮件 <表单控件> <输入占位符=“name@example.com”{...字段} /> <表单消息/> )} /> <表单域控制={form.control} 名称=“密码” 渲染={({字段})=>( <表单项> 密码 <表单控件> <输入类型=“密码”{...字段} /> <表单消息/> )} /> ）； } ### 带有 TanStack 表的数据表导入{ 表，桌体，表格单元格，桌头，表头，表行，来自 '@/components/ui/table'; 从 '@tanstack/react-table' 导入 { ColumnDef, flexRender, getCoreRowModel, useReactTable }; 接口 DataTableProps { 列：ColumnDef[]; 数据：TData[]； } 导出函数 DataTable({ columns, data }: DataTableProps) { 常量表 = useReactTable({ 数据，列，获取CoreRowModel: getCoreRowModel(), }); 返回（

<表> <表头> {table.getHeaderGroups().map(headerGroup => ( {headerGroup.headers.map(标题=>( {flexRender(header.column.columnDef.header, header.getContext())} ))} ))} <表体> {table.getRowModel().rows.map(行=>( {row.getVisibleCells().map(单元格 => ( {flexRender(cell.column.columnDef.cell, cell.getContext())} ))} ))}

）； } ### 响应式对话框/抽屉模式在桌面上使用 Dialog，在移动设备上使用 Drawer： '使用客户端'；从 '@/hooks/use-media-query' 导入 { useMediaQuery }；从 '@/components/ui/dialog' 导入 { Dialog, DialogContent, DialogTrigger }; 从'@/components/ui/drawer'导入{Drawer，DrawerContent，DrawerTrigger}；从'@/components/ui/button'导入{Button}；导出函数 ResponsiveModal({ 孩子 }: { 孩子: React.ReactNode }) { const isDesktop = useMediaQuery('(最小宽度：768px)'); 如果（是桌面）{ 返回（ <对话框> <按钮>打开 {children} ）； } 返回（ <抽屉> <按钮>打开 {children} ）； } ## 辅助功能模式 shadcn/ui 组件基于 Radix UI 构建，它提供： * 全键盘导航（Tab、箭头键、Enter、Escape） * ARIA 属性（角色、状态、属性） * 焦点管理（陷印、恢复） * 屏幕阅读器公告 ### 组件的主要辅助功能组件|键盘|阿丽亚 |焦点陷阱 ---|---|---|--- 按钮|输入/空格激活 |角色=“按钮”|否对话|逃脱关闭|角色=“对话”，咏叹调模式|是的下拉菜单|方向键导航 |角色=“菜单”，角色=“菜单项”|是的选择 |方向键，提前输入 |角色=“列表框”，角色=“选项”|是的标签 |选项卡之间的箭头键 |角色=“tablist”，角色=“选项卡”|否吐司|自动公告 |角色=“状态”，aria-live |否工具提示|焦点/悬停显示 |角色=“工具提示”|否 ### 自定义辅助功能增强 // 始终为交互元素提供标签 <按钮 aria-label="关闭对话框"> // 对纯视觉内容使用 sr-only 正在加载... // 公布动态内容

{状态消息}

## 反模式 * 不要将 shadcn/ui 安装为 npm 包——使用 CLI 复制组件 * 不要直接修改 Radix 原语——通过 shadcn 包装器组件扩展 * 不要使用硬编码颜色——始终使用 CSS 变量主题标记 * 不要跳过 `cn()` 实用程序——它可以防止 Tailwind 类冲突 * 使用下一个主题时，不要忘记 `` 上的 `suppressHydrationWarning` * 不要嵌套交互元素（按钮内有按钮，按钮内有链接） ## 铁律 1. **永远不要**将 shadcn/ui 安装为包依赖项 — 必须将组件复制到项目中以获得完全所有权 2. **始终**使用 `cn()` 实用程序作为条件类名称，以防止 Tailwind 类冲突 3. **绝不** 硬编码颜色 — 始终使用 CSS 变量主题标记来保持主题一致性 4. **始终**通过 shadcn/ui 抽象而不是直接使用 Radix UI 原语 5. **切勿** 嵌套交互元素（按钮内的按钮、按钮内的链接）——违反可访问性标准 ## 反模式反模式|为什么失败 |正确的做法 ---|---|--- 作为软件包安装 |组件来源被锁定；无法定制|使用“npx shadcn@latest add”将组件复制到您的项目中硬编码颜色值 |主题切换中断；深色模式失败 |使用 CSS 变量标记（`bg-background`、`text-foreground` 等）跳过 `cn()` 实用程序 |顺风的阶级冲突产生不可预测的风格|始终使用“@/lib/utils”中的“cn()”合并类直接 Radix UI 原语使用 |缺少 shadcn 样式和可访问性接线 |使用 shadcn 组件用正确的类包装 Radix 原语缺少`suppressHydrationWarning` |下一个主题深色模式出现水合作用不匹配错误 |使用下一个主题时将 `suppressHydrationWarning` 添加到 `` ## 内存协议（强制） **开始之前：**阅读 `.claude/context/memory/learnings.md` **完成后：** * 新模式 -> `.claude/context/memory/learnings.md` * 发现问题 -> `.claude/context/memory/issues.md` * 做出决定 -> `.claude/context/memory/decisions.md` > 假设中断：如果它不在内存中，则它没有发生。 ## 参考文献 * [shadcn/ui 文档]() * [Radix UI 基元]() * [Tailwind CSS v4]() * [下一个主题]()

沙德恩用户界面

包含技能