当前位置：首页 > news >正文

【CSS 】Class Variance Authority CSS 类名管理工具库

news 来源：原创 2025/5/19 8:42:39

1.背景、什么是 CVA？

Class Variance Authority (CVA) 是一个用于管理 CSS 类名 的工具库，特别适合在 React 或 Vue 等前端框架中使用。
它可以帮助你更轻松地处理组件的 样式变体（Variants），比如按钮的不同状态（primary、secondary、disabled 等）。
它非常契合像 Tailwind CSS 这类的原子化思想。

2.`CVA`的主要功能和特点?

结构化样式管理：CVA提供了一种结构化的方式来管理样式变体，减少了全局样式冲突的可能性。它允许开发者以声明的方式描述每个参数值的样式，从而自动找出正确的样式组合。
方便样式复用和扩展：当需要添加新的样式变体时，CVA使得扩展变得更加方便和高效。开发者可以通过定义variants、compoundVariants和defaultVariants等参数，来轻松创建可复用的样式组合。
减少样式冲突：由于CVA采用了结构化的样式管理方式，因此可以大大减少样式冲突的可能性。这使得在大型项目中维护样式变得更加容易。

3.`CVA` 的使用场景

CVA 特别适用于使用Tailwind CSS 等原子化 CSS 框架的项目。
在这些项目中，开发者通常需要根据组件的 props 值将 Tailwind 类组合在一起，以创建可重用的 UI 元素。
然而，随着组件样式的增加，这种组合方式可能会变得非常复杂。通过引入 CVA，开发者可以消除这种复杂性，并以声明的方式描述每个参数值的样式。

4.如何在项目中使用 `CVA`

4.1安装

你可以通过 npm 或 pnpm 安装 CVA：

npm install class-variance-authority

或者

pnpm add class-variance-authority

4.2 `CVA`函数参数

基础类名（Base Classes）
1. 参数形式：通常是一个数组（也可以是一个用空格分割的字符串），包含一组基础的 CSS类名。
  1. [‘pl-2’, ‘pt-1’]
  2. ‘pl-2 pt-1’
2. 作用：这些基础类名会被应用到所有生成的样式类名组合中，作为样式的基础部分。它们不是“默认值”意义上的参数，而是函数调用的必需部分。
变体定义（Variants Definitions）
1. 参数形式：一个对象，其键是变体属性的名称，值通常是一个对象，该对象定义了不同属性值对应的CSS类名数组。
2. 作用：变体定义用于指定不同属性组合下的样式变化。这里的对象不是“第二个值”的固定形式，而是变体定义的一种常见结构。
其他可选参数
1. 复合变体（Compound Variants）：一个对象，定义了当多个变体属性同时满足特定条件时应用的额外CSS类名。
2. 默认变体（Default Variants）：一个数组或者是一个字符串，指定了当没有提供特定变体属性值时应使用的默认值。

4.3 定义`CVA`函数

4.3.1 基础使用

以下是一个简单的示例，展示如何使用 CVA 创建一个带有变体的按钮组件。

4.3.1.1 第一步

button.tsx

import React from "react";
import { cva } from "class-variance-authority";

export type ButtonProps = {
    intent: "primary" | "secondary" | "danger";
    size: "small" | "medium" | "large";
    children: React.ReactNode;
}

/** 
 * 定义样式变体 buttonVariants
 *  cva：核心函数，用于定义样式变体。
 *  variants：定义组件的变体（如 intent 和 size）。
 *  defaultVariants：设置默认的变体值。
*/
const buttonVariants = cva("button", {
    variants: {
        intent: {
            primary: "bg-blue-500 text-white",
            secondary: "bg-gray-500 text-white",
            danger: "bg-red-500 text-white",
        },
        size: {
            small: "text-sm py-1 px-2",
            medium: "text-base py-2 px-4",
            large: "text-lg py-3 px-6",
        },
    },
    defaultVariants: {
        intent: "primary",
        size: "medium",
    },
});

/** 
 * 按钮组件 
 *  buttonVariants({ intent, size })：根据传入的 intent 和 size 动态生成类名。
*/
const Button = ({ intent, size, children }: ButtonProps) => {
    return (
        <button className={buttonVariants({ intent, size })}>
            {children}
        </button>
    );
};

export default Button;

4.3.2.1.2 第二步使用 botton 按钮

根据传入的 intent 和 size 动态生成类名。

import Button from './botton.tsx'

function App() {
  return (
    <div>
      {/* button bg-blue-500 text-white text-base py-2 px-4 */}
      <Button intent="primary" size="medium">Primary Button</Button>
      {/* button bg-gray-500 text-white text-sm py-1 px-2500 */}
      <Button intent="secondary" size="small">Secondary Button</Button>
      {/* 样式为: button bg-red-500 text-white text-lg py-3 px-6 */}
      <Button intent="danger" size="large">Danger Button</Button>
    </div>
  );
}

export default App;

4.3.1.2 高级用法

4.3.1.2.1 第一步：复合变体, 你可以定义多个变体的组合!

button.tsx

import React from "react";
import { cva } from "class-variance-authority";

export type ButtonProps = {
    intent: "primary" | "secondary"
    disabled: boolean
    children: React.ReactNode
}

/** 
 * 定义样式变体 
 *  cva 第一个参数："button" 是基础类名，用于定义组件的默认样式(如果有多个用空格分即可)。
 *  variants：定义组件的变体（如 intent 和 size）。
 *  defaultVariants：设置默认的变体值。
 *  compoundVariants：用于定义多个变体的组合样式。   
*/

const buttonVariants = cva("button", {
    variants: {
        intent: {
            primary: "bg-blue-500 text-white",
            secondary: "bg-gray-500 text-white",
        },
        outlined: {
            true: "border-2",
        },
    },
    compoundVariants: [
        {
            intent: "primary",
            outlined: false,
            class: "border-blue-500",
        },
        {
            intent: "secondary",
            outlined: false,
            class: "border-gray-500",
        },
    ],
});

/** 
 * 按钮组件 
 *  buttonVariants({ intent, disabled })：根据传入的 intent 和 size 动态生成类名。
 *  当 intent="secondary" 时，disabled=false 时, 它会添加 border-gray-500 类名到结果数组中; 
*/

const Button = ({ intent, disabled }: ButtonProps) => {
    return (
        <button
            className={buttonVariants({
                intent,
                outlined: disabled,
            })}
        >
            Click Me
        </button>
    );
};

export default Button;

4.3.1.2.2 第二步

根据传入的 intent 和 disabled动态生成类名。

import Button from './botton.tsx'

function App() {
  return (
    <div>
      {/* 
        当 intent="secondary" 时，disabled=true 时，样式为：
         button bg-blue-500 text-white border-2 
      */}
      <Button intent="primary" disabled>Primary Button</Button>
      {/* 
        当 intent="secondary" 时，disabled=false 时，样式为:
          button bg-gray-500 text-white border-gray-500 
      */}
      <Button intent="secondary"disabled={false}>Secondary Button</Button>
    </div>
  );
}

export default App;