Μετάβαση στο περιεχόμενο

Παραλλαγές

Προβολή ως Markdown Επεξεργασία στο GitHub Τεκμηρίωση στο 3843abd

Το variants() είναι μια PHP υλοποίηση του CVA (Class Variance Authority). Μετατρέπει μια δηλωτική διαμόρφωση — μια βασική κλάση, ονομασμένους άξονες παραλλαγών και προεπιλογές — σε συνάρτηση που αντιστοιχίζει props σε συμβολοσειρά κλάσεων. Χρησιμοποιήστε το όταν ένα στοιχείο έχει διαστάσεις στυλ, όπως μέγεθος και πρόθεση, που συνδυάζονται.

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() επιστρέφει ένα callable· καλέστε το με έναν πίνακα props (ή χωρίς όρισμα) για να λάβετε την επιλυμένη συμβολοσειρά.

Διαμόρφωση

Κλειδί Τύπος Σκοπός
base string Κλάσεις που εφαρμόζονται σε κάθε έξοδο.
variants array Ονομασμένοι άξονες, καθένας αντιστοιχίζει ονόματα τιμών σε συμβολοσειρές κλάσεων.
compoundVariants array Συμβολοσειρές κλάσεων που εφαρμόζονται μόνο όταν συνδυάζονται πολλές τιμές παραλλαγών.
defaultVariants array Τιμή ανά άξονα που χρησιμοποιείται όταν παραλείπεται ένα prop.

Όλα τα κλειδιά είναι προαιρετικά. Χωρίς variants, το αποτέλεσμα επιστρέφει base μαζί με τυχόν προσαρμοσμένες κλάσεις:

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

Μια τιμή παραλλαγής μπορεί να αντιστοιχεί σε null ώστε να μην προσθέτει τίποτα — χρήσιμο ως ρητή επιλογή «χωρίς τιμή» σε έναν άξονα.

Κλήση του αποτελέσματος

Περάστε έναν πίνακα props, όπως στο CVA. Τα κλειδιά αντιστοιχούν στα ονόματα των αξόνων παραλλαγών σας· οι άξονες που παραλείπονται χρησιμοποιούν την 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'

Το κλειδί class (και το ψευδώνυμό του className) προστίθεται στο τέλος της εξόδου. Η προσθήκη από μόνη της δεν επιλύει συγκρούσεις — δείτε παρακάτω το μοτίβο στοιχείου.

compoundVariants

Κάθε εγγραφή στο compoundVariants είναι ένας πίνακας συνθηκών παραλλαγών μαζί με ένα class (ή className) πρόσθετων κλάσεων. Οι κλάσεις εφαρμόζονται μόνο όταν όλες οι συνθήκες αντιστοιχούν στα επιλυμένα props (μαζί με τις προεπιλογές). Η τιμή μιας συνθήκης μπορεί να είναι μία συμβολοσειρά ή πίνακας συμβολοσειρών για αντιστοίχιση με οποιαδήποτε από πολλές τιμές.

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'

Μοτίβο στοιχείου

Η variants() απλώς προσθέτει το class· για να μπορούν οι καλούντες να παρακάμπτουν πραγματικά τις προεπιλογές παραλλαγών, τυλίξτε την έξοδο σε cn() ώστε οι συγκρούσεις να επιλύονται υπέρ του καλούντος.

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']);

Η κρυφή μνήμη static $styles δημιουργεί τη διαμόρφωση παραλλαγών μία φορά και την επαναχρησιμοποιεί στις κλήσεις.

compose()

Η compose() συγχωνεύει πολλά στοιχεία παραλλαγών σε ένα. Η σύνθετη συνάρτηση προωθεί κάθε prop σε κάθε στοιχείο, συλλέγει τις εξόδους τους και προσθέτει τυχόν 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'

Έτσι, επαναχρησιμοποιήσιμοι άξονες (αποστάσεις, ανύψωση, διάταξη) παραμένουν σε ξεχωριστούς ορισμούς και συνδυάζονται ανά στοιχείο.

Εισαγωγές

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

Και τα δύο βρίσκονται στον κύριο χώρο ονομάτων TailwindPHP και περιλαμβάνονται στο πακέτο — PHP υλοποίηση του CVA από τον Joe Bell.