shadcn/ui 完整使用指南与AI提示词模板
🎯 什么是 shadcn/ui
shadcn/ui 是一套设计精美、可访问的组件和代码分发平台，不是传统的组件库，而是构建组件库的方式。它基于以下核心原则：
核心特性
- 开放代码: 组件代码完全开放，可自由修改定制
- 组合性: 统一的可组合接口，API一致可预测
- 分发系统: 平面文件模式和CLI工具简化组件分发
- 精美默认值: 精心设计的默认样式，开箱即用
- AI就绪: 开放代码便于LLM理解和改进
🚀 快速开始
1. 选择框架
shadcn/ui 支持所有React框架：
- Next.js
- Vite
- Laravel
- React Router
- Astro
- TanStack Start/Router
2. 基础安装步骤
# 1. 初始化项目
npx create-next-app@latest my-app --typescript --tailwind --eslint
# 2. 进入项目目录
cd my-app
# 3. 运行shadcn-ui初始化
npx shadcn@latest init
# 4. 添加组件
npx shadcn@latest add button
npx shadcn@latest add card
npx shadcn@latest add input3. 配置文件 (components.json)
{
"$schema": "https://ui.shadcn.com/schema.json",
"style": "new-york",
"rsc": false,
"tsx": true,
"tailwind": {
"config": "tailwind.config.js",
"css": "src/styles/globals.css",
"baseColor": "slate",
"cssVariables": true
},
"aliases": {
"components": "@/components",
"utils": "@/lib/utils"
}
}🎨 设计风格指南
设计原则
- 简洁现代: 干净的线条，适度的阴影
- 一致性: 统一的间距、颜色和字体系统
- 可访问性: 符合WCAG标准，支持键盘导航
- 响应式: 移动优先的设计理念
颜色系统
- 主色调: 可自定义的CSS变量系统
- 语义化颜色: primary, secondary, destructive, muted
- 暗黑模式: 内置完整的暗黑主题支持
间距系统
- 基于Tailwind CSS的间距系统
- 8px基础网格系统
- 一致的内外边距规范
🧩 核心组件分类
基础组件
- Button: 各种样式的按钮组件
- Input: 输入框组件
- Label: 标签组件
- Card: 卡片容器组件
表单组件
- Form: 表单容器和验证
- Select: 下拉选择器
- Checkbox: 复选框
- Radio: 单选按钮
- Textarea: 文本域
导航组件
- Navigation Menu: 导航菜单
- Breadcrumb: 面包屑导航
- Tabs: 标签页组件
- Pagination: 分页组件
反馈组件
- Alert: 警告提示
- Toast: 消息提示
- Dialog: 对话框
- Tooltip: 工具提示
数据展示
- Table: 表格组件
- Avatar: 头像组件
- Badge: 徽章组件
- Progress: 进度条
高级组件
- Command: 命令面板
- Calendar: 日历组件
- Date Picker: 日期选择器
- Combobox: 组合框
✨ Magic UI 特效组件
动画效果
- blur-fade: 模糊淡入淡出动画
- text-animate: 文字动画效果
- animated-beam: 动画光束效果
- border-beam: 边框光束动画
背景效果
- grid-pattern: 网格背景图案
- dot-pattern: 点状背景图案
- retro-grid: 复古网格效果
- particles: 粒子效果背景
特殊效果
- meteors: 流星雨效果
- confetti: 彩带庆祝效果
- ripple: 水波纹效果
- shine-border: 发光边框效果
文字特效
- animated-gradient-text: 渐变文字动画
- sparkles-text: 闪烁文字效果
- typing-animation: 打字机动画
- morphing-text: 文字变形效果
📱 最佳实践
1. 组件定制
// 扩展默认组件
import { Button } from "@/components/ui/button"
import { cn } from "@/lib/utils"
interface CustomButtonProps extends ButtonProps {
gradient?: boolean
}
const CustomButton = ({ gradient, className, ...props }: CustomButtonProps) => {
return (
<Button
className={cn(
gradient && "bg-gradient-to-r from-blue-500 to-purple-600",
className
)}
{...props}
/>
)
}2. 主题定制
/* globals.css */
:root {
--background: 0 0% 100%;
--foreground: 222.2 84% 4.9%;
--primary: 221.2 83.2% 53.3%;
--primary-foreground: 210 40% 98%;
}
.dark {
--background: 222.2 84% 4.9%;
--foreground: 210 40% 98%;
--primary: 217.2 91.2% 59.8%;
--primary-foreground: 222.2 84% 4.9%;
}3. 响应式设计
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
<Card className="p-6">
<CardHeader>
<CardTitle>响应式卡片</CardTitle>
</CardHeader>
<CardContent>
内容自适应不同屏幕尺寸
</CardContent>
</Card>
</div>🤖 AI提示词模板
基础组件创建提示词
请使用shadcn/ui创建一个[组件类型]组件，要求：
1. 技术栈：
- 使用TypeScript
- 基于shadcn/ui组件库
- 使用Tailwind CSS样式
- 支持暗黑模式
2. 功能需求：
- [具体功能描述]
- 支持[特定属性]
- 包含[交互行为]
3. 设计要求：
- 遵循shadcn/ui设计规范
- 现代简洁的视觉风格
- 良好的可访问性
- 响应式设计
4. 代码规范：
- 使用forwardRef处理ref传递
- 使用cva处理变体样式
- 包含完整的TypeScript类型定义
- 遵循shadcn/ui的组件结构
请提供完整的组件代码和使用示例。页面布局提示词
请使用shadcn/ui组件创建一个[页面类型]页面，包含：
1. 布局结构：
- 响应式导航栏
- 主内容区域
- 侧边栏（如需要）
- 页脚
2. 组件使用：
- 使用shadcn/ui的[具体组件列表]
- 集成表单验证（使用react-hook-form + zod）
- 添加适当的加载状态和错误处理
3. 视觉设计：
- 遵循shadcn/ui设计系统
- 合理的间距和排版
- 统一的颜色方案
- 支持暗黑模式切换
4. 交互体验：
- 流畅的动画过渡
- 直观的用户反馈
- 键盘导航支持
请提供完整的页面代码和相关的组件文件。特效组件提示词
请使用shadcn/ui和Magic UI创建一个具有[特效类型]的组件：
1. 特效需求：
- 使用Magic UI的[具体特效组件]
- 实现[动画效果描述]
- 支持用户交互触发
2. 技术实现：
- 基于Framer Motion或CSS动画
- 性能优化，避免重复渲染
- 支持动画控制（播放/暂停/重置）
3. 自定义选项：
- 可配置的动画参数
- 多种预设效果
- 响应式适配
4. 集成要求：
- 与shadcn/ui组件无缝集成
- 保持一致的设计语言
- 支持主题切换
请提供组件代码、使用示例和配置选项说明。表单创建提示词
请使用shadcn/ui创建一个[表单类型]表单，包含：
1. 表单字段：
- [字段列表及类型]
- 相应的验证规则
- 错误提示信息
2. 技术栈：
- react-hook-form进行表单管理
- zod进行数据验证
- shadcn/ui表单组件
3. 用户体验：
- 实时验证反馈
- 清晰的错误提示
- 加载状态显示
- 成功提交反馈
4. 样式要求：
- 响应式布局
- 一致的间距和对齐
- 支持暗黑模式
- 无障碍访问支持
请提供完整的表单组件代码和验证schema。主题定制提示词
请为shadcn/ui项目创建一个自定义主题：
1. 设计风格：
- [风格描述，如：现代简约/科技感/温暖色调等]
- 主色调：[具体颜色]
- 辅助色彩：[颜色方案]
2. 定制内容：
- CSS变量定义
- 组件样式覆盖
- 暗黑模式适配
- 字体和间距调整
3. 组件变体：
- 按钮样式变体
- 卡片设计变体
- 输入框样式变体
4. 实现要求：
- 保持shadcn/ui的设计原则
- 确保组件间的一致性
- 良好的可访问性
- 完整的TypeScript支持
请提供主题配置文件和相关的样式代码。🔧 常用命令速查
# 初始化项目
npx shadcn@latest init
# 添加单个组件
npx shadcn@latest add button
npx shadcn@latest add card
npx shadcn@latest add form
# 添加多个组件
npx shadcn@latest add button card input label
# 更新组件
npx shadcn@latest update
# 查看可用组件
npx shadcn@latest list
# 添加特定样式的组件
npx shadcn@latest add --style new-york button📚 学习资源
官方文档
相关技术栈
社区资源
💡 进阶技巧
1. 组件组合模式
// 复合组件模式
const Card = {
Root: CardRoot,
Header: CardHeader,
Title: CardTitle,
Description: CardDescription,
Content: CardContent,
Footer: CardFooter,
}
// 使用
<Card.Root>
<Card.Header>
<Card.Title>标题</Card.Title>
<Card.Description>描述</Card.Description>
</Card.Header>
<Card.Content>内容</Card.Content>
<Card.Footer>底部</Card.Footer>
</Card.Root>2. 自定义Hook集成
// 自定义hook与shadcn/ui组件结合
const useFormWithToast = () => {
const { toast } = useToast()
const form = useForm()
const onSubmit = async (data) => {
try {
await submitData(data)
toast({
title: "成功",
description: "数据已保存",
})
} catch (error) {
toast({
title: "错误",
description: "保存失败",
variant: "destructive",
})
}
}
return { form, onSubmit }
}3. 性能优化
// 使用React.memo优化组件渲染
const OptimizedCard = React.memo(({ title, content }) => (
<Card>
<CardHeader>
<CardTitle>{title}</CardTitle>
</CardHeader>
<CardContent>{content}</CardContent>
</Card>
))
// 使用useMemo优化计算
const MemoizedList = ({ items }) => {
const sortedItems = useMemo(
() => items.sort((a, b) => a.name.localeCompare(b.name)),
[items]
)
return (
<div>
{sortedItems.map(item => (
<Card key={item.id}>...</Card>
))}
</div>
)
}🎉 总结
shadcn/ui 不仅仅是一个组件库，更是一种构建现代Web应用的理念和方法。通过开放的代码、一致的API和精美的设计，它为开发者提供了一个强大而灵活的工具集。
结合AI工具使用时，shadcn/ui的开放性和一致性使得AI能够更好地理解和生成符合规范的代码，大大提高了开发效率。
无论是快速原型开发还是大型项目构建，shadcn/ui都能提供稳定可靠的解决方案。配合本指南中的提示词模板，你可以更高效地利用AI助手来创建高质量的用户界面。