Preskočiť na obsah

Varianty

Zobraziť ako Markdown Upraviť na GitHub Dokumentácia na 3843abd

variants() je PHP port CVA (Class Variance Authority). Deklaratívnu konfiguráciu — základ, pomenované osi variantov a predvolené hodnoty — prevedie na volateľnú funkciu, ktorá mapuje vlastnosti na reťazec tried. Použite ho pre komponenty s kombinovateľnými rozmermi štýlu, ako sú veľkosť a zámer.

PHP
use function TailwindPHP\variants;

$button = variants([
    'base' => 'btn font-semibold border rounded',
    'variants' => [
        'intent' => [
            'primary'   => 'bg-blue-500 text-white',
            'secondary' => 'bg-gray-200 text-gray-800',
        ],
        'size' => [
            'sm' => 'text-sm px-2 py-1',
            'md' => 'text-base px-4 py-2',
        ],
    ],
    'defaultVariants' => [
        'intent' => 'primary',
        'size'   => 'md',
    ],
]);

$button();
// => 'btn font-semibold border rounded bg-blue-500 text-white text-base px-4 py-2'

variants() vracia callable; zavolaním s poľom vlastností (alebo bez neho) získate rozriešený reťazec.

Konfigurácia

Kľúč Typ Účel
base string Triedy použité v každom výstupe.
variants array Pomenované osi, z ktorých každá mapuje názvy hodnôt na reťazce tried.
compoundVariants array Reťazce tried použité iba pri kombinácii viacerých hodnôt variantov.
defaultVariants array Hodnota pre každú os, ktorá sa použije, keď vlastnosť chýba.

Všetky kľúče sú voliteľné. Ak chýba variants, výsledok obsahuje base a všetky vlastné triedy:

PHP
$x = variants(['base' => 'box']);
$x();                          // => 'box'
$x(['class' => 'p-4']);        // => 'box p-4'

Hodnote variantu možno priradiť null, čím nepridá nič — užitočné ako výslovná možnosť „nenastavené“ v danej osi.

Volanie výsledku

Odovzdajte jedno pole vlastností v štýle CVA. Kľúče zodpovedajú názvom osí variantov; chýbajúce osi prevezmú hodnoty z defaultVariants.

PHP
$button(['intent' => 'secondary']);
// => 'btn font-semibold border rounded bg-gray-200 text-gray-800 text-base px-4 py-2'

$button(['size' => 'sm', 'class' => 'mt-4']);
// => 'btn font-semibold border rounded bg-blue-500 text-white text-sm px-2 py-1 mt-4'

Kľúč class (a jeho alias className) sa pridá na koniec výstupu. Samotné pridanie nevyrieši konflikty — ďalšie informácie nájdete vo vzore komponentu nižšie.

compoundVariants

Každá položka v compoundVariants je pole podmienok variantu a class (alebo className) s dodatočnými triedami. Triedy sa použijú iba vtedy, keď sa všetky podmienky zhodujú s vyriešenými vlastnosťami (vrátane predvolených hodnôt). Hodnota podmienky môže byť jeden reťazec alebo pole reťazcov, ktoré umožňuje zhodu s viacerými hodnotami.

PHP
$button = variants([
    'base' => 'btn',
    'variants' => [
        'intent' => [
            'primary' => 'bg-blue-500',
            'warning' => 'bg-yellow-500',
            'danger'  => 'bg-red-500',
        ],
        'size' => ['sm' => 'text-sm', 'md' => 'text-base'],
    ],
    'compoundVariants' => [
        // Applies only when intent=primary AND size=md
        ['intent' => 'primary', 'size' => 'md', 'class' => 'uppercase'],
        // Applies when intent is warning OR danger
        ['intent' => ['warning', 'danger'], 'class' => '!border-red-500'],
    ],
    'defaultVariants' => ['intent' => 'primary', 'size' => 'md'],
]);

$button();
// => 'btn bg-blue-500 text-base uppercase'

$button(['intent' => 'danger']);
// => 'btn bg-red-500 text-base !border-red-500'

Vzor komponentu

variants() iba pridáva class; ak chcete volajúcim umožniť skutočne prepísať predvolené hodnoty variantu, obaľte výstup do cn(), aby sa pri konfliktoch uprednostnili hodnoty volajúceho.

PHP
use function TailwindPHP\variants;
use function TailwindPHP\cn;

function Button(array $props = []): string {
    static $styles = null;
    $styles ??= variants([
        'base' => 'inline-flex items-center justify-center rounded-md font-medium',
        'variants' => [
            'variant' => [
                'default' => 'bg-primary text-primary-foreground hover:bg-primary/90',
                'outline' => 'border border-input bg-background hover:bg-accent',
                'ghost'   => 'hover:bg-accent hover:text-accent-foreground',
            ],
            'size' => [
                'default' => 'h-10 px-4 py-2',
                'sm'      => 'h-9 px-3',
                'lg'      => 'h-11 px-8',
            ],
        ],
        'defaultVariants' => ['variant' => 'default', 'size' => 'default'],
    ]);

    // cn() merges variant output with custom classes, resolving conflicts
    $class = cn($styles($props), $props['class'] ?? null);
    $text  = $props['children'] ?? 'Button';
    return "<button class=\"{$class}\">{$text}</button>";
}

// The custom px-8 wins over the variant's px-3 via cn()
Button(['variant' => 'outline', 'size' => 'sm', 'class' => 'mt-4 px-8']);

Vyrovnávacia pamäť static $styles zostaví konfiguráciu variantu raz a opätovne ju použije pri ďalších volaniach.

compose()

compose() zlúči niekoľko komponentov variantov do jedného. Zložená funkcia odovzdá každú vlastnosť všetkým komponentom, zhromaždí ich výstupy a pridá všetky class/className.

PHP
use function TailwindPHP\variants;
use function TailwindPHP\compose;

$box   = variants(['variants' => ['shadow' => ['sm' => 'shadow-sm', 'md' => 'shadow-md']]]);
$stack = variants(['variants' => ['gap' => ['1' => 'gap-1', '2' => 'gap-2']]]);
$card  = compose($box, $stack);

$card(['shadow' => 'md', 'gap' => '2']);
// => 'shadow-md gap-2'

Vďaka tomu zostávajú opakovane použiteľné osi (rozostupy, vyvýšenie, rozloženie) v samostatných definíciách a kombinujú sa pre každý komponent.

Importy

PHP
use function TailwindPHP\variants;
use function TailwindPHP\compose;

Oba sa nachádzajú v hlavnom mennom priestore TailwindPHP a sú súčasťou balíka — ide o port knižnice CVA od Joea Bella v jazyku PHP.