`html_cva`

3.12

html_cva 函数在 Twig 3.12 中添加。

CVA (Class Variant Authority) 是来自 JavaScript 世界的概念，并被著名的 shadcn/ui 库使用。 CVA 概念用于渲染组件的多种变体，应用一组条件和配方来动态组合 CSS 类字符串（颜色、尺寸等），以创建高度可重用和可定制的模板。

CVA 的概念由 html_cva() Twig 函数驱动，您可以在其中定义应始终存在的 base 类，然后定义不同的 variants 和相应的类

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
        {# templates/alert.html.twig #}
{% set alert = html_cva(
    base: 'alert',
    variants: {
        color: {
            blue: 'bg-blue',
            red: 'bg-red',
            green: 'bg-green',
        },
        size: {
            sm: 'text-sm',
            md: 'text-md',
            lg: 'text-lg',
        }
    }
) %}

<div class="{{ alert.apply({color, size}, class) }}">
    ...
</div>
    

然后使用 color 和 size 变体来选择所需的类

        1
2
3
4
5
6
7
8
9
        {# index.html.twig #}
{{ include('alert.html.twig', {'color': 'blue', 'size': 'md'}) }}
// class="alert bg-blue text-md"

{{ include('alert.html.twig', {'color': 'green', 'size': 'sm'}) }}
// class="alert bg-green text-sm"

{{ include('alert.html.twig', {'color': 'red', 'class': 'flex items-center justify-center'}) }}
// class="alert bg-red flex items-center justify-center"
    

CVA 和 Tailwind CSS

CVA 与 Tailwind CSS 完美配合。唯一的缺点是您可能会遇到类冲突。要“合并”冲突的类并仅保留您需要的类，请将 tailwind_merge() 过滤器与来自 tales-from-a-dev/twig-tailwind-extra 的 html_cva() 函数一起使用

        1
        $ composer require tales-from-a-dev/twig-tailwind-extra
    

        1
2
3
4
5
6
7
        {% set alert = html_cva(
   // ...
) %}

<div class="{{ alert.apply({color, size}, class)|tailwind_merge }}">
     ...
</div>
    

复合变体

您可以定义复合变体。复合变体是在满足多个其他变体条件时应用的变体

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
        {% set alert = html_cva(
    base: 'alert',
    variants: {
        color: {
            blue: 'bg-blue',
            red: 'bg-red',
            green: 'bg-green',
        },
        size: {
            sm: 'text-sm',
            md: 'text-md',
            lg: 'text-lg',
        }
    },
    compoundVariants: [{
        // if color = red AND size = (md or lg), add the `font-bold` class
        color: ['red'],
        size: ['md', 'lg'],
        class: 'font-bold'
    }]
) %}

<div class="{{ alert.apply({color, size}) }}">
     ...
</div>

{# index.html.twig #}

{{ include('alert.html.twig', {color: 'red', size: 'lg'}) }}
// class="alert bg-red text-lg font-bold"

{{ include('alert.html.twig', {color: 'green', size: 'sm'}) }}
// class="alert bg-green text-sm"

{{ include('alert.html.twig', {color: 'red', size: 'md'}) }}
// class="alert bg-green text-md font-bold"
    

默认变体

如果没有任何变体匹配，您可以定义一组默认类来应用

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
        {% set alert = html_cva(
    base: 'alert',
    variants: {
        color: {
            blue: 'bg-blue',
            red: 'bg-red',
            green: 'bg-green',
        },
        size: {
            sm: 'text-sm',
            md: 'text-md',
            lg: 'text-lg',
        },
        rounded: {
            sm: 'rounded-sm',
            md: 'rounded-md',
            lg: 'rounded-lg',
        }
    },
    defaultVariant: {
        rounded: 'md',
    }
) %}

<div class="{{ alert.apply({color, size}) }}">
     ...
</div>

{# index.html.twig #}

{{ include('alert.html.twig', {color: 'red', size: 'lg'}) }}
// class="alert bg-red text-lg rounded-md"
    

注意

html_cva 函数是默认未安装的 HtmlExtension 的一部分。请先安装它

        1
        $ composer require twig/html-extra
    

然后，在 Symfony 项目上，安装 twig/extra-bundle

        1
        $ composer require twig/extra-bundle
    

否则，在 Twig 环境中显式添加扩展

        1
2
3
4
        use Twig\Extra\Html\HtmlExtension;

$twig = new \Twig\Environment(...);
$twig->addExtension(new HtmlExtension());
    

此函数与 TwigComponent 一起使用时效果最佳。

目录

问题与反馈

许可证

html_cva

CVA 和 Tailwind CSS

复合变体

默认变体

`html_cva`