Directive

Directivele sunt reguli at prefixate cu @, pe care le scrieți în fișierul de intrare CSS pentru a compune, extinde și ordona rezultatul Tailwind. Această pagină prezintă @apply, @utility, @variant, @custom-variant și @layer. @theme este prezentată în Temă; @plugin în Pluginuri; iar @source în @source.

@apply

@apply încorporează declarațiile utilitarelor existente în propriul selector. Folosiți-o pentru a atașa stiluri utilitare unei clase semantice, inclusiv în selectori imbricați și interogări 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;
    }
');

Variantele funcționează într-o listă @apply — @apply bg-blue-500 hover:bg-blue-600; extinde starea :hover, iar prefixele responsive precum @apply px-4 md:px-6 lg:px-8; emit regulile @media corespunzătoare. Este respectat și modificatorul important (@apply !flex;). Selectorii imbricați sunt acceptați, așadar o regulă precum .card { h2 { @apply text-xl font-bold; } } aplică utilitare selectorului imbricat h2.

@apply este o instrucțiune: @apply px-4 { … } cu un corp provoacă o eroare. Un @apply care conține doar identificatori cu cratimă (@apply --my-mixin;) este un mixin CSS din proiectul de mixinuri CSS, nu o listă de utilitare, așa că TailwindPHP nu îl rezolvă; includerea unui mixin și a utilitarelor în același @apply provoacă o eroare (You cannot use @apply with both mixins and utilities…). Regulile mixinurilor sunt eliminate momentan din rezultat, în loc să fie păstrate (#12).

@utility

@utility înregistrează un utilitar personalizat care participă la motorul Tailwind — este sortat în stratul utilities și acceptă variante ca orice utilitar integrat. Un utilitar static are un corp fix:

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

Fiind un utilitar real, variantele se combină automat (hover:content-auto, md:content-auto). Corpul poate folosi la rândul său @apply și selectori imbricați:

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

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

Un utilitar funcțional folosește un sufix -* în nume și citește valoarea potrivită cu --value():

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

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

--value() rezolvă valoarea candidatului pe rând pentru fiecare sursă: un spațiu de nume al temei (--gutter-*), o valoare arbitrară cu tip de date ([length]) sau un tip de valoare simplu (integer, number, percentage, ratio). O declarație al cărei --value() nu poate fi rezolvat este eliminată, astfel încât stivuirea declarațiilor creează o secvență de valori de rezervă:

--modifier() rezolvă partea de după un / în același mod: cu line-height: --modifier(integer); în corp, gutter-4/7 emite și line-height: 7. Numele utilitarelor respectă regulile TailwindCSS v4.3.3: cel mult un /, % doar la final, după o cifră, iar punctele doar între cifre.

@variant

@variant aplică o variantă declarațiilor din propriul CSS, fără a defini un utilitar:

.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;
  }
}

Variantele pot fi stivuite (@variant hover:focus), enumerate cu virgule, imbricate unele în altele și pot denumi propriile @custom-variant. O regulă @variant de nivel superior, fără corp sau cu @slot, este tratată ca @custom-variant pentru compatibilitate inversă.

@custom-variant

@custom-variant definește o variantă nouă pe care o puteți adăuga ca prefix oricărui utilitar. Forma compactă numește varianta și specifică un selector sau o regulă at între paranteze.

O variantă cu listă de selectori folosește & pentru element:

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

hocus:bg-blue-500 emite apoi atât regulile :hover, cât și :focus. Forma cu atribut funcționează la fel:

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

O variantă cu regulă at învelește utilitarele selectate în acea regulă at:

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

Variantele personalizate se combină cu cele integrate — sm:hocus:bg-blue-500 imbrică selectorul hocus în interogarea media sm. Pentru cazuri mai complexe, folosiți forma cu bloc, unde @slot indică locul în care sunt inserate declarațiile utilitarului:

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

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

@layer

@layer controlează ordinea cascadei folosind straturile native de cascadă CSS. O instrucțiune simplă @layer declară ordinea straturilor; straturile ulterioare au prioritate, indiferent de specificitatea selectorului. Ordinea canonică a Tailwind este:

@layer theme, base, components, utilities;

Acesta este exact aranjamentul configurat intern de @import "tailwindcss". Puteți declara propria ordine sau o puteți împărți în mai multe instrucțiuni (@layer reset, base; apoi @layer components, utilities;) și puteți atribui reguli unui strat cu nume folosind un bloc:

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

Adăugarea stilurilor de bază prin @layer base le menține sub components și utilities, astfel încât o clasă utilitară suprascrie întotdeauna valorile implicite ale elementului. Același lucru este valabil pentru @layer components { … }, destinat claselor de componente care trebuie să rămână sub utilitare. Straturile anonime și modificatorii layer() pentru @import sunt prezentați în Importuri.

Pașii următori

• Temă — @theme tokenuri și funcțiile temei.
• Importuri — @import, module virtuale și modificatori layer().
• Pluginuri — directiva @plugin și API pluginului.
• @source — controlați fișierele și clasele scanate.