shadcn-vue Badge 组件完全指南：安装、变体与源码级定制

UI组件前端【免费下载链接】shadcn-vueVue port of shadcn-ui项目地址https://gitcode.com/gh_mirrors/sh/shadcn-vue点击查看免费下载本篇技术指南以 shadcn-vue 官方文档的 Badge 组件页面为骨架结合仓库中的真实注册表源码与示例完整讲解 Badge徽章组件的安装方式、四种内置变体default / secondary / destructive / outline、底层cva样式变体机制的实现原理以及基于/lib/utils的cn工具进行样式合并与自定义扩展的实战方案。读完本文你将能够在自己的 Vue 3 Tailwind CSS 项目中独立安装、使用并深度定制 Badge 组件同时理解其背后 class-variance-authority 的变体设计模式。Badge 组件是什么Badge 用于展示一个徽章样式的小型标签或者一个看起来像徽章的组件。它的典型应用场景包括状态标记如进行中已完成已废弃分类标签与数量统计如3 条新消息表单字段的附属说明与图标、加载指示器组合形成更丰富的交互提示。在 shadcn-vue 中Badge 是少数不依赖任何 headless 交互逻辑的纯展示组件它没有键盘交互、焦点管理或 ARIA 状态核心就是一个基于 class-variance-authoritycva声明样式变体的容器。这也使它成为理解 shadcn-vue 样式系统的最佳入门组件之一。安装 BadgeBadge 组件的安装有两种方式通过 CLI 自动安装或手动复制源码。方式一CLI 安装在项目根目录执行以下命令npx shadcn-vuelatest add badge该命令会从注册表拉取 Badge 组件并放入项目的src/components/ui/badge目录同时自动处理依赖class-variance-authority、/lib/utils中的cn工具函数与路径别名。方式二手动复制若希望完全掌控源码可将以下代码复制到src/components/ui/badge/Badge.vue同时参考仓库中的 默认版本实现script setup langts import type { VariantProps } from class-variance-authority import { cva } from class-variance-authority import { cn } from /lib/utils definePropsProps() const badgeVariants cva( inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2, { variants: { variant: { default: border-transparent bg-primary text-primary-foreground hover:bg-primary/80, secondary: border-transparent bg-secondary text-secondary-foreground hover:bg-secondary/80, destructive: border-transparent bg-destructive text-destructive-foreground hover:bg-destructive/80, outline: text-foreground, }, }, defaultVariants: { variant: default, }, }, ) interface BadgeVariantProps extends VariantPropstypeof badgeVariants {} interface Props { variant?: BadgeVariantProps[variant] } /script template div :classcn(badgeVariants({ variant }), $attrs.class ?? ) slot / /div /template手动安装时需要确保项目具备以下前置条件安装了class-variance-authority存在/lib/utils模块并导出cn工具函数通常基于clsx与tailwind-mergeTailwind CSS 主题中定义了primary、secondary、destructive、ring等设计令牌颜色。源码剖析cva 变体如何工作仓库中的 badge/index.ts 提供了该组件更完整的生产级实现其中badgeVariants的定义与文档中的内联版本几乎一致但基础类中额外加入了gap-1import type { VariantProps } from class-variance-authority import { cva } from class-variance-authority export { default as Badge } from ./Badge.vue export const badgeVariants cva( inline-flex gap-1 items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2, { variants: { variant: { default: border-transparent bg-primary text-primary-foreground hover:bg-primary/80, secondary: border-transparent bg-secondary text-secondary-foreground hover:bg-secondary/80, destructive: border-transparent bg-destructive text-destructive-foreground hover:bg-destructive/80, outline: text-foreground, }, }, defaultVariants: { variant: default, }, }, ) export type BadgeVariants VariantPropstypeof badgeVariants几个值得注意的实现细节基础样式类baseinline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold transition-colors定义了徽章的胶囊外形、字号与过渡动画是所有变体共享的骨架focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2保证了键盘聚焦时的可见性符合可访问性要求。变体variants四个变体通过 Tailwind 颜色令牌切换主题default使用primary前景/背景色并带hover:bg-primary/80悬停反馈secondary/destructive同理outline只设置text-foreground保留边框、去掉填充。默认变体defaultVariantsvariant: default表示未传variantprop 时自动回退到 primary 风格。类型安全BadgeVariants VariantPropstypeof badgeVariants把 cva 的变体类型自动推导为联合类型使组件variantprop 获得完整的类型提示与编译期校验。对应的 Badge.vue 组件实现非常精简script setup langts import type { HTMLAttributes } from vue import type { BadgeVariants } from . import { cn } from /lib/utils import { badgeVariants } from . const props defineProps{ variant?: BadgeVariants[variant] class?: HTMLAttributes[class] }() /script template div :classcn(badgeVariants({ variant }), props.class) slot / /div /template它只做三件事接收variant与classprop调用badgeVariants({ variant })生成变体类名再通过cn()与外部传入的class合并——cn内部的 tailwind-merge 会智能处理类名冲突因此调用方传入的bg-*、text-*等类可以安全地覆盖默认样式这就是 Badge 易于定制的根本原因。基本使用安装完成后在任意组件中导入并使用script setup langts import { Badge } from /components/ui/badge /script template BadgeBadge/Badge /templateBadge通过默认插槽slot /渲染任意内容文本、图标、甚至是内嵌的加载指示器都可以直接放入。四种内置变体示例仓库中的四个示例组件见 demo 目录展示了全部内置变体的用法Default默认template BadgeBadge/Badge /template对应源码BadgeDemo.vue。使用primary主题色填充是最常用的主视觉徽章。Secondary次要template Badge variantsecondary Secondary /Badge /template对应源码BadgeSecondaryDemo.vue。使用secondary主题色适合作为次要信息或弱化操作区的标签。Outline描边template Badge variantoutline Outline /Badge /template对应源码BadgeOutlineDemo.vue。无填充色仅保留边框与前景色适合低调的元信息展示。Destructive破坏性template Badge variantdestructive Destructive /Badge /template对应源码BadgeDestructiveDemo.vue。使用destructive红色系用于错误、删除、危险操作等负面语义标记。进阶用法图标、链接、加载态与自定义颜色在仓库的 v4 注册表中Badge 提供了比文档更丰富的一组扩展示例见 bases/reka/examples/badge可作为实战参考BadgeVariants.vue一次性展示全部变体其中还包含文档未提及的ghost与link变体v4 版本新增印证了 cva 变体集合的可扩展性BadgeAsLink.vue把徽章渲染为链接实现可点击的标签导航BadgeWithIconLeft.vue / BadgeWithIconRight.vue在文本两侧插入图标配合基础类中的gap-1自动保持图标与文字的间距BadgeWithSpinner.vue内嵌加载指示器适合保存中上传中等异步状态BadgeCustomColors.vue通过cn合并机制用自定义 Tailwind 类覆盖默认配色BadgeLongText.vue演示长文本场景下的换行与布局表现。同时v4 版本的 Badge.vue 基于 reka-ui 的Primitive组件重构通过reactiveOmit透传非 class 属性并额外标注了data-slotbadge与data-variant数据属性方便针对组件进行选择器定位与样式挂钩script setup langts import type { PrimitiveProps } from reka-ui import type { HTMLAttributes } from vue import type { BadgeVariants } from . import { reactiveOmit } from vueuse/core import { Primitive } from reka-ui import { cn } from /lib/utils import { badgeVariants } from . const props definePropsPrimitiveProps { variant?: BadgeVariants[variant] class?: HTMLAttributes[class] }() const delegatedProps reactiveOmit(props, class) /script template Primitive >赞分享UI组件前端【免费下载链接】shadcn-vueVue port of shadcn-ui项目地址https://gitcode.com/gh_mirrors/sh/shadcn-vue点击查看免费下载相关推荐shadcn-vue Alert 组件完全指南安装、用法与变体定制shadcn vue Alert 组件完全指南安装、用法与变体定制 本文围绕 shadcn vueVue 版 shadcn ui仓库中的 Alert 组件UI组件前端shadcn-vue 手风琴Accordion组件完全指南从安装、用法到源码级定制shadcn vue 手风琴Accordion组件完全指南从安装、用法到源码级定制 导读 本文围绕 shadcn vue 仓库中 Accordion手风UI组件前端shadcn-vue Table 组件完全指南安装、组合式 API 与源码级解析shadcn vue Table 组件完全指南安装、组合式 API 与源码级解析 Table 是 shadcn vue 中一个响应式responsive数UI组件前端上一篇解码Windows网络黑匣子etl2pcapng如何让ETL文件在Wireshark中开口说话下一篇终极指南Karabiner-Elements键盘映射工具的系统权限与唤醒问题深度解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考