Dyrektywy

Dyrektywy to reguły at-rule z prefiksem @, zapisywane w wejściowym CSS, służące do komponowania, rozszerzania i porządkowania wyników Tailwind. Ta strona omawia @apply, @utility, @variant, @custom-variant i @layer. @theme opisano w sekcji Motyw; @plugin w sekcji Wtyczki; a @source w sekcji @source.

@apply

@apply umieszcza deklaracje istniejących narzędzi we własnym selektorze. Użyj go, aby przypisać style narzędzi do klasy semantycznej, także wewnątrz zagnieżdżonych selektorów i zapytań o media.

use TailwindPHP\tw;

$css = tw::generate('<div class="btn">', '
    @import "tailwindcss";

    @theme { --color-brand: #3b82f6; }

    .btn {
        @apply px-4 py-2 rounded-lg bg-brand text-white;
    }
');

Warianty działają w liście @apply — @apply bg-blue-500 hover:bg-blue-600; rozwija stan :hover, a responsywne prefiksy, takie jak @apply px-4 md:px-6 lg:px-8;, emitują odpowiednie reguły @media. Obsługiwany jest też modyfikator important (@apply !flex;). Obsługiwane są zagnieżdżone selektory, więc reguła taka jak .card { h2 { @apply text-xl font-bold; } } stosuje narzędzia do zagnieżdżonego h2.

@apply jest instrukcją: @apply px-4 { … } z treścią powoduje błąd. Reguła @apply zawierająca wyłącznie identyfikatory z łącznikiem (@apply --my-mixin;) to mixin CSS z wersji roboczej CSS mixinów, a nie lista narzędzi, więc TailwindPHP jej nie rozpoznaje; umieszczenie mixina i narzędzi w tej samej regule @apply powoduje błąd (You cannot use @apply with both mixins and utilities…). Reguły mixinów są obecnie pomijane w wynikach, zamiast być przekazywane dalej (#12).

@utility

@utility rejestruje własne narzędzie uczestniczące w działaniu silnika Tailwind — jest sortowane w warstwie utilities i obsługuje warianty tak jak narzędzia wbudowane. Narzędzie statyczne ma stałą treść:

@utility content-auto {
    content-visibility: auto;
}

Ponieważ jest to prawdziwe narzędzie, warianty łączą się automatycznie (hover:content-auto, md:content-auto). Treść może sama korzystać z @apply i zagnieżdżonych selektorów:

@utility btn-primary {
    @apply px-4 py-2 bg-blue-500 text-white rounded;
}

@utility card {
    color: red;
    &:hover { color: blue; }
}

Narzędzie funkcyjne używa sufiksu -* w nazwie i odczytuje dopasowaną wartość za pomocą --value():

@theme {
    --gutter-wide: 3rem;
}

@utility gutter-* {
    padding-inline: --value(--gutter-*, [length]);
    padding-inline: --spacing(--value(integer));
}

--value() sprawdza wartość kandydata kolejno w każdym źródle: przestrzeni nazw motywu (--gutter-*), dowolnej wartości z typem danych ([length]) albo prostym typie wartości (integer, number, percentage, ratio). Deklaracja, której --value() nie zostanie rozpoznane, jest pomijana, więc zestawienie deklaracji tworzy łańcuch wartości zapasowych:

--modifier() rozpoznaje część po / w ten sam sposób: gdy treść zawiera line-height: --modifier(integer);, gutter-4/7 również emituje line-height: 7. Nazwy narzędzi podlegają regułom TailwindCSS v4.3.3: najwyżej jeden /, % wyłącznie na końcu po cyfrze, a kropki tylko między cyframi.

@variant

@variant stosuje wariant do deklaracji we własnym CSS, nie definiując narzędzia:

.card {
    color: red;

    @variant hover {
        color: blue;
    }

    @variant dark {
        color: white;
    }
}

.card {
  color: red;
}
@media (hover: hover) {
  .card:hover {
    color: #00f;
  }
}
@media (prefers-color-scheme: dark) {
  .card {
    color: #fff;
  }
}

Warianty można łączyć (@variant hover:focus), rozdzielać przecinkami, zagnieżdżać w sobie i tworzyć z nazw własnych @custom-variant. Górna reguła @variant bez treści lub zawierająca @slot jest traktowana jako @custom-variant dla zgodności wstecznej.

@custom-variant

@custom-variant definiuje nowy wariant, który można dodawać jako prefiks do dowolnego narzędzia. Zwięzła forma podaje nazwę wariantu oraz selektor lub regułę at-rule w nawiasach.

Wariant listy selektorów używa & dla elementu:

@custom-variant hocus (&:hover, &:focus);

hocus:bg-blue-500 emituje następnie zarówno reguły :hover, jak i :focus. Forma atrybutowa działa tak samo:

@custom-variant loading (&[data-loading="true"]);

Wariant at-rule obejmuje dopasowane narzędzia tą regułą at-rule:

@custom-variant tablet (@media (min-width: 600px));

Własne warianty można łączyć z wbudowanymi — sm:hocus:bg-blue-500 zagnieżdża selektor hocus w zapytaniu o media sm. W bardziej złożonych przypadkach użyj formy blokowej, w której @slot wskazuje miejsce wstawienia deklaracji narzędzia:

@custom-variant child {
    & > * {
        @slot;
    }
}

@custom-variant sidebar-open {
    .sidebar-open & {
        @slot;
    }
}

@layer

@layer kontroluje kolejność kaskady za pomocą natywnych warstw kaskady CSS. Samodzielna instrukcja @layer deklaruje kolejność warstw; późniejsze warstwy mają pierwszeństwo niezależnie od specyficzności selektora. Kanoniczna kolejność Tailwind to:

@layer theme, base, components, utilities;

Właśnie to @import "tailwindcss" konfiguruje wewnętrznie. Możesz zadeklarować własną kolejność albo rozdzielić ją na kilka instrukcji (@layer reset, base;, a następnie @layer components, utilities;) i przypisać reguły do nazwanej warstwy za pomocą bloku:

use TailwindPHP\tw;

$css = tw::generate('<article><h1>Title</h1></article>', '
    @import "tailwindcss";

    @layer base {
        h1 { font-size: var(--text-2xl); }
        a  { color: var(--color-blue-600); text-decoration-line: underline; }
    }
');

Dodanie stylów bazowych przez @layer base umieszcza je poniżej components i utilities, dzięki czemu klasa narzędzia zawsze nadpisuje domyślne style elementu. To samo dotyczy @layer components { … } w przypadku klas komponentów, które powinny znajdować się pod narzędziami. Anonimowe warstwy i modyfikatory layer() w @import opisano w sekcji Importy.

Następne kroki

• Motyw — tokeny @theme i funkcje motywu.
• Importy — @import, moduły wirtualne i modyfikatory layer().
• Wtyczki — dyrektywa @plugin i API wtyczek API.
• @source — kontrola plików i klas skanowanych przez narzędzie.