Narzędzia klas

Wyświetl jako Markdown Edytuj w GitHub Dokumentacja: 3843abd

Budowanie atrybutów class w szablonach wymaga łączenia ciągów, przełączania klas zależnie od warunków i zapobiegania konfliktom późniejszych utility z wcześniejszymi (p-2 i p-4 nie powinny występować jednocześnie). W JavaScript zadania te rozdzielono między clsx i tailwind-merge. TailwindPHP zawiera porty PHP obu narzędzi, dzięki czemu uzyskujesz takie samo działanie bez narzędzi Node.js i dodatkowych pakietów Composer.

Trzy funkcje obejmują cały zakres zastosowań: cn() tworzy i rozwiązuje konflikty, merge() tylko rozwiązuje konflikty, a join() jedynie łączy ciągi.

cn()

Zalecana funkcja utility. Najpierw wykonuje warunkowe tworzenie w stylu clsx, a następnie rozwiązuje konflikty Tailwind za pomocą tailwind-merge — wygrywa więc ostatnie konfliktujące utility.

PHP

use function TailwindPHP\cn;

// Conflicts are resolved — px-4 overrides px-2
cn('px-2 py-1', 'px-4');
// => 'py-1 px-4'

// Conditional classes via a key => bool array
cn('btn', ['btn-primary' => true, 'btn-disabled' => false]);
// => 'btn btn-primary'

Akceptowane argumenty

cn() przyjmuje dowolną liczbę argumentów. Każdy jest spłaszczany i filtrowany zgodnie z semantyką clsx:

Argument	Działanie
`string`	Dodany bez zmian.
`int` / `float`	Konwertowane na ciąg i dodawane.
Tablica sekwencyjna	Każdy element jest przetwarzany rekurencyjnie.
Tablica `key => bool`	Każdy klucz jest dodawany, gdy jego wartość jest prawdziwa.
`null`, `false`, `0`, `''`	Pomijane.

PHP

cn('flex', ['items-center' => true], ['p-4', ['gap-2']], null);
// => 'flex items-center p-4 gap-2'

Wzorzec komponentu

cn() umożliwia nadpisywanie komponentu: połącz jego własne klasy z klasami przekazanymi przez wywołującego, a konflikty zostaną rozstrzygnięte na korzyść wywołującego.

PHP

use function TailwindPHP\cn;

function Card(array $props = []): string {
    $class = cn(
        'rounded-lg border bg-card text-card-foreground shadow-sm',
        $props['class'] ?? null
    );
    return "<div class=\"{$class}\">" . ($props['children'] ?? '') . "</div>";
}

Card(['class' => 'p-6', 'children' => 'Content']);
// <div class="rounded-lg border bg-card text-card-foreground shadow-sm p-6">Content</div>

W przypadku deklaratywnych stylów komponentów o wielu osiach połącz cn() z variants().

merge()

Samo rozwiązywanie konfliktów — bez warunkowego tworzenia. Przekazuj ciągi klas; późniejsze klasy nadpisują wcześniejsze, jeśli dotyczą tej samej właściwości. Użyj tej funkcji, gdy dane wejściowe są już zwykłymi ciągami.

PHP

use function TailwindPHP\merge;

merge('px-2 py-1 bg-red-500', 'px-4 bg-blue-500');
// => 'py-1 px-4 bg-blue-500'

// Conflict resolution is variant-aware
merge('hover:bg-red-500', 'hover:bg-blue-500');
// => 'hover:bg-blue-500'

cn() jest merge() opartym na clsx, więc sięgnij bezpośrednio po merge() tylko wtedy, gdy nie potrzebujesz składni tablic warunkowych.

join()

Proste łączenie bez rozwiązywania konfliktów. Wartości fałszywe są pomijane, ale wszystkie konfliktujące utility zostają zachowane. Użyj tej funkcji, gdy wiesz, że nie ma konfliktów i zależy Ci na najtańszym rozwiązaniu.

PHP

use function TailwindPHP\join;

join('foo', 'bar', null, 'baz');
// => 'foo bar baz'

Której funkcji użyć?

Funkcja	Tworzy (warunki, tablice)	Rozwiązuje konflikty	Użyj, gdy
`cn()`	tak	tak	Domyślny wybór — do tworzenia ciągów klas, w których mogą występować konflikty.
`merge()`	nie	tak	Dane wejściowe to zwykłe ciągi; potrzebujesz tylko rozwiązywania konfliktów.
`join()`	tak	nie	Wiesz, że nie ma konfliktów i chcesz wykonać jak najmniej pracy.

Importy

PHP

use function TailwindPHP\cn;
use function TailwindPHP\merge;
use function TailwindPHP\join;

Wszystkie trzy funkcje znajdują się w głównej przestrzeni nazw TailwindPHP i są dołączone do pakietu. To porty PHP clsx (autorstwa Luke’a Edwardsa) i tailwind-merge (autorstwa Dany’ego Castillo).