Back to Details

component-library

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Component Library - shadcn/ui Architecture

组件库 - shadcn/ui 架构

Generate production-ready React components with shadcn/ui patterns, saving 8-10 hours per project.
使用shadcn/ui模式生成可直接用于生产环境的React组件，每个项目可节省8-10小时的开发时间。

Quick Start

快速开始

When generating components:
  1. Create 
    /components/ui/
    directory structure
  2. Generate 
    lib/utils.ts
    with cn() helper first
  3. Create requested components with full TypeScript, variants, and accessibility
  4. Include example usage for each component
生成组件时请遵循以下步骤：
  1. 创建
    /components/ui/
    目录结构
  2. 先生成包含cn()工具函数的
    lib/utils.ts
    文件
  3. 创建带有完整TypeScript类型、变体和可访问性支持的目标组件
  4. 为每个组件提供使用示例

Core Setup Files

核心配置文件

Always generate these first:

请始终先生成以下文件：

lib/utils.ts - Essential cn() helper:
typescript
import { type ClassValue, clsx } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}
components.json - Component registry:
json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "default",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "app/globals.css",
    "baseColor": "slate",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  }
}
lib/utils.ts - 核心cn()工具函数：
typescript
import { type ClassValue, clsx } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}
components.json - 组件注册表：
json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "default",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "app/globals.css",
    "baseColor": "slate",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  }
}

Component Categories

组件分类

Form Components

表单组件

  • Input - Text input with variants (default, ghost, underline)
  • Select - Custom dropdown with search, multi-select options
  • Checkbox - With indeterminate state support
  • Radio - Radio groups with custom styling
  • Switch - Toggle switches with labels
  • Textarea - Auto-resize, character count variants
  • DatePicker - Calendar integration, range selection
  • FileUpload - Drag & drop, preview, progress
  • Slider - Range input with marks, tooltips
  • Form - React Hook Form wrapper with validation
  • Input - 带有多种变体（默认、幽灵型、下划线型）的文本输入框
  • Select - 支持搜索、多选的自定义下拉菜单
  • Checkbox - 支持不确定状态的复选框
  • Radio - 带有自定义样式的单选按钮组
  • Switch - 带标签的切换开关
  • Textarea - 支持自动调整高度、字符计数的文本域
  • DatePicker - 集成日历、支持范围选择的日期选择器
  • FileUpload - 支持拖拽上传、预览、进度显示的文件上传组件
  • Slider - 带有标记、提示框的范围滑块
  • Form - 集成React Hook Form的表单包装器，支持验证

Display Components

展示组件

  • Card - Container with header/footer slots
  • Table - Sortable, filterable, pagination
  • Badge - Status indicators with variants
  • Avatar - Image/initials with fallback
  • Progress - Linear and circular variants
  • Skeleton - Loading states
  • Separator - Visual dividers
  • ScrollArea - Custom scrollbars
  • Card - 带有页眉/页脚插槽的容器组件
  • Table - 支持排序、筛选、分页的表格
  • Badge - 带有多种变体的状态指示器
  • Avatar - 支持图片/首字母、带有回退样式的头像组件
  • Progress - 线性和圆形两种变体的进度条
  • Skeleton - 加载状态骨架屏
  • Separator - 视觉分隔线
  • ScrollArea - 自定义滚动条区域

Feedback Components

反馈组件

  • Alert - Info/warning/error/success states
  • Toast - Notifications with actions
  • Dialog/Modal - Accessible overlays
  • Tooltip - Hover information
  • Popover - Positioned content
  • AlertDialog - Confirmation dialogs
  • Alert - 包含信息/警告/错误/成功状态的提示框
  • Toast - 带有操作按钮的通知组件
  • Dialog/Modal - 符合可访问性标准的弹窗组件
  • Tooltip - 悬停提示信息组件
  • Popover - 定位弹出内容组件
  • AlertDialog - 确认对话框组件

Navigation Components

导航组件

  • Navigation - Responsive nav with mobile menu
  • Tabs - Tab panels with keyboard nav
  • Breadcrumb - Path navigation
  • Pagination - Page controls
  • CommandMenu - Command palette (⌘K)
  • ContextMenu - Right-click menus
  • DropdownMenu - Action menus
  • Navigation - 响应式导航栏，支持移动端菜单
  • Tabs - 支持键盘导航的标签面板
  • Breadcrumb - 路径导航组件
  • Pagination - 分页控制组件
  • CommandMenu - 命令面板（⌘K）
  • ContextMenu - 右键菜单
  • DropdownMenu - 操作菜单

Layout Components

布局组件

  • Accordion - Collapsible sections
  • Collapsible - Show/hide content
  • ResizablePanels - Draggable split panes
  • Sheet - Slide-out panels
  • AspectRatio - Maintain ratios
  • Accordion - 可折叠的面板组件
  • Collapsible - 显示/隐藏内容的折叠组件
  • ResizablePanels - 可拖拽调整的分栏面板
  • Sheet - 滑出式面板
  • AspectRatio - 保持宽高比的容器

Component Implementation Patterns

组件实现模式

Use CVA for all variants:

所有变体均使用CVA实现：

typescript
import { cva, type VariantProps } from "class-variance-authority"

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        ghost: "hover:bg-accent hover:text-accent-foreground",
        link: "text-primary underline-offset-4 hover:underline",
      },
      size: {
        default: "h-10 px-4 py-2",
        sm: "h-9 rounded-md px-3",
        lg: "h-11 rounded-md px-8",
        icon: "h-10 w-10",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)
typescript
import { cva, type VariantProps } from "class-variance-authority"

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        ghost: "hover:bg-accent hover:text-accent-foreground",
        link: "text-primary underline-offset-4 hover:underline",
      },
      size: {
        default: "h-10 px-4 py-2",
        sm: "h-9 rounded-md px-3",
        lg: "h-11 rounded-md px-8",
        icon: "h-10 w-10",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

Accessibility Requirements:

可访问性要求：

  • ARIA labels and roles on all interactive elements
  • Keyboard navigation (Tab, Arrow keys, Enter, Escape)
  • Focus management and trapping for modals
  • Screen reader announcements
  • Semantic HTML elements
  • 所有交互元素均添加ARIA标签和角色
  • 支持键盘导航（Tab、方向键、Enter、Escape）
  • 弹窗组件的焦点管理与陷阱
  • 屏幕阅读器可识别的提示信息
  • 使用语义化HTML元素

Dark Mode Support:

暗黑模式支持：

  • Use Tailwind dark: modifier
  • CSS variables for theme colors
  • Smooth transitions between modes
  • 使用Tailwind的dark:修饰符
  • 采用CSS变量定义主题颜色
  • 模式切换时的平滑过渡

Responsive Design:

响应式设计：

  • Mobile-first approach
  • Container queries where appropriate
  • Touch-friendly tap targets (min 44x44px)
  • Responsive typography scale
  • 移动端优先的设计思路
  • 适当使用容器查询
  • 适合触摸操作的点击目标（最小44x44px）
  • 响应式排版比例

Dependencies

依赖项

Include in package.json:
json
{
  "dependencies": {
    "@radix-ui/react-accordion": "^1.1.2",
    "@radix-ui/react-alert-dialog": "^1.0.5",
    "@radix-ui/react-avatar": "^1.0.4",
    "@radix-ui/react-checkbox": "^1.0.4",
    "@radix-ui/react-dialog": "^1.0.5",
    "@radix-ui/react-dropdown-menu": "^2.0.6",
    "@radix-ui/react-label": "^2.0.2",
    "@radix-ui/react-popover": "^1.0.7",
    "@radix-ui/react-progress": "^1.0.3",
    "@radix-ui/react-radio-group": "^1.1.3",
    "@radix-ui/react-select": "^2.0.0",
    "@radix-ui/react-separator": "^1.0.3",
    "@radix-ui/react-slider": "^1.1.2",
    "@radix-ui/react-switch": "^1.0.3",
    "@radix-ui/react-tabs": "^1.0.4",
    "@radix-ui/react-toast": "^1.1.5",
    "@radix-ui/react-tooltip": "^1.0.7",
    "class-variance-authority": "^0.7.0",
    "clsx": "^2.0.0",
    "cmdk": "^0.2.0",
    "date-fns": "^2.30.0",
    "lucide-react": "^0.263.1",
    "react-day-picker": "^8.8.0",
    "react-hook-form": "^7.45.4",
    "tailwind-merge": "^1.14.0",
    "tailwindcss-animate": "^1.0.7"
  }
}
请在package.json中添加以下依赖：
json
{
  "dependencies": {
    "@radix-ui/react-accordion": "^1.1.2",
    "@radix-ui/react-alert-dialog": "^1.0.5",
    "@radix-ui/react-avatar": "^1.0.4",
    "@radix-ui/react-checkbox": "^1.0.4",
    "@radix-ui/react-dialog": "^1.0.5",
    "@radix-ui/react-dropdown-menu": "^2.0.6",
    "@radix-ui/react-label": "^2.0.2",
    "@radix-ui/react-popover": "^1.0.7",
    "@radix-ui/react-progress": "^1.0.3",
    "@radix-ui/react-radio-group": "^1.1.3",
    "@radix-ui/react-select": "^2.0.0",
    "@radix-ui/react-separator": "^1.0.3",
    "@radix-ui/react-slider": "^1.1.2",
    "@radix-ui/react-switch": "^1.0.3",
    "@radix-ui/react-tabs": "^1.0.4",
    "@radix-ui/react-toast": "^1.1.5",
    "@radix-ui/react-tooltip": "^1.0.7",
    "class-variance-authority": "^0.7.0",
    "clsx": "^2.0.0",
    "cmdk": "^0.2.0",
    "date-fns": "^2.30.0",
    "lucide-react": "^0.263.1",
    "react-day-picker": "^8.8.0",
    "react-hook-form": "^7.45.4",
    "tailwind-merge": "^1.14.0",
    "tailwindcss-animate": "^1.0.7"
  }
}

Implementation Workflow

实现流程

  1. Assess Requirements: Identify which components are needed
  2. Generate Base Files: Create utils.ts and components.json
  3. Create Components: Generate requested components with all features
  4. Provide Examples: Include usage examples for each component
  5. Document Props: Add TypeScript interfaces with JSDoc comments
  1. 需求评估：确定所需组件
  2. 生成基础文件：创建utils.ts和components.json
  3. 创建组件：生成带有全部功能的目标组件
  4. 提供示例：为每个组件添加使用示例
  5. 文档化Props：添加带有JSDoc注释的TypeScript接口

Advanced Patterns

高级模式

For complex requirements, see:
  • references/form-patterns.md - Advanced form handling
  • references/data-tables.md - Complex table implementations
  • references/animation-patterns.md - Framer Motion integration
  • references/testing-setup.md - Component testing patterns
如需实现复杂需求，请参考：
  • references/form-patterns.md - 高级表单处理
  • references/data-tables.md - 复杂表格实现
  • references/animation-patterns.md - Framer Motion集成
  • references/testing-setup.md - 组件测试模式

Performance Optimization

性能优化

  • Use React.memo for expensive components
  • Implement virtual scrolling for long lists
  • Lazy load heavy components
  • Optimize bundle size with tree shaking
  • Use CSS containment for layout stability
  • 对性能开销大的组件使用React.memo
  • 为长列表实现虚拟滚动
  • 懒加载体积较大的组件
  • 通过Tree Shaking优化包体积
  • 使用CSS containment保证布局稳定性

Component Generation Tips

组件生成技巧

When generating components:
  • Include all variant combinations
  • Add proper TypeScript types
  • Implement keyboard shortcuts
  • Include loading and error states
  • Provide Storybook stories structure
  • Add comprehensive prop documentation
  • Include accessibility attributes
  • Test with screen readers
生成组件时：
  • 包含所有变体组合
  • 添加完整的TypeScript类型
  • 实现键盘快捷键
  • 包含加载和错误状态
  • 提供Storybook故事结构
  • 添加全面的Props文档
  • 包含可访问性属性
  • 使用屏幕阅读器测试