Importy a virtuální moduly

TailwindPHP před kompilací zpracovává pravidla @import. Importy mohou odkazovat na vestavěné virtuální moduly (tailwindcss a další), na soubory na disku prostřednictvím možnosti importPaths nebo na cokoli, co vrátí vlastní resolver.

Virtuální moduly

@import "tailwindcss" je vstupní bod používaný většinou projektů. Rozbalí se na čtyři řádky níže — deklaraci pořadí vrstev a tři dílčí importy, každý přiřazený ke své vrstvě kaskády:

@layer theme, base, components, utilities;
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css" layer(utilities);

Každý dílčí import je samostatný virtuální modul, který lze importovat samostatně. Dostupné virtuální moduly:

Samostatným importem jednotlivých částí můžete vynechat Preflight nebo změnit pořadí vrstev (viz níže).

Animace pomocí tw-animate-css

tw-animate-css je animační knihovna TailwindCSS v4 — přímá náhrada za tailwindcss-animate. Je součástí vestavěného virtuálního modulu; importováním spolu s vrstvou utilit se proto její třídy pro animace při vstupu a odchodu kompilují stejně jako jakékoli jiné utility:

@import "tw-animate-css";
@import "tailwindcss/utilities.css";

Animační utility zahrnují:

• Vstup / odchod — animate-in, animate-out
• Zeslabení — fade-in, fade-out
• Přiblížení — zoom-in, zoom-out
• Otáčení — spin-in, spin-out
• Rozostření — blur-in, blur-out
• Posunutí — slide-in-from-top / -bottom / -left / -right a odpovídající slide-out-to-*, plus varianty -start / -end pro jazyky se směrem zprava doleva
• Časování — duration-*, delay-*, repeat-1 / repeat-infinite, direction-normal / -reverse / -alternate a fill-mode-none / -forwards / -backwards / -both
• Stav přehrávání — running, paused
• Animace komponent — accordion-down / accordion-up, collapsible-down / collapsible-up a caret-blink

Tyto třídy lze stejně jako jiné utility kombinovat s variantami Tailwind, takže se hodí přímo pro vzory dialogových oken a rozbalovacích nabídek shadcn/ui.

Možnost importPaths

Chcete-li @import vyhledávat v souborovém systému, předejte importPaths v poli generate(). Přijímá cestu k souboru, adresář nebo pole obojího.

use TailwindPHP\tw;

// Single file
$css = tw::generate([
    'content'     => '<div class="flex btn">Hello</div>',
    'importPaths' => '/path/to/styles.css',
]);

// Directory (loads all .css files alphabetically)
$css = tw::generate([
    'content'     => '<div class="flex btn">Hello</div>',
    'importPaths' => '/path/to/css/',
]);

// Multiple paths — files and directories
$css = tw::generate([
    'content'     => '<div class="flex btn card">Hello</div>',
    'importPaths' => [
        '/path/to/base.css',
        '/path/to/components/',
    ],
]);

// Combine with inline css
$css = tw::generate([
    'content'     => '<div class="flex btn custom">Hello</div>',
    'css'         => '.custom { color: red; }',
    'importPaths' => '/path/to/styles.css',
]);

Vnořené importy

Importy uvnitř načteného souboru se řeší vzhledem k tomuto souboru. Pokud /path/to/styles.css obsahuje @import "./components/buttons.css", cesta se vyhodnotí vzhledem k /path/to/:

/* /path/to/styles.css */
@import "tailwindcss";
@import "./components/buttons.css";
@import "./components/cards.css";

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

Odstranění duplicit

Opakovaný import téhož souboru nebo virtuálního modulu se po prvním načtení ignoruje — duplicitní řádky @import "tailwindcss" i dva soubory importující stejnou část se automaticky odstraní. Zároveň se tím předchází kruhovým importům.

Vlastní resolver

Pro virtuální souborové systémy, databáze nebo jakýkoli zdroj mimo souborový systém předejte jako importPaths volatelnou funkci. Dostane URI importu a základní adresář, vůči němuž se import řeší, a vrátí CSS nebo null:

use TailwindPHP\tw;

$css = tw::generate([
    'content'     => '<div class="flex virtual-class">Hello</div>',
    'importPaths' => function (?string $uri, ?string $fromFile): ?string {
        if ($uri === null) {
            // Entry CSS — returned when no file is supplied
            return '@import "tailwindcss"; @import "custom.css";';
        }
        if ($uri === 'custom.css') {
            return '.virtual-class { color: purple; }';
        }
        return null; // Unknown imports are silently skipped
    },
]);

Když je $uri rovno null (při prvním volání, také s argumentem null), vraťte vstupní CSS. U jakéhokoli jiného URI vraťte jeho obsah CSS, nebo null pro návrat k vyhledávání v souborovém systému, které import tiše přeskočí, pokud nic nenajde.

Preflight

Preflight je svébytný základní reset od Tailwind, postavený na modern-normalize. Vyhlazuje rozdíly mezi prohlížeči, aby utility fungovaly předvídatelně. Mimo jiné odstraňuje výchozí okraje, ruší stylování nadpisů a seznamů, nastavuje obrázky jako blokové prvky, resetuje styly okrajů, takže okraj vykresluje pouze border-width, a umožňuje tlačítkům dědit písmo.

Preflight je součástí @import "tailwindcss" — pokud importujete celý balíček, už ho máte:

use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'css'     => '@import "tailwindcss";',
]);

Rozšíření Preflight

Přidejte vlastní základní styly nad Preflight pomocí @layer base:

use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<article><h1>Title</h1><p>Content</p></article>',
    'css'     => '
        @import "tailwindcss";
        @layer base {
            h1 { font-size: var(--text-2xl); }
            h2 { font-size: var(--text-xl); }
            a  { color: var(--color-blue-600); text-decoration-line: underline; }
        }
    ',
]);

Zakázání Preflight

Při začleňování do existujícího projektu importujte jen potřebné části a vynechte řádek Preflight:

use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'css'     => '
        @layer theme, base, components, utilities;
        @import "tailwindcss/theme.css" layer(theme);
        @import "tailwindcss/utilities.css" layer(utilities);
    ',
]);

Modifikátory importu

Při samostatném importu souborů Tailwind přiřaďte modifikátory k importům, kterých se týkají:

/* Assign the import to a cascade layer */
@import "tailwindcss/utilities.css" layer(utilities);

/* prefix affects both theme variables and utilities */
@import "tailwindcss/theme.css" layer(theme) prefix(tw);
@import "tailwindcss/utilities.css" layer(utilities) prefix(tw);

/* important affects utilities */
@import "tailwindcss/utilities.css" layer(utilities) important;

/* theme(static) or theme(inline) affects theme variables */
@import "tailwindcss/theme.css" layer(theme) theme(static);

/* theme(reference): utilities use the variables with a fallback, no :root block */
@import "tailwindcss/theme.css" layer(theme) theme(reference);

Referenční importy

@import "…" reference načte soubor pouze kvůli jeho definicím: lze použít hodnoty @theme, @utility a definice @custom-variant v něm, ale soubor sám nevygeneruje žádné CSS. Je to stejné, jako kdybyste obsah souboru obalili do @media reference { … }, což můžete zapsat i přímo:

@import "tailwindcss/utilities.css";

@media reference {
    @theme {
        --color-brand: #f00;
    }
}

bg-brand se pak zkompiluje na background-color: var(--color-brand, #f00); a žádná deklarace --color-brand se nevygeneruje.

Dvě omezení aktuální verze (#14):

• Referenční importy a bloky @media reference umístěte za @import tailwindcss nebo tailwindcss/utilities.css. Pokud je umístíte před něj, celý výstup bude prázdný.
• reference na vestavěných virtuálních modulech (@import "tailwindcss" reference;) zatím nemá žádný účinek: téma, Preflight i utility se stále generují.

Pokračujte tématem Theme, kde najdete proměnné tématu, nebo direktivou @source, která určuje, které soubory se prohledávají kvůli názvům tříd.