# shadcn/ui 技能 shadcn/ui 是一组设计精美、可访问的组件和使用 TypeScript、Tailwind CSS 和 Radix UI 原语构建的代码分发平台。它不是传统的组件库，而是可重用组件的集合，您可以将其复制并粘贴到应用程序中。 ## 参考 ## 何时使用此技能在以下情况下使用此技能： * 使用基于 React 的框架（Next.js、Vite、Remix、Astro 等）构建用户界面 * 向应用程序添加预构建的、可访问的 UI 组件 * 使用 Tailwind CSS 实施设计系统 * 设置带有验证的表单（React Hook Form + Zod） * 添加数据表、图表或复杂的 UI 模式 * 实现具有一致主题的深色模式 * 自定义组件的外观和行为 ## 核心概念 ### 关键原则 * **开放代码** : 将组件复制到您的项目中，自由修改 * **组合** ：使用 Radix UI 中的可组合基元构建 * **分发** ：通过 CLI 分发的组件，而不是 npm 包 * **美丽的默认设置**：精心设计，具有出色的美观性 * **AI-Ready**：结构易于与人工智能工具集成 ### 架构 shadcn/ui 遵循独特的分发模型： 1. **CLI工具**：通过`npx shadcn@latest`安装和管理组件 2. **组件注册表**：组件的中央存储库 3. **本地组件**：组件位于您的`components/ui/`目录中 4. **完全所有权** ：您拥有代码，根据需要进行修改 ### 技术栈 * **TypeScript** ：完全类型安全 * **Tailwind CSS** ：实用优先的样式（v3 和 v4 支持） * **Radix UI** ：可访问的、无样式的基元 * **类别差异权威**：组件变体 * **React 19** ：与最新的 React 兼容 ## 安装和设置 ### 初始设置 **使用 CLI（推荐）：** npx shadcn@最新 init CLI 将提示： * 框架偏好（Next.js、Vite 等） * TypeScript 或 JavaScript * 组件安装位置 * CSS 变量或 Tailwind 配置 * 颜色主题偏好 * 全局 CSS 文件位置 **手动设置：** 1.安装依赖项： npm install tailwindcss-animate class-variance-authority clsx tailwind-merge lucide-react 2. 创建`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” } } 3.配置Tailwind： // tailwind.config.ts 从“tailwindcss”导入类型 { Config } 常量配置：配置= { 黑暗模式：[“类”]，内容：[ './pages/**/*.{ts,tsx}', './components/**/*.{ts,tsx}', './app/**/*.{ts,tsx}', ], 主题：{ 扩展：{}， }, 插件: [require("tailwindcss-animate")], } 导出默认配置 4. 创建实用程序文件： // lib/utils.ts 从“clsx”导入 { clsx，类型 ClassValue } 从“tailwind-merge”导入 { twMerge } 导出函数 cn(...输入: ClassValue[]) { 返回 twMerge(clsx(输入)) } ### 添加组件 **通过 CLI：** # 添加单个组件 npx shadcn@最新添加按钮 # 添加多个组件 npx shadcn@最新添加按钮卡对话框 # 添加所有组件 npx shadcn@最新添加--全部 **添加组件时会发生什么：** 1.组件文件复制到`components/ui/` 2.自动安装依赖 3. 组件已准备好导入和使用 ## 组件类别 ### 表单和输入组件 **按钮：** 从“@/components/ui/button”导入{Button} <按钮变体=“默认”>点击我 <按钮变体=“破坏性”>删除 <按钮变体=“轮廓”大小=“sm”>小 <按钮变体=“幽灵”大小=“图标”> <图标/> **输入：** 从“@/components/ui/input”导入{输入} 从“@/components/ui/label”导入{标签}

<标签 htmlFor="电子邮件">电子邮件 <输入id =“电子邮件”类型=“电子邮件”占位符=“you@example.com”/>

**表格（经过验证）：** 从“react-hook-form”导入 { useForm } 从“@hookform/resolvers/zod”导入{zodResolver} 从“zod”导入*作为z 导入{ 形式，表单控件，表格描述，表单字段，表单项，表单标签，表单消息，来自“@/components/ui/form” 从“@/components/ui/input”导入{输入} 从“@/components/ui/button”导入{Button} const formSchema = z.object({ 用户名：z.string().min(2).max(50), 电子邮件：z.string().email(), }) 函数 ProfileForm() { const form = useForm>({ 解析器：zodResolver(formSchema), 默认值：{ 用户名：“”，电子邮件：“”， }, }) 函数 onSubmit(值: z.infer) { 控制台.log(值) } 返回（ <表格{...表格}>

<表单域控制={form.control} 名称=“用户名” 渲染={({字段})=>( <表单项> 用户名 <表单控件> <输入占位符=“shadcn”{...字段} /> <表单描述> 这是您的公开显示名称。 <表单消息/> )} /> <按钮类型=“提交”>提交） } **选择：** 导入{ 选择，选择内容，选择项目，选择触发器，选择值， } 来自“@/components/ui/select” <选择> <选择内容> 浅色深色系统 **复选框：** 从“@/components/ui/checkbox”导入{复选框} 从“@/components/ui/label”导入{标签}

<复选框 id="条款" /> 接受条款和条件

**日期选择器：** 从“@/components/ui/calendar”导入{日历} 从“@/components/ui/popover”导入 { Popover, PopoverContent, PopoverTrigger } 从“@/components/ui/button”导入{Button} 从“lucide-react”导入{CalendarIcon} 从“date-fns”导入{格式} const [日期，setDate] = useState<日期>() <弹出框> <按钮变体=“大纲”> {日期？格式（日期，“PPP”）：“选择日期”} <日历模式=“单”选择= {日期} onSelect = {setDate} /> ### 布局和导航 **卡：** 导入{ 卡，卡片内容，卡说明，卡页脚，卡头，卡片标题， } 来自“@/components/ui/card” <卡片> <卡片标题> 卡片标题卡说明 <卡片内容>

卡片内容

<卡页脚>

卡片页脚

**标签：** 从“@/components/ui/tabs”导入 { Tabs, TabsContent, TabsList, TabsTrigger } <选项卡defaultValue =“帐户”> <选项卡列表> 帐户密码帐户设置密码设置 **手风琴：** 导入{ 手风琴, 手风琴内容，手风琴项目，手风琴触发器， } 来自“@/components/ui/accordion” <手风琴类型=“单”可折叠> 可以访问吗？ <手风琴内容> 是的。它遵循 WAI-ARIA 设计模式。 **导航菜单：** 导入{ 导航菜单，导航菜单内容，导航菜单项，导航菜单链接，导航菜单列表，导航菜单触发器，来自“@/components/ui/navigation-menu” <导航菜单> <导航菜单列表> <导航菜单项> 项目一 <导航菜单内容> 链接 ### 叠加层和对话框 **对话框：** 导入{ 对话，对话内容，对话框描述，对话框标题，对话框标题，对话触发器，来自“@/components/ui/dialog” <对话框> <按钮>打开对话框 <对话内容> <对话框标题> 您确定吗？ <对话框描述> 此操作无法撤消。 **抽屉：** 导入{ 抽屉，抽屉关闭，抽屉内容，抽屉描述，抽屉页脚，抽屉标题，抽屉标题，抽屉触发器，来自“@/components/ui/drawer” <抽屉> 打开 <抽屉内容> <抽屉标题> 你确定吗？此操作无法撤消。 <抽屉页脚> <按钮>提交取消 **弹出框：** 导入{ 弹出窗口，弹出内容，弹出窗口触发器，来自“@/components/ui/popover” <弹出框> 打开在此处放置内容。 **吐司：** 从“@/hooks/use-toast”导入 { useToast } 从“@/components/ui/button”导入{Button} const { 吐司 } = useToast() <按钮 onClick={() => { 吐司（{ title: "预定：赶上", 描述：“2023 年 2 月 10 日星期五下午 5:57”， }) }} > 显示吐司 **命令：** 导入{ 命令，命令对话框，命令为空，指挥组，命令输入，命令项，命令列表， } 来自“@/components/ui/command” <命令> <命令列表> 未找到结果。日历搜索表情符号计算器 ### 反馈和状态 **警报：** 从“@/components/ui/alert”导入{Alert、AlertDescription、AlertTitle} <警报> 注意！ <警报描述> 您可以使用 CLI 将组件添加到您的应用程序。 <警报变体=“破坏性”> 错误 <警报描述> 您的会话已过期。请重新登录。 **进展：** 从“@/components/ui/progress”导入{进度} <进度值={33}/> **骨架：** 从“@/components/ui/skeleton”导入{骨架}

### 显示组件 **表：** 导入{ 表，桌体，表格标题，表格单元格，桌头，表头，表行， } 来自“@/components/ui/table” <表> 您最近的发票列表。 <表头> <表行> 发票状态金额 <表体> <表行> <表格单元格>INV001 付费 <表格单元格>250.00 美元 **数据表（带排序/过滤）：** npx shadcn@最新添加数据表 **头像：** 从“@/components/ui/avatar”导入 { Avatar, AvatarFallback, AvatarImage } <头像> CN **徽章：** 从“@/components/ui/badge”导入{徽章} <徽章>默认 <徽章变体=“次要”>次要 <徽章变体=“破坏性”>破坏性 <徽章变体=“outline”>大纲 ## 主题化和定制 ### 深色模式设置 **Next.js（应用程序路由器）：** 1.安装下一个主题： npm 安装下一个主题 2.创建主题提供者： // 组件/theme-provider.tsx “使用客户端” 从“react”导入 * as React 从“下一个主题”导入 { ThemeProvider as NextThemesProvider } 导出函数 ThemeProvider({ 孩子们， ...道具 }: React.ComponentProps) { 返回 {children} } 3. 使用提供者包装应用程序： // 应用程序/layout.tsx 从“@/components/theme-provider”导入{ThemeProvider} 导出默认函数 RootLayout({ Children }) { 返回（ <正文> <主题提供者属性=“类” 默认主题=“系统” 启用系统禁用更改时转换 > {孩子} ） } 4.添加主题切换：从“lucide-react”导入{月亮，太阳} 从“下一个主题”导入 { useTheme } 从“@/components/ui/button”导入{Button} 导出函数 ThemeToggle() { const { setTheme, 主题 } = useTheme() 返回（ <按钮变体=“幽灵” 大小=“图标” onClick={() => setTheme(主题 === "light" ? "dark" : "light")} > 切换主题） } ### 颜色定制 **使用 CSS 变量：** /* 全局.css */ @层基础{ ：根{ --背景：0 0% 100%； --前景：222.2 84% 4.9%； ——小学：222.2 47.4% 11.2%； --主前景：210 40% 98%； ——中学：210 40% 96.1%； --次要前景：222.2 47.4% 11.2%； --静音：210 40% 96.1%； --静音前景：215.4 16.3% 46.9%； --口音：210 40% 96.1%； --重音前景：222.2 47.4% 11.2%； --破坏性：0 84.2% 60.2%； --破坏性前景：210 40% 98%； --边界：214.3 31.8% 91.4%； --输入：214.3 31.8% 91.4%； --环：222.2 84% 4.9%； --半径：0.5rem； } .暗{ --背景：222.2 84% 4.9%； --前景：210 40% 98%； --初级：210 40% 98%； --主前景：222.2 47.4% 11.2%； /* ... */ } } **使用 Tailwind 配置：** // tailwind.config.ts 导出默认值{ 主题：{ 扩展：{ 颜色：{ 边框：“hsl(var(--border))”，输入：“hsl（var（--输入））”，环：“hsl(var(--ring))”，背景：“hsl(var(--background))”，前景：“hsl(var(--foreground))”，主要：{ 默认值：“hsl(var(--primary))”，前景：“hsl(var(--primary-foreground))”， }, // ... }, }, }, } ### 组件定制由于组件存在于您的代码库中，因此您可以直接修改它们： // 组件/ui/button.tsx // 修改变体、添加新变体、更改样式 const 按钮变体 = cva( “inline-flex items-center justify-center rounded-md text-sm font-medium”， { 变体：{ 变体：{ 默认值：“bg-primary text-primary-foreground”，破坏性的：“bg-破坏性文本-破坏性-前景”，大纲：“边框边框-输入bg-背景”， // 添加自定义变体自定义：“bg-gradient-to-r from-purple-500 to-pink-500 text-white”， }, 尺寸：{ 默认值：“h-10 px-4 py-2”， sm: "h-9 圆角-md px-3", lg: "h-11 圆角-md px-8", // 添加自定义尺寸 xl: "h-14 rounded-md px-10 text-lg", }, }, 默认变体：{ 变体：“默认”，大小：“默认”， }, } ） ## 高级模式 ### 服务器操作 (Next.js) // 应用程序/actions.ts “使用服务器” 从“zod”导入{z} const 架构 = z.object({ 电子邮件：z.string().email(), 密码：z.string().min(8), }) 导出异步函数createUser(formData: FormData) { const validFields = schema.safeParse({ 电子邮件：formData.get(“电子邮件”), 密码：formData.get("密码"), }) if (!validatedFields.success) { 返回{ 错误：validatedFields.error.flatten().fieldErrors， } } // 创建用户 } // 应用程序/注册/page.tsx 从“@/app/actions”导入{createUser} 从“@/components/ui/button”导入{Button} 从“@/components/ui/input”导入{输入} 导出默认函数 SignupPage() { 返回（ <表单操作={createUser}> <输入名称=“电子邮件”类型=“电子邮件”/> <输入名称=“密码”类型=“密码”/> ） } ### 可重用表单模式 // lib/form-utils.ts 从“react-hook-form”导入 { UseFormReturn } 从“@/components/ui/form”导入{ FormField、FormItem、FormLabel、FormControl、FormMessage } 从“@/components/ui/input”导入{输入} 导出函数 TextFormField({ 形式，名字，标签，占位符，类型=“文本”， }：{ 形式：UseFormReturn<任意> 名称：字符串标签：字符串占位符？：字符串类型？：字符串 }) { 返回（ <表单域控制={form.control} 名称={名称} 渲染={({字段})=>( <表单项> {标签} <表单控件> <输入类型={类型}占位符={占位符} {...字段} /> <表单消息/> )} /> ） } ### 响应式组件组成从“@/hooks/use-media-query”导入 { useMediaQuery } 从“@/components/ui/dialog”导入 { Dialog, DialogContent } 从“@/components/ui/drawer”导入{Drawer，DrawerContent} 导出函数 ResponsiveDialog({ Children, ...props }) { const isDesktop = useMediaQuery("(最小宽度：768px)") 如果（是桌面）{ 返回（ <对话框{...道具}> {children} ） } 返回（ <抽屉{...道具}> {children} ） } ## 最佳实践 1. **使用 TypeScript** ：利用完整的类型安全性实现更好的 DX 2. **自定义组件** ：直接在代码库中修改组件 3. **Compose Primitives** ：通过组合简单的组件来构建复杂的 UI 4. **遵循可访问性**：组件基于可访问的 Radix UI 原语构建 5. **使用表单验证**：集成 React Hook Form + Zod 以实现健壮的表单 6. **深色模式**：实现主题切换以获得更好的用户体验 7. **响应式设计**：使用 Tailwind 响应式实用程序 8. **性能** ：对大型组件集使用代码分割和延迟加载 9. **一致的间距**：一致地使用 Tailwind 间距比例 10. **图标库** ：使用 lucide-react 获得一致的图标 ## 特定于框架的设置 ### Next.js * 支持应用程序路由器和页面路由器 * 服务器组件兼容性 * 服务器操作集成 ### 维特 * 使用 HMR 快速开发 * 使用 TypeScript 轻松设置 ### 混音 * 基于路由的架构 * 渐进增强 ### 太空人 * 静态站点生成 * 岛屿建筑 ### Laravel (Inertia.js) * 与 Laravel 的后端集成 * 用惯性反应前端 ## 常见模式 ### 加载状态从“@/components/ui/skeleton”导入{骨架} 导出函数 UserCardSkeleton() { 返回（

） } 导出函数 UserCard({ user }: { user?: User }) { if (!user) 返回返回（

<头像> {user.initials}

{用户名}

{user.email}

） } ### 错误处理从“@/components/ui/alert”导入{Alert、AlertDescription、AlertTitle} 从“lucide-react”导入{AlertCircle} 导出函数 ErrorAlert({ 错误 }: { 错误: 错误 }) { 返回（ <警报变体=“破坏性”> 错误 {error.message} ） } ### 确认对话框导入{ 警报对话框，警报对话框操作，警报对话框取消，警报对话框内容，警报对话框描述，警报对话框页脚，警报对话框标题，警报对话框标题，警报对话框触发器，来自“@/components/ui/alert-dialog” 导出函数DeleteConfirmation({ onConfirm }: { onConfirm: () => void }) { 返回（ <警报对话框> <按钮变体=“破坏性”>删除 <警报对话框内容> <警报对话框标题> 您绝对确定吗？ <警报对话框描述> 此操作无法撤消。这将永久删除您的帐户并从我们的服务器中删除您的数据。 <警报对话框页脚> 取消继续） } ## 故障排除 ### 常见问题 1. **“找不到模块”错误** * 检查`tsconfig.json`中的路径别名 * 验证“components.json”别名与您的项目结构匹配 * 确保组件安装在正确的目录中 2. **未应用样式** * 验证 Tailwind CSS 配置是否正确 * 检查 `globals.css` 导入 CSS 变量 * 确保已安装 `tailwindcss-animate` 插件 3. **深色模式不起作用** * 检查 ThemeProvider 是否包装了您的应用程序 * 验证“”标签上的“suppressHydrationWarning” * 确保在 CSS 中定义暗模式类 4. **表单验证问题** * 安装所需的软件包：`react-hook-form`、`@hookform/resolvers`、`zod` * 检查模式是否与表单字段匹配 * 验证解析器配置是否正确 5. **TypeScript 错误** * 更新 `@types/react` 和 `@types/react-dom` * 检查组件属性类型 * 确保 TypeScript 版本兼容 (>= 4.5) ## 资源 * 文档： * GitHub： * 组件注册表： * 示例： * Figma 设计套件： * v0（人工智能用户界面生成器）： ## 实施清单实现 shadcn/ui 时： * 运行`npx shadcn@latest init`来设置项目 * 配置 Tailwind CSS 和路径别名 * 使用 ThemeProvider 设置深色模式 * 通过 CLI 安装所需的组件 * 创建实用函数（cn helper） * 设置表单处理（React Hook Form + Zod） * 配置图标（lucide-react） * 实现主题切换组件 * 在明暗模式下测试组件 * 如果需要自定义调色板 * 添加骨架加载状态 * 实现错误处理模式 * 测试辅助功能 * 优化包大小（tree-shaking） * 添加响应式设计实用程序

沙德恩用户界面

包含技能