shadcn/ui 组件库深度使用指南：自定义主题与组件扩展
shadcn/ui Component Library Deep Guide: Custom Themes and Component Extensions
| iDev Team | 2026-07-28T10:00:00
shadcn/ui 不是传统的 NPM 组件库，而是一种全新的"复制粘贴"模式。本文深入讲解如何自定义主题、扩展组件、以及与后端 API 集成的最佳实践。
shadcn/ui is not a traditional NPM component library but a novel copy-paste approach. This article dives deep into custom themes, component extensions, and best practices for backend API integration.
shadcn/ui 的独特之处与 Ant Design、Element UI 不同，shadcn/ui 不是一个 NPM 包。它是一组可复制到项目中的组件源码，你拥有完全的控制权。底层使用 Radix UI（无障碍原语）+ Tailwind CSS（样式）。自定义主题shadcn/ui 的主题系统基于 CSS 变量：/* globals.css */ @layer base { :root { --background: 0 0% 100%; --foreground: 240 10% 3.9%; --primary: 240 5.9% 10%; --primary-foreground: 0 0% 98%; /* ... */ } .dark { --background: 240 10% 3.9%; --foreground: 0 0% 98%; --primary: 0 0% 98%; /* ... */ } }修改这些 CSS 变量即可全局切换主题，无需修改任何组件代码。组件扩展由于组件源码在你的项目中，你可以直接修改。例如，给 Button 组件添加 loading 状态：interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> { loading?: boolean } const Button = React.forwardRef<HTMLButtonElement, ButtonProps>( ({ loading, children, disabled, ...props }, ref) => ( <button ref={ref} disabled={disabled || loading} {...props}> {loading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />} {children} </button> ) )与后端集成使用 React Query + shadcn/ui 的 DataTable 组件实现服务端分页：const { data, isLoading } = useQuery({ queryKey: ['news', page, pageSize], queryFn: () => fetchNews({ page, pageSize }) })推荐组合React Hook Form + Zod + shadcn/ui Form 组件TanStack Table + shadcn/ui DataTableSonner + shadcn/ui Toaster
What Makes shadcn/ui UniqueUnlike Ant Design or Element UI, shadcn/ui is not an NPM package. It's a set of component source code you copy into your project, giving you full control. It uses Radix UI (accessibility primitives) + Tailwind CSS (styling) under the hood.Custom Themesshadcn/ui's theme system is based on CSS variables:/* globals.css */ @layer base { :root { --background: 0 0% 100%; --foreground: 240 10% 3.9%; --primary: 240 5.9% 10%; --primary-foreground: 0 0% 98%; /* ... */ } .dark { --background: 240 10% 3.9%; --foreground: 0 0% 98%; --primary: 0 0% 98%; /* ... */ } }Modify these CSS variables to globally switch themes without changing any component code.Component ExtensionsSince component source code lives in your project, you can modify it directly. For example, adding a loading state to the Button component:interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> { loading?: boolean } const Button = React.forwardRef<HTMLButtonElement, ButtonProps>( ({ loading, children, disabled, ...props }, ref) => ( <button ref={ref} disabled={disabled || loading} {...props}> {loading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />} {children} </button> ) )Backend IntegrationUsing React Query + shadcn/ui DataTable for server-side pagination:const { data, isLoading } = useQuery({ queryKey: ['news', page, pageSize], queryFn: () => fetchNews({ page, pageSize }) })Recommended CombinationsReact Hook Form + Zod + shadcn/ui Form componentTanStack Table + shadcn/ui DataTableSonner + shadcn/ui Toaster