Importok és virtuális modulok

A TailwindPHP fordítás előtt oldja fel a @import szabályait. Az importok hivatkozhatnak beépített virtuális modulokra (például tailwindcss-ra), a lemezen lévő fájlokra a importPaths beállítással, vagy bármire, amit egyéni feloldóval ad vissza.

Virtuális modulok

A @import "tailwindcss" a legtöbb projektben használt belépési pont. Az alábbi négy sorra bontódik: a rétegek sorrendjét deklaráló sorra, valamint a három alimportálásra, mindegyik a saját kaszkádrétegéhez rendelve:

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

Mindegyik alimportálás önálló virtuális modul, amelyet külön is importálhat. Az elérhető virtuális modulok:

A részek külön importálásával kihagyhatja a Preflightot, vagy átrendezheti a rétegeket (lásd lent).

Animációk a tw-animate-css használatával

tw-animate-css egy TailwindCSS v4 animációs könyvtár, amely a tailwindcss-animate közvetlen helyettesítője. Beépített virtuális modulként érkezik, így ha a segédosztályok rétegével együtt importálja, a belépési és kilépési animációs osztályai ugyanúgy lefordulnak, mint bármely más segédosztály:

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

Az animációs segédosztályok többek között az alábbiakat tartalmazzák:

• Belépés / kilépés — animate-in, animate-out
• Elhalványítás — fade-in, fade-out
• Nagyítás — zoom-in, zoom-out
• Forgatás — spin-in, spin-out
• Elmosás — blur-in, blur-out
• Csúsztatás — slide-in-from-top / -bottom / -left / -right és a hozzájuk tartozó slide-out-to-*, valamint RTL-t támogató -start / -end
• Időzítés — duration-*, delay-*, repeat-1 / repeat-infinite, direction-normal / -reverse / -alternate és fill-mode-none / -forwards / -backwards / -both
• Lejátszási állapot — running, paused
• Komponensanimációk — accordion-down / accordion-up, collapsible-down / collapsible-up és caret-blink

Ezek az osztályok más segédosztályokhoz hasonlóan kombinálhatók a Tailwind változatokkal, így közvetlenül használhatók shadcn/ui-féle párbeszédablak- és legördülőmenü-mintákban.

A importPaths beállítás

Ha a @import-t a fájlrendszer alapján szeretné feloldani, adja át a importPaths értéket a generate() tömbös formájában. Egyetlen útvonalat, könyvtárat vagy ezek tömbjét fogadja el.

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

Beágyazott importok

A betöltött fájlban lévő importok feloldása az adott fájlhoz képest történik. Ha a /path/to/styles.css tartalmazza a @import "./components/buttons.css" értéket, az útvonal feloldása a /path/to/ alapján történik:

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

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

Ismétlődések kiszűrése

Ugyanazon fájl vagy virtuális modul többszöri importálása az első után nem eredményez változást: az ismétlődő @import "tailwindcss" sorokat, illetve az ugyanazt a részfájlt importáló fájlokat a rendszer automatikusan deduplikálja. Ez a körkörös importok ellen is véd.

Egyéni feloldó

Virtuális fájlrendszerek, adatbázisok vagy bármilyen nem fájlrendszer-alapú forrás esetén adjon át egy hívható függvényt importPaths-ként. A függvény megkapja az import URI-ját és az alapkönyvtárat, amelyhez képest az importot fel kell oldani, majd CSS-et vagy null-t ad vissza:

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

Ha a $uri értéke null (az első hívás, amelynek második argumentuma is null), adja vissza a belépési CSS-t. Más URI esetén adja vissza annak CSS tartalmát, vagy adja vissza a null értéket, hogy a rendszer a fájlrendszerben keressen tovább; ha nem talál semmit, csendben kihagyja az importot.

Preflight

A Preflight a Tailwind saját alaphelyzetbe állító stíluscsomagja, amely a modern-normalize alapjaira épül. Egységesíti a böngészők közötti eltéréseket, hogy a segédosztályok kiszámíthatóan működjenek. Többek között eltávolítja az alapértelmezett margókat, megszünteti a címsorok és listák alapstílusait, blokk szintűvé teszi a képeket, alaphelyzetbe állítja a keretstílusokat, így csak a border-width rajzol keretet, a gombok pedig öröklik a betűtípust.

A Preflight a @import "tailwindcss" része, ezért ha a teljes csomagot importálja, már használja is:

use TailwindPHP\tw;

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

A Preflight kiterjesztése

Saját alapstílusokat is hozzáadhat a Preflighthoz a @layer base segítségével:

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

A Preflight letiltása

Meglévő projektbe való integráláskor csak a szükséges részeket importálja, és hagyja ki a Preflight sort:

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

Importmódosítók

Ha a Tailwind fájljait külön-külön importálja, a módosítókat az általuk érintett importokhoz kell megadni:

/* 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);

Referenciaimportok

A @import "…" reference csak a definíciók betöltésére szolgál: az abban lévő @theme értékek, @utility-ok és @custom-variant definíciók használhatók, de a fájl nem bocsát ki saját CSS-ot. Ez megfelel annak, mintha a fájl tartalmát @media reference { … }-ba csomagolná, amit közvetlenül is megírhat:

@import "tailwindcss/utilities.css";

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

A bg-brand így background-color: var(--color-brand, #f00);-ra fordul, és --color-brand deklaráció nem jön létre.

A jelenlegi kiadás két korlátozása (#14):

• A referenciaimportokat és a @media reference blokkokat a @import után helyezze el, a tailwindcss vagy a tailwindcss/utilities.css blokkjában. Ha eléjük kerülnek, a teljes kimenet üres lesz.
• A beépített virtuális modulokon (@import "tailwindcss" reference;) használt reference egyelőre hatástalan: a téma, a Preflight és a segédosztályok továbbra is kibocsátásra kerülnek.

Folytassa a Theme résszel a témaváltozókért, vagy az @source résszel annak szabályozásához, mely fájlokban keresse a rendszer az osztályneveket.