⚡

shadcn-vueVue组件库 shadcn-vue

shadcn-vue 是一个用于Vue.js和Nuxt.js框架的UI组件库，基于Reka UI和Tailwind CSS，提供可访问、可自定义的组件，如自动表单、数据表格、图表等，并支持黑暗模式和TypeScript。关键词：Vue, Nuxt, UI组件, Tailwind CSS, 可访问性, 自动表单, 数据表格, 黑暗模式, TypeScript

前端开发 0 次安装 0 次浏览 更新于 3/7/2026

名称: shadcn-vue 描述: shadcn-vue 用于 Vue/Nuxt，带有 Reka UI 组件和 Tailwind。用于可访问的用户界面、自动表单、数据表格、图表，或遇到组件导入、黑暗模式、Reka UI 错误。 关键词: shadcn-vue, shadcn vue, Reka UI, radix-vue, Vue 组件, Nuxt 组件, Tailwind CSS, 可访问组件, headless ui, 自动表单, Zod 验证, TanStack 表格, 数据表格, Unovis 图表, 黑暗模式, useColorMode, components.json, bunx shadcn-vue, vueuse, 可组合函数, Vue 3, Nuxt 3, TypeScript, 可访问性, ARIA, 组件库, UI 组件, 表单构建器, 模式验证 许可证: MIT

shadcn-vue 生产堆栈

生产测试: Vue/Nuxt 应用程序，带有可访问、可自定义的组件 最后更新: 2025-12-09 状态: 生产就绪 ✅ 最新版本: shadcn-vue@latest (Reka UI v2) 依赖项: Tailwind CSS, Reka UI, Vue 3+ 或 Nuxt 3+

快速开始 (3 分钟)

对于 Vue 项目 (Vite)

1. 初始化 shadcn-vue

# 使用 Bun (推荐)
bunx shadcn-vue@latest init

# 使用 npm
npx shadcn-vue@latest init

初始化期间:

  • 样式: New York 或 Default (之后无法更改！)
  • 基础颜色: Slate (推荐)
  • CSS 变量: Yes (黑暗模式必需)

2. 配置 TypeScript 路径别名

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

3. 配置 Vite

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import tailwindcss from '@tailwindcss/vite' // Tailwind v4
import path from 'path'

export default defineConfig({
  plugins: [vue(), tailwindcss()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    }
  }
})

4. 添加您的第一个组件

bunx shadcn-vue@latest add button
# 或: npx shadcn-vue@latest add button

查看完整设置: templates/quick-setup.ts

对于 Nuxt 项目

# 创建带 Tailwind 的项目
bun create nuxt-app my-app
cd my-app
bun add -D @nuxtjs/tailwindcss

# 配置 Nuxt
# nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxtjs/tailwindcss']
})

# 初始化 shadcn-vue
bunx shadcn-vue@latest init
# 或: npx shadcn-vue@latest init
# 或: pnpm dlx shadcn-vue@latest init

组件库 (50+ 组件)

导航与布局

  • 手风琴, 警报对话框, 头像, 徽章, 面包屑, 卡片, 轮播, 可折叠, 对话框, 抽屉, 下拉菜单, 菜单栏, 导航菜单, 分页, 弹出框, 可调整大小, 滚动区域, 侧边栏, 选项卡, 吐司通知, 工具提示

表单组件

  • 自动表单, 按钮, 日历, 复选框, 组合框, 命令, 上下文菜单, 日期选择器, 表单, 输入框, OTP 输入, 标签, 数字字段, PIN 输入, 单选组, 范围日历, 选择框, 滑块, Sonner, 开关, 文本区域, 切换, 切换组

数据展示

  • 宽高比, 数据表格, 骨架屏, 步骤条, 分割器, 表格, 标签输入

高级

  • 图表 (Unovis), 颜色选择器, 可编辑, 文件上传, 可排序

完整组件参考: https://shadcn-vue.com/docs/components

自动表单 - 基于模式的表单

安装

bunx shadcn-vue@latest add auto-form
# 或: npx shadcn-vue@latest add auto-form

bun add zod
# 或: npm install zod

基本用法

<script setup lang="ts">
import { AutoForm } from '@/components/ui/auto-form'
import { z } from 'zod'

const schema = z.object({
  name: z.string().min(2, '姓名必须至少2个字符'),
  email: z.string().email('无效邮箱'),
  age: z.number().min(18, '必须18岁或以上'),
  bio: z.string().optional(),
  subscribe: z.boolean().default(false)
})

function onSubmit(values: z.infer<typeof schema>) {
  console.log('表单提交:', values)
}
</script>

<template>
  <AutoForm :schema="schema" @submit="onSubmit">
    <template #submit>
      <Button type="submit">提交</Button>
    </template>
  </AutoForm>
</template>

支持的字段类型: 字符串, 数字, 布尔值, 日期, 枚举, 数组, 对象

使用 TanStack 表格的数据表格

安装

bunx shadcn-vue@latest add data-table
# 或: npx shadcn-vue@latest add data-table

bun add @tanstack/vue-table
# 或: npm install @tanstack/vue-table

基本设置

<script setup lang="ts">
import { DataTable } from '@/components/ui/data-table'
import { h } from 'vue'

const columns = [
  {
    accessorKey: 'id',
    header: 'ID',
  },
  {
    accessorKey: 'name',
    header: '姓名',
  },
  {
    accessorKey: 'email',
    header: '邮箱',
  }
]

const data = [
  { id: 1, name: 'John Doe', email: 'john@example.com' },
  { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
]
</script>

<template>
  <DataTable :columns="columns" :data="data" />
</template>

功能: 排序, 筛选, 分页, 行选择, 列可见性, 可扩展行

黑暗模式实现

安装

bun add @vueuse/core
# 或: npm install @vueuse/core

设置主题提供者

<!-- components/ThemeProvider.vue -->
<script setup lang="ts">
import { useColorMode } from '@vueuse/core'

const mode = useColorMode()
</script>

<template>
  <div :class="mode">
    <slot />
  </div>
</template>

在组件中使用

<script setup>
import { useColorMode } from '@vueuse/core'

const mode = useColorMode()

function toggleTheme() {
  mode.value = mode.value === 'dark' ? 'light' : 'dark'
}
</script>

<template>
  <Button @click="toggleTheme">
    {{ mode === 'dark' ? '🌙' : '☀️' }}
  </Button>
</template>

关键规则

总是做

✅ 在添加组件前运行 init

  • 创建必需的配置和工具
  • 设置路径别名

✅ 使用 CSS 变量进行主题化 (cssVariables: true)

  • 启用黑暗模式支持
  • 灵活的主题自定义

✅ 配置 TypeScript 路径别名

  • 组件导入必需
  • 必须匹配 components.json 别名

✅ 将 components.json 保持在版本控制中

  • 团队成员需要相同配置
  • 记录项目设置

✅ 使用 Bun 进行更快安装 (推荐)

  • 比 npm 快 10-20 倍

永远不做

❌ 不要初始化后更改 style

  • 需要完全重新安装
  • 在新目录中重新初始化

❌ 不要混合 Radix Vue 和 Reka UI v2

  • 不兼容的组件 API
  • 使用其中之一

❌ 不要跳过 TypeScript 配置

  • 组件导入将失败
  • IDE 自动完成无法工作

❌ 不要在没有 Tailwind CSS 的情况下使用

  • 组件使用 Tailwind 样式化
  • 无法正确渲染

前 7 大关键问题

问题 #1: 缺少 TypeScript 路径别名

错误: 找不到模块 '@/components/ui/button'

解决方案:

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

问题 #2: Tailwind CSS 未配置

错误: 组件渲染无样式

解决方案:

/* src/assets/index.css */
@import "tailwindcss";

// vite.config.ts (Tailwind v4)
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [vue(), tailwindcss()]
})

问题 #3: CSS 变量未定义

错误: 主题颜色未应用, 灰色/透明组件

解决方案: 确保所有 CSS 变量已定义 (运行 init 命令)

问题 #4: 选择错误样式

错误: 组件外观与预期不同

解决方案: 在 init 期间仔细选择 (New York 或 Default) - 之后无法更改, 不重新安装

问题 #5: 混合 Radix Vue 和 Reka UI

错误: 类型冲突, 重复组件

解决方案:

  • 使用 bunx shadcn-vue@latest 用于 Reka UI v2
  • 使用 bunx shadcn-vue@radix 用于旧版 Radix Vue
  • 不要混合两者

问题 #6: 单体仓库路径问题

错误: 组件安装在错误目录

解决方案: 使用 -c 标志指定工作区:

bunx shadcn-vue@latest init -c ./apps/web
bunx shadcn-vue@latest add button -c ./apps/web

问题 #7: 手动编辑后组件导入失败

错误: 编辑 components.json 后导入路径损坏

解决方案: 保持 components.json 和 tsconfig.json 别名同步。任何配置更改后测试导入。

查看所有 7 个问题: references/error-catalog.md

CLI 命令参考

init 命令

# 在当前目录初始化
bunx shadcn-vue@latest init
# 或: npx shadcn-vue@latest init

# 在特定目录初始化 (单体仓库)
bunx shadcn-vue@latest init -c ./apps/web
# 或: npx shadcn-vue@latest init -c ./apps/web

add 命令

# 添加单个组件
bunx shadcn-vue@latest add button
# 或: npx shadcn-vue@latest add button

# 添加多个组件
bunx shadcn-vue@latest add button card dialog

# 添加所有组件
bunx shadcn-vue@latest add --all
# 或: npx shadcn-vue@latest add --all

diff 命令

# 检查组件更新
bunx shadcn-vue@latest diff button
# 或: npx shadcn-vue@latest diff button

Reka UI v2 迁移

shadcn-vue 现在使用 Reka UI v2 (前身 Radix Vue) 作为其基础。所有新组件使用 Reka UI 基元。

迁移: 现有项目应更新到 Reka UI v2。查看官方迁移指南: shadcn-vue.com/docs/changelog#reka-ui

配置

shadcn-vue 使用 components.json 配置:

  • 组件路径 (@/components/ui)
  • 工具位置 (@/lib/utils)
  • Tailwind 配置路径
  • TypeScript 路径

完整示例: 查看 templates/components.json 或通过 bunx shadcn-vue@latest init 生成

工具库

@/lib/utils.ts 文件提供 cn() 辅助函数用于合并 Tailwind 类:

  • 组合多个 className 字符串
  • 使用 clsx + tailwind-merge 解决冲突

自动生成 由 shadcn-vue init - 无需手动设置。

捆绑资源

模板 (templates/):

  • quick-setup.ts - Vue/Nuxt 完整设置指南, 带示例 (190 行)

参考 (references/):

  • error-catalog.md - 所有 7 个记录的问题及解决方案 (267 行)

何时加载参考

根据任务加载这些参考:

  1. 加载 references/error-catalog.md 当:

    • 用户遇到“找不到组件”或导入错误
    • 设置命令失败或配置问题出现
    • Tailwind CSS 变量或 TypeScript 路径损坏
    • 触发短语: “不工作”, “错误”, “失败”, “损坏”

  2. 加载 references/component-examples.md 当:

    • 用户问“如何实现 [组件]?”
    • 需要特定组件的复制粘贴示例
    • 构建表单、表格、导航或数据展示
    • 触发短语: “示例”, “如何使用”, “实现”, “代码示例”

  3. 加载 references/dark-mode-setup.md 当:

    • 实现黑暗模式 / 主题切换
    • 用户提到 Vue 3 + Vite, Nuxt, 或 Astro 设置
    • 需要主题管理的可组合模式
    • 触发短语: “黑暗模式”, “主题”, “亮/暗”, “配色方案”

与其他技能集成

此技能可很好组合:

  • nuxt-v4 → Nuxt 框架
  • tailwind-v4-shadcn → Tailwind v4 与 React shadcn/ui
  • react-hook-form-zod → 表单验证模式 (类似 Auto Form)
  • tanstack-query → 数据获取用于表格
  • zustand-state-management → 状态管理

资源

参考 (references/):

  • component-examples.md - 所有 50+ 组件示例带代码
  • dark-mode-setup.md - 完整黑暗模式实现指南
  • error-catalog.md - 常见错误及解决方案

模板 (templates/):

  • 组件模板可在 references/component-examples.md 获得

附加资源

官方文档:

示例:

生产测试: Vue/Nuxt 应用程序, 管理仪表板, 内容管理系统 最后更新: 2025-12-09 令牌节省: ~65% (减少设置 + 组件文档)