Direktivy

Direktivy jsou pravidla at-rule s předponou @, která zapisujete do vstupního CSS, abyste skládali, rozšiřovali a řadili výstup Tailwind. Tato stránka se věnuje direktivám @apply, @utility, @variant, @custom-variant a @layer. Direktivu @theme popisuje část Téma, @plugin část Pluginy a @source část @source.

@apply

@apply vkládá deklarace existujících utilit do vašeho selektoru. Umožňuje připojit styly utilit k sémantické třídě, a to i ve vnořených selektorech a mediálních dotazech.

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

Varianty fungují v seznamu @apply — @apply bg-blue-500 hover:bg-blue-600; rozbalí stav :hover a responzivní předpony jako @apply px-4 md:px-6 lg:px-8; vytvoří odpovídající pravidla @media. Respektuje se také modifikátor důležitosti (@apply !flex;). Podporovány jsou i vnořené selektory, takže pravidlo jako .card { h2 { @apply text-xl font-bold; } } použije utility na vnořený prvek h2.

@apply je příkaz: @apply px-4 { … } s tělem vyvolá chybu. @apply obsahující pouze pomlčkové identifikátory (@apply --my-mixin;) je mixin CSS z návrhu mixinů CSS, nikoli seznam utilit, takže ho TailwindPHP nerozpozná; uvedení mixinu a utilit v témže @apply vyvolá chybu (You cannot use @apply with both mixins and utilities…). Pravidla mixinu se nyní z výstupu zahazují, místo aby se předávala dál (#12).

@utility

@utility registruje vlastní utilitu, která se zapojuje do enginu Tailwind — řadí se do vrstvy utilities a přijímá varianty stejně jako vestavěné utility. Statická utilita má pevně dané tělo:

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

Protože jde o skutečnou utilitu, varianty se automaticky skládají (hover:content-auto, md:content-auto). Tělo může samo používat @apply a vnořené selektory:

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

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

Funkční utilita používá v názvu příponu -* a načítá odpovídající hodnotu pomocí --value():

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

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

--value() postupně ověřuje hodnotu kandidáta vůči jednotlivým zdrojům: obor názvů tématu (--gutter-*), libovolná hodnota s datovým typem ([length]) nebo samotný typ hodnoty (integer, number, percentage, ratio). Deklarace, jejíž --value() se nepodaří rozpoznat, se zahodí, takže řada deklarací tvoří záložní řetězec:

--modifier() rozpoznává část za / stejným způsobem: obsahuje-li tělo line-height: --modifier(integer);, gutter-4/7 také vygeneruje line-height: 7. Názvy utilit se řídí pravidly TailwindCSS v4.3.3: nejvýše jeden /, % pouze na konci za číslicí a tečky pouze mezi číslicemi.

@variant

@variant použije variantu na deklarace uvnitř vašeho vlastního CSS, aniž by definovala utilitu:

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

Varianty lze skládat (@variant hover:focus), oddělovat čárkami, vnořovat do sebe a uvádět v nich vlastní @custom-variant. Příkaz @variant nejvyšší úrovně bez těla nebo s @slot se kvůli zpětné kompatibilitě považuje za @custom-variant.

@custom-variant

@custom-variant definuje novou variantu, kterou lze připojit jako předponu k libovolné utilitě. Stručný zápis uvádí název varianty a selektor nebo pravidlo at-rule v závorkách.

Varianta se seznamem selektorů používá & pro prvek:

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

hocus:bg-blue-500 pak vytvoří pravidla :hover i :focus. Stejně funguje i zápis s atributem:

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

Varianta s pravidlem at-rule zabalí odpovídající utility do tohoto pravidla:

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

Vlastní varianty lze skládat s vestavěnými — sm:hocus:bg-blue-500 vnoří selektor hocus do mediálního dotazu sm. Složitější případy řešte blokovou formou, kde @slot označuje místo vložení deklarací utility:

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

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

@layer

@layer řídí pořadí kaskády pomocí nativních vrstev kaskády CSS. Samostatný příkaz @layer deklaruje pořadí vrstev; pozdější vrstvy mají přednost bez ohledu na specifičnost selektoru. Kanonické pořadí Tailwind je:

@layer theme, base, components, utilities;

Přesně toto @import "tailwindcss" nastavuje interně. Můžete deklarovat vlastní pořadí nebo je rozdělit do více příkazů (@layer reset, base; a poté @layer components, utilities;) a přiřadit pravidla do pojmenované vrstvy 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; }
    }
');

Přidáním základních stylů pomocí @layer base je zařadíte pod components a utilities, takže třída utility vždy přepíše výchozí styly prvků. Totéž platí pro @layer components { … } u tříd komponent, které mají být pod utilitami. Anonymní vrstvy a modifikátory layer() na @import popisuje část Importy.

Další kroky

• Téma — tokeny @theme a funkce tématu.
• Importy — @import, virtuální moduly a modifikátory layer().
• Pluginy — direktiva @plugin a rozhraní pluginu API.
• @source — určuje, které soubory a třídy se prohledávají.