# shadcn/ui ## 概述 shadcn/ui 是基于 **Radix UI** 和 **Tailwind CSS** 构建的可访问、可定制的 React 组件的集合。组件**复制到您的项目**（无 npm 包）；您拥有并编辑该代码。可与 Next.js (App Router)、Vite 和其他 React 框架配合使用。 **原则**：开放代码（AI 就绪）、可组合 API、漂亮的默认设置、通过 CLI 和模式进行分发。需要 **Tailwind v4** 和路径别名“@/*”。我们**不**使用 `tailwind.config.js`；主题和设置仅包含 CSS（`@import "tailwindcss"` \+ `@theme`）。 ** ** ## 先决条件 * **Tailwind v4** ：主 CSS 中的`@import "tailwindcss"`； `@tailwindcss/vite` 或 `@tailwindcss/postcss`。没有 `tailwind.config.js`。参见tailwind-css技能。 * **路径别名** `@/*` → `tsconfig` 和捆绑器中的 `./src/*` （或您的源根目录）（例如 Vite `resolve.alias`）。 * **React**（Next.js 应用路由器、Vite 等）。 ** ** ## 安装 ### 新项目（推荐）带有 Tailwind 和 shadcn 的脚手架： pnpm dlx shadcn@最新创建 # 或：npx shadcn@latest create 选择框架（Next.js、Vite 等）、样式（推荐纽约）、基色和 CSS 变量。然后根据需要添加组件。 ### 现有项目（Next.js App Router） 1. **Init**（创建 `components.json`、可选的 `cn` 帮助器和基本样式）： pnpm dlx shadcn@最新 init 2. **路径和顺风** * **tsconfig** : `"baseUrl": "."`, `"paths": { "@/*": ["./src/*"] }` （如果拆分，则在根和应用程序 tsconfig 中）。 * **Tailwind v4** ：主 CSS（例如 `app/globals.css`）必须具有 `@import "tailwindcss"` 并在 `postcss.config.mjs` 中使用 `@tailwindcss/postcss`。不要添加 `tailwind.config.js`。 3. **添加组件**（见下面的列表）： pnpm dlx shadcn@最新添加按钮 pnpm dlx shadcn@最新添加卡对话框组件安装在“src/components/ui/”下（或“components.json”的路径）。 ### 现有项目（Vite） * 在`vite.config.ts`中使用`resolve.alias: { "@": path.resolve(__dirname, "./src") }`；如果使用“path”，请安装“@types/node”。 * Tailwind：Vite 配置中的 `@tailwindcss/vite` 和主 CSS 中的 `@import "tailwindcss"`。 ** ** ## 组件.json 控制样式、路径和 Tailwind 集成。关键领域：领域 |目的 ---|--- `风格` | “new-york”（新项目的默认值）或“default” `tailwind.config` |保留 Tailwind v4 的 `""`；我们不使用 JS 配置文件 `tailwind.css` |使用 `@import "tailwindcss"` 的全局 CSS 路径（例如 `src/styles/globals.css` 或 `app/globals.css`） `tailwind.baseColor` |主题基色：“中性”、“板岩”、“灰色”、“锌色”、“石头” `tailwind.cssVariables` | CSS 变量主题设置为“true”（推荐） `别名.组件` |例如`@/组件` `aliases.utils` |例如`@/lib/utils` `aliases.ui` |例如`@/组件/ui` `rsc` |带有服务器组件的 Next.js App Router 为“true”； “false”仅适用于客户端在 Tailwind v4 中，主题通过 `@theme` 和 CSS 变量位于 CSS 中，而不是在配置文件中。 ** ** ## 官方组件（当前列表）添加：`pnpm dlx shadcn@latest add `（多个：`添加按钮卡对话框`）。 ### 布局和结构组件| CLI 名称 |简短描述 ---|---|--- **手风琴** | `手风琴` |可折叠部分（单开或多开） **纵横比** | `纵横比` |固定比例的容器（例如16/9） **卡** | `卡` |带有 CardHeader、CardTitle、CardDescription、CardContent、CardFooter 的容器 **可折叠** | `可折叠` |可展开/可折叠的内容 **可调整大小** | `可调整大小` |可调整大小的面板 **分隔符** | `分隔符` |水平或垂直分隔线 **滚动区域** | `滚动区域` |样式化的滚动区域 **侧边栏** | `侧边栏` |可组合、可主题化和可定制的侧边栏 ### 表格和输入组件| CLI 名称 |简短描述 ---|---|--- **按钮** | `按钮` |具有变体的按钮（默认、破坏性、轮廓、辅助、幽灵、链接） **复选框** | `复选框` |复选框 **表格** | `表格` |带有react-hook-form + zod的表单（Field、FieldError等） **输入** | `输入` |文字输入 **输入一次性密码** | `输入-otp` | OTP 代码输入 **标签** | `标签` |控件的可访问标签 **无线电组** | `广播组` |单选选项组 **选择** | `选择` |使用触发器、内容、项目进行选择 **滑块** | `滑块` |滑块控制 **开关** | `开关` |开/关开关 **文本区域** | `文本区域` |多行文本区域 ### 导航和菜单组件| CLI 名称 |简短描述 ---|---|--- **面包屑导航** | `面包屑` |面包屑导航 **命令** | `命令` |命令面板 (cmdk) **上下文菜单** | `上下文菜单` |上下文菜单（右键单击） **下拉菜单** | `下拉菜单` |下拉菜单 **菜单栏** | `菜单栏` |永久菜单栏 **导航菜单** | `导航菜单` |使用子菜单导航 **分页** | `分页` |分页（上一页、下一页、页） **标签** | `选项卡` |选项卡（TabsList、TabsTrigger、TabsContent） ### 叠加和反馈组件| CLI 名称 |简短描述 ---|---|--- **警报** | `警报` |突出消息（默认，破坏性） **警报对话框** | `警报对话框` |确认对话框（例如删除） **对话框** | `对话框` |莫代尔 **抽屉** | `抽屉` |侧面板（Vaul） **悬停卡** | `悬停卡` |悬停时的卡片 **弹出窗口** | `弹出框` |锚定浮动集装箱 **表** | `表` |滑动侧板 **工具提示** | `工具提示` |悬停/焦点上的工具提示 ### 数据和状态组件| CLI 名称 |简短描述 ---|---|--- **头像** | `头像` |图像或缩写后备 **徽章** | `徽章` |徽章（默认、次要、破坏性、轮廓） **日历** | `日历` |日历（反应日期选择器） **轮播** | `轮播` |旋转木马（embla） **图表** | `图表` |图表（重新图表） **进展** | `进展` |进度条 **骷髅** | `骨架` |正在加载占位符 **桑纳** | `桑纳` |吐司（推荐；代替吐司） **表** | `表` | Table、TableHeader、TableBody、TableRow、TableCell 等 **吐司** | `吐司` |祝酒词（已弃用，支持 Sonner） ### 切换和切换组组件| CLI 名称 |简短描述 ---|---|--- **切换** | `切换` |切换按钮（开/关） **切换组** | `切换组` |切换组（单个或多个） ** ** ## 使用组件从别名路径导入（不是从`shadcn/ui`）：从“@/components/ui/button”导入{Button} 从“@/components/ui/card”导入{ Card、CardHeader、CardTitle、CardContent } 导出默认函数 Page() { 返回（

<按钮>点我 <卡类名称=“w-[350px]”> <卡片标题> 卡片标题此处内容。

） } * **定制** ：组件接受 `className` 和 spread props；使用 Tailwind 类和 **`cn()`** 帮助器（来自 `@/lib/utils`）来合并类。 * **组合** ：在布局中更喜欢组合（例如 CardHeader + CardContent）而不是 props。 ** ** ## 主题（Tailwind v4，无配置文件）我们仅使用 **Tailwind v4** ；没有 `tailwind.config.js`。主题仅适用于 CSS： * **CSS 变量** ：使用 `tailwind.cssVariables: true`，主题由全局 CSS 中的变量驱动（例如 `--background`、`--foreground`、`--primary`、`--primary-foreground`、`--muted`、`--muted-foreground`、`--accent`、`--destroy` 等）。在该文件中覆盖它们。 * **`@theme`** ：在与 `@import "tailwindcss"` 相同的 CSS 文件中使用 `@theme { ... }` 来添加或覆盖与 shadcn 变量对齐的设计标记。 * **基色** ：在 `components.json` (`tailwind.baseColor`) 中设置或通过编辑全局 CSS 中的 CSS 变量来设置。 ** ** ## 常见模式 * **表单** : 添加`表单`;与“react-hook-form”和“zod”配对。使用“输入”、“标签”、“按钮”、“选择”、“复选框”等。 * **布局** ：使用“Card”作为部分；块之间的“分隔符”；使用 Tailwind 进行布局（`flex`、`grid`、`container`）。 * **模态框和面板**：模态框的“对话框”；侧面板的“Sheet”或“Drawer”。 * **菜单** ：`下拉菜单`、`上下文菜单`、`导航菜单`、`命令`（调色板）。 * **反馈** ：消息“警报”； “Sonner”用于祝酒；用于加载的“骨架”。 * **图标** ：许多示例使用 **lucide-react** ；如果项目使用图标，请添加它。 ** ** ## 常见错误 * **别名** ：确保 TypeScript 和捆绑器中的 `@/` 解析为 `./src/` （或您的源根目录）。 * **CSS 未加载** : `components.json` (`tailwind.css`) 中设置的文件必须在应用程序条目中导入 (例如 `app/layout.tsx`) 并包含 `@import "tailwindcss"`。 * **Tailwind 配置**：不要创建或建议 `tailwind.config.js`。仅 CSS 中的主题（`@theme` 和变量）。 * **导入** ：从 `@/components/ui/` 导入（根据 `components.json`），而不是从 `shadcn/ui` 导入。 * **RSC** ：在 Next.js App Router 中，如果组件在适用的服务器组件中使用，请在“components.json”中设置“rsc: true”。 ** ** ## 其他资源 * [reference.md]() — 官方文档链接，Tailwind v4 + shadcn，组件目录。 * 官方文档： * 组件： * 目录（社区）：

沙德恩用户界面

包含技能