当前位置：首页 > news >正文

react之shadcn（二）

news 2026/5/11 21:04:51

shadcn/ui 的使用流程与传统组件库（如 Ant Design 或 Material UI）完全不同。它不是通过import { Button } from 'shadcn-ui'来使用的，而是将组件的源代码直接复制到你自己的项目中。

以下是 shadcn/ui 的具体使用实现步骤，以React + Next.js + Tailwind CSS为例：

第一步：环境准备

在使用之前，你的项目必须满足以下前提条件：

框架：React (推荐 Next.js) 或 Vue (实验性支持)。
样式库：必须安装并配置好Tailwind CSS。
构建工具：Vite, Next.js, Remix 等。
TypeScript(强烈推荐，虽然支持 JS，但官方主要维护 TS 版本)。

第二步：初始化 (Initialization)

在你的项目根目录下，运行官方 CLI 工具进行初始化。这会创建一个配置文件components.json，并设置好路径别名和基础样式变量。

npx shadcn@latest init

运行过程中你会看到交互式提示：

Style: 选择默认风格（Default）或纽约风格（New York）。
Base Color: 选择主色调（如 Slate, Gray, Zinc 等）。
CSS Variables: 确认是否使用 CSS 变量来管理主题颜色（推荐 Yes）。
Components Path: 确认组件存放路径（默认为@/components）。

执行后发生了什么？

生成了components.json配置文件。
在app/globals.css(Next.js) 或index.css中注入了大量的 CSS 变量（用于定义颜色、半径等主题系统）。
安装了必要的依赖（主要是class-variance-authority,clsx,tailwind-merge,lucide-react等工具库，以及底层的radix-ui组件）。

第三步：添加组件 (Adding Components)

这是核心步骤。你不需要安装组件包，而是“拉取”代码。

命令格式：

npx shadcn@latest add <组件名>

示例：添加一个按钮 (Button) 和一个对话框 (Dialog)

npx shadcn@latest add button dialog

执行后发生了什么？
CLI 会自动下载这些组件的源代码文件，并放置在你配置的目录中（通常是components/ui/）。
你的项目结构会变成这样：

src/ ├── components/ │ └── ui/ │ ├── button.tsx <-- 代码直接在这里，你可以随意修改！ │ ├── dialog.tsx <-- 代码直接在这里 │ └── ... ├── lib/ │ └── utils.ts <-- 提供 cn() 函数，用于合并类名

第四步：在代码中使用 (Usage)

现在，这些组件就是你本地普通的 React 组件了。你可以像导入自己写的组件一样导入它们。

示例代码 (page.tsx或App.tsx)：

import { Button } from "@/components/ui/button"; import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger, } from "@/components/ui/dialog"; import { Input } from "@/components/ui/input"; // 假设你也添加了 input export default function Demo() { return ( <Dialog> <DialogTrigger asChild> <Button variant="outline">打开设置</Button> </DialogTrigger> <DialogContent className="sm:max-w-[425px]"> <DialogHeader> <DialogTitle>编辑个人资料</DialogTitle> <DialogDescription> 在这里修改你的个人信息。点击保存后生效。 </DialogDescription> </DialogHeader> <div className="grid gap-4 py-4"> <div className="grid grid-cols-4 items-center gap-4"> <label htmlFor="name" className="text-right">用户名</label> <Input id="name" defaultValue="Pedro Duarte" className="col-span-3" /> </div> </div> <DialogFooter> <Button type="submit">保存更改</Button> </DialogFooter> </DialogContent> </Dialog> ); }

第五步：定制与修改 (Customization)

这是 shadcn 最强大的地方。因为代码在你手里：

修改样式：直接打开components/ui/button.tsx，修改 Tailwind 类名。例如，想把所有按钮的圆角改大，直接改rounded-md为rounded-xl。
修改逻辑：如果默认的 Dialog 行为不符合需求，直接修改dialog.tsx里的 Radix UI props 或逻辑。
主题切换：修改globals.css中的 CSS 变量（如--primary,--background），即可一键切换深色/浅色模式或品牌色。

进阶技巧

1. 批量更新组件

如果 shadcn 官方修复了某个组件的 Bug 或增加了新功能，你可以运行以下命令来更新本地已有的组件：

npx shadcn@latest add button --overwrite # 或者更新所有已安装的组件 npx shadcn@latest add --all --overwrite

注意：--overwrite会覆盖你本地的修改，如果你深度定制过某个组件，请谨慎使用或手动合并。

2. 创建自定义变体 (Variants)

shadcn 组件通常使用class-variance-authority(cva) 来管理变体。你可以在组件文件中轻松添加新的变体。
例如在button.tsx中添加一个 "ghost-danger" 变体：

const buttonVariants = cva( "...", { variants: { variant: { default: "...", destructive: "...", // 新增自定义变体 "ghost-danger": "hover:bg-red-100 hover:text-red-600", }, // ... }, } )

然后在使用时：<Button variant="ghost-danger">删除</Button>。