Importy a virtuálne moduly

TailwindPHP pred kompiláciou rieši pravidlá @import. Importy môžu odkazovať na vstavané virtuálne moduly (tailwindcss a ďalšie), na súbory na disku prostredníctvom možnosti importPaths alebo na ľubovoľné výstupy vlastného resolvera.

Virtuálne moduly

@import "tailwindcss" je vstupný bod, ktorý používa väčšina projektov. Rozbalí sa na štyri riadky uvedené nižšie — deklaráciu poradia vrstiev a tri podimporty, každý priradený k vlastnej vrstve 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ý podimport je samostatný virtuálny modul, ktorý môžete importovať aj nezávisle. K dispozícii sú tieto virtuálne moduly:

Samostatný import jednotlivých častí vám umožní vynechať Preflight alebo zmeniť poradie vrstiev (pozrite nižšie).

Animácie pomocou tw-animate-css

tw-animate-css je knižnica animácií TailwindCSS v4 — priama náhrada za tailwindcss-animate. Je súčasťou vstavaného virtuálneho modulu, takže pri importe spolu s vrstvou utilít sa jej triedy animácií vstupu a výstupu kompilujú ako akákoľvek iná utilita:

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

Animačné utility pokrývajú:

• Vstup / výstup — animate-in, animate-out
• Zoslabenie — fade-in, fade-out
• Priblíženie — zoom-in, zoom-out
• Otáčanie — spin-in, spin-out
• Rozmazanie — blur-in, blur-out
• Posúvanie — slide-in-from-top / -bottom / -left / -right a zodpovedajúce slide-out-to-*, ako aj varianty -start / -end prispôsobené RTL
• Časovanie — duration-*, delay-*, repeat-1 / repeat-infinite, direction-normal / -reverse / -alternate a fill-mode-none / -forwards / -backwards / -both
• Stav prehrávania — running, paused
• Animácie komponentov — accordion-down / accordion-up, collapsible-down / collapsible-up a caret-blink

Tieto triedy možno kombinovať s variantmi Tailwind ako každú inú utilitu, vďaka čomu sa hodia do vzorov dialógových okien a rozbaľovacích ponúk shadcn/ui.

Možnosť importPaths

Ak chcete vyriešiť @import voči súborovému systému, odovzdajte importPaths v poli generate(). Prijíma jednu cestu, adresár alebo pole s oboma typmi hodnôt.

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',
]);

Vnorené importy

Importy v načítanom súbore sa vyhodnocujú vzhľadom na tento súbor. Ak /path/to/styles.css obsahuje @import "./components/buttons.css", cesta sa vyhodnotí vzhľadom na /path/to/:

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

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

Odstránenie duplicít

Opakovaný import toho istého súboru alebo virtuálneho modulu po prvom načítaní nič neurobí — opakované riadky @import "tailwindcss" alebo dva súbory, ktoré importujú tú istú čiastkovú časť, sa automaticky zbavia duplicít. Chráni to aj pred kruhovými importmi.

Vlastný resolver

Pri virtuálnych súborových systémoch, databázach alebo akomkoľvek zdroji mimo súborového systému odovzdajte ako importPaths volateľnú funkciu. Dostane URI importu a základný adresár, voči ktorému sa import vyhodnocuje, a vráti CSS alebo 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
    },
]);

Keď je $uri null (pri prvom volaní, aj s druhým argumentom null), vráťte vstupný CSS. Pri každom inom URI vráťte jeho obsah CSS alebo null, aby sa pokračovalo vo vyhľadávaní v súborovom systéme; ak sa nič nenájde, import sa potichu preskočí.

Predbežné nastavenie

Preflight je názorovo vyhranený základný reset Tailwind postavený na modern-normalize. Zmierňuje rozdiely medzi prehliadačmi, aby sa nástroje správali predvídateľne. Okrem iného odstraňuje predvolené okraje, ruší štýly nadpisov a zoznamov, nastavuje obrázky ako blokové prvky, resetuje štýly okrajov, takže okraj vykresľuje iba border-width, a tlačidlám umožňuje dediť písmo.

Preflight je súčasťou @import "tailwindcss" — ak importujete celý balík, už ho máte:

use TailwindPHP\tw;

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

Rozšírenie Preflight

Pridajte vlastné základné štýly nad Preflight pomocou @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; }
        }
    ',
]);

Vypnutie Preflight

Pri integrácii do existujúceho projektu importujte iba potrebné časti a vynechajte riadok 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

Pri samostatnom importe súborov Tailwind sa modifikátory uvádzajú pri importoch, na ktoré sa vzťahujú:

/* 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číta súbor iba kvôli jeho definíciám: možno použiť hodnoty @theme a definície @utility a @custom-variant z tohto súboru, no súbor sám nevygeneruje žiadne CSS. Je to rovnaké, ako keby ste obsah súboru obalili do @media reference { … }, čo môžete zapísať aj priamo:

@import "tailwindcss/utilities.css";

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

bg-brand sa potom skompiluje na background-color: var(--color-brand, #f00); a nevygeneruje sa žiadna deklarácia --color-brand.

Dve obmedzenia aktuálneho vydania (#14):

• Referenčné importy a bloky @media reference umiestnite za @import v tailwindcss alebo tailwindcss/utilities.css. Ak ich umiestnite pred neho, celý výstup bude prázdny.
• reference v zabudovaných virtuálnych moduloch (@import "tailwindcss" reference;) zatiaľ nemá žiadny účinok: téma, Preflight aj nástroje sa stále generujú.

Pokračujte témou Theme, kde nájdete premenné témy, alebo direktívou @source, ktorou určíte, ktoré súbory sa prehľadávajú kvôli názvom tried.