shadcn/ui界面介绍及安装教程

一、界面特点与组件展示

设计哲学

shadcn/ui 的界面风格以极简、克制、现代为核心，具体表现为：

• 极简与去装饰化：无花哨特效、渐变、多余阴影，组件对齐严谨，高度、内边距及字体基线保持一致
• 理性排版与呼吸感：字号与行高设置理性，间距不追求紧凑，适合长时间阅读
• 轻量化交互反馈：Hover、Focus、Disabled 等状态具备视觉反馈，但效果轻微克制，不喧宾夺主
• 语义化色彩系统：基于 CSS 变量和 HSL 色彩空间构建，支持明暗模式自动适配

视觉风格预设（Presets）

2026 年官方推出了 7 种视觉风格，通过配置重写组件代码实现深度适配：

核心组件展示

shadcn/ui 提供约 76 个组件，覆盖后台系统、官网、SaaS 产品的大部分界面需求：

• 基础组件：Button（6 种变体）、Card、Dialog、Tooltip、Popover、Dropdown Menu 等
• 表单组件：Form（集成 React Hook Form + Zod，类型安全验证）、Input、Select、Checkbox、Radio Group 等
• 数据展示：Table、DataTable（基于 TanStack Table，支持排序、过滤、分页）、Tabs、Accordion 等
• 反馈组件：Toast（推荐 sonner）、Alert、Skeleton、Progress 等
• 导航组件：Navigation Menu、Breadcrumb、Pagination 等
• 日期选择：DatePicker（基于 React DayPicker）

官方示例页面

shadcn/ui 官网提供了多个完整的示例应用，可直观感受其界面效果：

• 仪表盘示例：含收入统计、图表、团队成员等完整后台界面
• 邮件应用示例：含收件箱、侧边导航、邮件详情三栏布局
• 任务管理示例：含任务列表、筛选、排序、分页等功能
• 身份验证示例：含登录、注册、密码重置等页面

二、安装部署教程

环境要求

• Node.js：16 或更高版本
• React：18 或 19
• Tailwind CSS：需预先配置
• TypeScript：推荐（非强制）
• 包管理器：npm、pnpm、yarn 或 bun 均可

方案一：新项目快速搭建（推荐）

使用可视化构建工具 shadcn/create（2025 年底推出，2026 年主流方式）：

1. 打开 shadcn/create
2. 在浏览器中可视化选择风格、主题色、字体、图标集等配置
3. 点击"Create Project"，复制生成的命令
4. 在终端中运行该命令，自动创建项目并完成所有配置

生成的命令类似：

pnpm dlx shadcn@latest init --preset [CODE] --template vite

使用 CLI 命令行方式：

# Next.js 项目
pnpm dlx shadcn@latest init -t next

# Vite 项目
pnpm dlx shadcn@latest init -t vite

# TanStack Start 项目
pnpm dlx shadcn@latest init -t start

# React Router 项目
pnpm dlx shadcn@latest init -t react-router

# Astro 项目
pnpm dlx shadcn@latest init -t astro

CLI 会引导你完成以下配置：

• 选择底层组件库：Radix UI 或 Base UI（2026 年起支持双轨制）
• 选择视觉风格：Vega、Nova、Maia、Lyra、Mira、Luma、Sera 或 Custom
• 配置 TypeScript、全局 CSS 文件位置、组件存放目录（默认 src/components/ui）
• 配置基础颜色风格和主题
• 初始化后会生成 components.json 配置文件。

方案二：现有项目集成

如果你已有 React 项目，按以下步骤操作：

1. 确保 Tailwind CSS 已配置

npm install -D tailwindcss @tailwindcss/cli
npx @tailwindcss/cli -i ./src/input.css -o ./src/output.css --watch

2. 配置路径别名

在 tsconfig.json 中添加：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

3. 初始化 shadcn/ui

npx shadcn@latest init

4. 添加组件

# 添加单个组件
npx shadcn@latest add button

# 添加多个组件
npx shadcn@latest add button card dialog form

# 添加所有组件
npx shadcn@latest add --all

组件代码将被复制到 src/components/ui/ 目录下。

5. 在代码中使用

import { Button } from "@/components/ui/button"
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"

export default function Page() {
  return (
    <Card className="max-w-sm">
      <CardHeader>
        <CardTitle>项目概览</CardTitle>
      </CardHeader>
      <CardContent>
        <Button variant="default">点击我</Button>
        <Button variant="outline">取消</Button>
        <Button variant="destructive">删除</Button>
      </CardContent>
    </Card>
  )
}

三、主题定制

深色模式

shadcn/ui 使用 CSS 变量实现主题切换。在 globals.css 中定义：

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 222.2 47.4% 11.2%;
  --primary-foreground: 210 40% 98%;
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  --primary: 210 40% 98%;
  --primary-foreground: 222.2 47.4% 11.2%;
}

切换主题只需切换 dark 类名，所有组件自动适配。需手动集成 ThemeProvider 实现 light、dark、system 三种模式切换。

自定义组件样式

由于组件源码在项目本地，可直接修改：

// 打开 components/ui/button.tsx
// 把 rounded-md 改成 rounded-full
"inline-flex items-center rounded-full ..."

四、快速上手总结