Shadcn Vue 教程：从零开始构建现代化界面
在现代 Web 开发中，构建美观、响应迅速且易于维护的用户界面至关重要。Shadcn/UI 最初以 React 版本发布，因其独特的组件哲学——提供可定制的、可复制粘贴的代码而非预编译的组件库——而广受欢迎。现在，这一理念也延伸到了 Vue 生态系统，诞生了 Shadcn Vue。
本教程将引导您从零开始，使用 Shadcn Vue 构建一个现代化界面。
什么是 Shadcn Vue？
Shadcn Vue 并非传统的组件库。它提供了一套基于 Tailwind CSS 和 Radix Vue 构建的、经过精心设计和无障碍优化的 Vue 组件。它的核心思想是：
- 带来代码，而非库： 您将通过 CLI 命令将组件的源代码直接添加到您的项目中。这意味着您可以完全控制每个组件，轻松地根据项目需求进行修改和扩展，而无需处理复杂的组件覆盖或主题配置。
- 可定制性： 由于拥有组件的完整代码，您可以随意调整样式、逻辑甚至底层标记。
- 无障碍性 (Accessibility)： 基于 Radix Vue 的组件提供了出色的无障碍支持，这对于构建包容性应用至关重要。
- 美观与现代： 组件设计遵循现代 UI/UX 原则，开箱即用，即可拥有专业外观。
为什么选择 Shadcn Vue？
- 告别依赖地狱： 不再需要担心组件库版本更新带来的破坏性变更，因为您拥有代码。
- 极致的灵活性： 轻松调整任何组件以匹配您的品牌或特定功能需求。
- 更小的包体积： 只打包您实际使用的组件代码。
- 学习 Tailwind CSS 和 Vue 的实践机会： 通过研究和修改 Shadcn Vue 组件，您可以深入了解这些技术。
先决条件
在开始之前，请确保您的开发环境满足以下条件：
- Node.js (LTS 版本): 用于运行 JavaScript 和包管理器。
- 包管理器:
npm、yarn或pnpm均可。推荐pnpm以获得更快的安装速度。 - Vue 项目: 您将需要一个 Vue 3 项目。本教程将使用 Vite 创建项目。
步骤 1：创建新的 Vue 项目 (使用 Vite)
如果您已经有一个 Vue 3 项目，可以跳过此步骤。否则，我们将使用 Vite 快速搭建一个新项目：
bash
pnpm create vue@latest my-shadcn-vue-app
根据提示选择您的偏好：
“`
✔ Project name: my-shadcn-vue-app
✔ Add TypeScript? … Yes
✔ Add JSX Support? … No
✔ Add Vue Router for Single Page Application development? … Yes
✔ Add Pinia for state management? … No
✔ Add Vitest for Unit Testing? … No
✔ Add an End-to-End Testing Solution? … No
✔ Add ESLint for code quality? … Yes
pnpm install
pnpm dev
“`
进入项目目录并安装依赖：
bash
cd my-shadcn-vue-app
pnpm install
步骤 2：安装 Tailwind CSS
Shadcn Vue 依赖于 Tailwind CSS。我们需要先将其集成到项目中。
bash
pnpm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
这将创建 tailwind.config.js 和 postcss.config.js 文件。
接下来，修改 tailwind.config.js 以包含您的 Vue 文件路径：
javascript
// tailwind.config.js
/** @type {import('tailwindcss').Config} */
export default {
content: [
"./index.html",
"./src/**/*.{vue,js,ts,jsx,tsx}", // 确保这里包含了您的 Vue 文件
],
theme: {
extend: {},
},
plugins: [],
}
然后，在您的 src/assets/main.css (或您项目的主 CSS 文件) 中添加 Tailwind 的指令：
“`css
/ src/assets/main.css /
@tailwind base;
@tailwind components;
@tailwind utilities;
/ 其他您的全局样式 /
“`
注意： 如果您使用的是 Vite，通常会在 src/main.ts 或 src/main.js 中导入这个 CSS 文件。
“`typescript
// src/main.ts (或 main.js)
import ‘./assets/main.css’ // 确保导入了 Tailwind CSS
import { createApp } from ‘vue’
import App from ‘./App.vue’
import router from ‘./router’
const app = createApp(App)
app.use(router)
app.mount(‘#app’)
“`
运行 pnpm dev 检查 Tailwind CSS 是否正确配置（例如，尝试给一个元素添加 text-red-500 类）。
步骤 3：初始化 Shadcn Vue
现在，我们来安装 Shadcn Vue CLI 工具并进行初始化。
bash
pnpm dlx shadcn-vue@latest init
这个命令会引导您进行一系列配置。以下是一些常见选项及推荐选择：
Are you using TypeScript? (y/N) // 推荐 'y'
Which style would you like to use? › Default // 可以根据喜好选择，Default 是一个好的开始
Which color would you like to use as base color? › Slate // 可以根据喜好选择，Slate 常见且百搭
Where is your global CSS file? › src/assets/main.css // 确保路径正确
Configure the import alias for components: › @/components
Configure the import alias for utils: › @/lib/utils
Are you using Nuxt? (y/N) // 如果是 Nuxt 项目则选 'y'，否则选 'N'
Write configuration to components.json. Proceed? (y/N) // 推荐 'y'
初始化过程会修改您的 tailwind.config.js 文件，添加 Shadcn Vue 所需的颜色变量和插件。它还会创建 components.json 文件来存储配置。
步骤 4：添加您的第一个组件
初始化完成后，您可以使用 add 命令来添加组件。让我们从一个简单的 Button 开始：
bash
pnpm dlx shadcn-vue@latest add button
执行此命令后，Shadcn Vue CLI 会将 button 组件的源代码文件（通常是 src/components/ui/button/Button.vue 和相关文件）复制到您的项目中。
现在，您可以在任何 Vue 组件中使用它了。例如，修改 src/App.vue：
“`vue
“`
运行 pnpm dev，您应该能看到页面上出现了 Shadcn Vue 风格的按钮。
步骤 5：定制组件
由于您拥有组件的源代码，定制变得异常简单。
例如，如果您想改变 Button 组件的默认主题色或尺寸，可以直接修改 src/components/ui/button/Button.vue 或其样式文件。但更推荐的方式是修改 tailwind.config.js 中的颜色变量，或者在添加组件时选择不同的样式。
Shadcn Vue 的组件通常通过 variant prop 提供不同的视觉样式，并通过 Tailwind CSS 类来进一步定制。
例如，Button 组件可能有 default、outline、secondary、ghost、link、destructive 等 variant。
您还可以通过修改 tailwind.config.js 文件中的 theme.extend.colors 部分，来调整 Shadcn Vue 组件使用的颜色。这些颜色通常以 CSS 变量的形式存在，例如 --primary、--secondary 等。
javascript
// tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
// ...
theme: {
container: {
center: true,
padding: '2rem',
screens: {
'2xl': '1400px'
}
},
extend: {
colors: {
border: 'hsl(var(--border))',
input: 'hsl(var(--input))',
ring: 'hsl(var(--ring))',
background: 'hsl(var(--background))',
foreground: 'hsl(var(--foreground))',
primary: {
DEFAULT: 'hsl(var(--primary))',
foreground: 'hsl(var(--primary-foreground))'
},
secondary: {
DEFAULT: 'hsl(var(--secondary))',
foreground: 'hsl(var(--secondary-foreground))'
},
destructive: {
DEFAULT: 'hsl(var(--destructive))',
foreground: 'hsl(var(--destructive-foreground))'
},
muted: {
DEFAULT: 'hsl(var(--muted))',
foreground: 'hsl(var(--muted-foreground))'
},
accent: {
DEFAULT: 'hsl(var(--accent))',
foreground: 'hsl(var(--accent-foreground))'
},
popover: {
DEFAULT: 'hsl(var(--popover))',
foreground: 'hsl(var(--popover-foreground))'
},
card: {
DEFAULT: 'hsl(var(--card))',
foreground: 'hsl(var(--card-foreground))'
}
},
borderRadius: {
xl: 'calc(var(--radius) + 4px)',
lg: 'var(--radius)',
md: 'calc(var(--radius) - 2px)',
sm: 'calc(var(--radius) - 4px)'
},
keyframes: {
'accordion-down': {
from: { height: 0 },
to: { height: 'var(--radix-accordion-content-height)' }
},
'accordion-up': {
from: { height: 'var(--radix-accordion-content-height)' },
to: { height: 0 }
},
'collapsible-down': {
from: { height: 0 },
to: { height: 'var(--radix-collapsible-content-height)' }
},
'collapsible-up': {
from: { height: 'var(--radix-collapsible-content-height)' },
to: { height: 0 }
}
},
animation: {
'accordion-down': 'accordion-down 0.2s ease-out',
'accordion-up': 'accordion-up 0.2s ease-out',
'collapsible-down': 'collapsible-down 0.2s ease-out',
'collapsible-up': 'collapsible-up 0.2s ease-out'
}
}
},
// ...
}
这些 CSS 变量通常定义在 src/assets/main.css 中 (在 Shadcn Vue 初始化时添加)。
“`css
/ src/assets/main.css /
@tailwind base;
@tailwind components;
@tailwind utilities;
@layer base {
:root {
–background: 0 0% 100%;
–foreground: 222.2 84% 4.9%;
--card: 0 0% 100%;
--card-foreground: 222.2 84% 4.9%;
--popover: 0 0% 100%;
--popover-foreground: 222.2 84% 4.9%;
--primary: 222.2 47.4% 11.2%;
--primary-foreground: 210 40% 98%;
--secondary: 210 40% 96.1%;
--secondary-foreground: 222.2 47.4% 11.2%;
--muted: 210 40% 96.1%;
--muted-foreground: 215.4 16.3% 46.9%;
--accent: 210 40% 96.1%;
--accent-foreground: 222.2 47.4% 11.2%;
--destructive: 0 84.2% 60.2%;
--destructive-foreground: 210 40% 98%;
--border: 214.3 31.8% 91.4%;
--input: 214.3 31.8% 91.4%;
--ring: 222.2 84% 4.9%;
--radius: 0.5rem; /* 圆角大小 */
}
.dark {
–background: 222.2 84% 4.9%;
–foreground: 210 40% 98%;
--card: 222.2 84% 4.9%;
--card-foreground: 210 40% 98%;
--popover: 222.2 84% 4.9%;
--popover-foreground: 210 40% 98%;
--primary: 210 40% 98%;
--primary-foreground: 222.2 47.4% 11.2%;
--secondary: 217.2 32.6% 17.5%;
--secondary-foreground: 210 40% 98%;
--muted: 217.2 32.6% 17.5%;
--muted-foreground: 215 20.2% 65.1%;
--accent: 217.2 32.6% 17.5%;
--accent-foreground: 210 40% 98%;
--destructive: 0 62.8% 30.6%;
--destructive-foreground: 210 40% 98%;
--border: 217.2 32.6% 17.5%;
--input: 217.2 32.6% 17.5%;
--ring: 212.7 26.8% 83.9%;
}
}
/ … /
“`
通过修改这些 HSL 值，您可以轻松调整整个应用的主题。
步骤 6：探索更多组件
Shadcn Vue 提供了丰富的组件，涵盖了表单、导航、数据显示等多个方面。您可以在其官方文档中查看完整的组件列表。
例如，您可以尝试添加 input、card、dialog 等组件：
bash
pnpm dlx shadcn-vue@latest add input
pnpm dlx shadcn-vue@latest add card
pnpm dlx shadcn-vue@latest add dialog
然后，像使用 Button 一样，在您的 Vue 组件中导入并使用它们。
“`vue
“`
结论
通过 Shadcn Vue，您获得了构建现代化、可定制且无障碍的用户界面的强大工具。其 “带来代码，而非库” 的哲学赋予了开发者前所未有的灵活性和控制力。结合 Tailwind CSS 的实用性以及 Radix Vue 提供的无障碍基础，Shadcn Vue 无疑是 Vue 生态系统中一个令人兴奋的 UI 解决方案。
现在，您可以继续探索 Shadcn Vue 的其他组件，并通过定制它们来构建您心仪的应用程序界面！