Uvozi in navidezni moduli

TailwindPHP pred prevajanjem razreši pravila @import. Uvozi lahko kažejo na vgrajene navidezne module (tailwindcss in podobne), na datoteke na disku prek možnosti importPaths ali na vsebino, ki jo vrne razreševalnik po meri.

Navidezni moduli

@import "tailwindcss" je vstopna točka za večino projektov. Razširi se v spodnje štiri vrstice — deklaracijo vrstnega reda plasti in tri poduvoze, od katerih je vsak dodeljen svoji plasti kaskade:

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

Vsak poduvoz je sam po sebi navidezni modul, ki ga lahko uvozite samostojno. Na voljo so naslednji navidezni moduli:

Uvoz posameznih delov vam omogoča, da izpustite Preflight ali spremenite vrstni red plasti (glejte spodaj).

Animacije z tw-animate-css

tw-animate-css je animacijska knjižnica TailwindCSS v4 — zamenjava za tailwindcss-animate, ki jo lahko uporabite neposredno. Na voljo je kot vgrajeni navidezni modul, zato uvoz skupaj s plastjo pripomočkov omogoči, da se razredi za animacije vstopa in izstopa prevedejo kot vsi drugi pripomočki:

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

Animacijski pripomočki pokrivajo:

• Vstop / izstop — animate-in, animate-out
• Pojavljanje — fade-in, fade-out
• Povečava — zoom-in, zoom-out
• Vrtenje — spin-in, spin-out
• Zameglitev — blur-in, blur-out
• Drsenje — slide-in-from-top / -bottom / -left / -right in ustrezni slide-out-to-* ter različici -start / -end, ki upoštevata RTL
• Čas — duration-*, delay-*, repeat-1 / repeat-infinite, direction-normal / -reverse / -alternate in fill-mode-none / -forwards / -backwards / -both
• Stanje predvajanja — running, paused
• Animacije komponent — accordion-down / accordion-up, collapsible-down / collapsible-up in caret-blink

Ti razredi se tako kot drugi pripomočki združujejo z različicami Tailwind, zato so primerni za vzorce pogovornih oken in spustnih menijev shadcn/ui.

Možnost importPaths

Če želite @import razreševati glede na datotečni sistem, v obliki polja za generate() podajte importPaths. Sprejema posamezno pot, imenik ali polje enega oziroma drugega.

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

Vgnezdeni uvozi

Uvozi v naloženi datoteki se razrešijo glede na to datoteko. Če /path/to/styles.css vsebuje @import "./components/buttons.css", se pot razreši glede na /path/to/:

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

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

Odstranjevanje dvojnikov

Če isto datoteko ali navidezni modul uvozite večkrat, se po prvem uvozu ne zgodi nič — ponovljene vrstice @import "tailwindcss" ali dve datoteki, ki obe uvažata isti del, se samodejno odstranijo kot dvojniki. S tem se preprečijo tudi krožni uvozi.

Razreševalnik po meri

Za navidezne datotečne sisteme, zbirke podatkov ali kateri koli vir, ki ni datotečni sistem, kot importPaths podajte klicno vrednost. Prejme URI uvoza in osnovni imenik, glede na katerega se uvoz razrešuje, ter vrne CSS ali 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
    },
]);

Ko je $uri enak null (prvi klic, tudi z argumentom null), vrnite vstopni CSS. Za kateri koli drug URI vrnite vsebino njegovega CSS ali null, da se uporabi iskanje po datotečnem sistemu; če ničesar ne najde, se uvoz tiho preskoči.

Preflight

Preflight je osnovna ponastavitev s stališči vtičnika Tailwind, zgrajena na vrhu modern-normalize. Zgladi razlike med brskalniki, da se pripomočki vedejo predvidljivo. Med drugim odstrani privzete zunanje odmike, odstrani sloge naslovov in seznamov, nastavi prikaz slik na ravni bloka, ponastavi sloge obrob, tako da obrobo riše samo border-width, in omogoči gumbom, da podedujejo pisave.

Preflight je vključen v @import "tailwindcss" — če uvozite celoten sveženj, ga že imate:

use TailwindPHP\tw;

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

Razširitev Preflight

Dodajte lastne osnovne sloge nad Preflight z @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; }
        }
    ',
]);

Izklop Preflight

Pri vključevanju v obstoječi projekt uvozite samo potrebne dele in izpustite vrstico za 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);
    ',
]);

Modifikatorji uvoza

Pri ločenem uvažanju datotek Tailwind dodajte modifikatorje uvozom, na katere vplivajo:

/* 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čni uvozi

@import "…" reference naloži datoteko samo zaradi njenih definicij: uporabite lahko vrednosti @theme ter definicije @utility in @custom-variant v njej, vendar datoteka ne ustvari lastnega CSS. To je enakovredno ovijanju vsebine datoteke v @media reference { … }, kar lahko zapišete tudi neposredno:

@import "tailwindcss/utilities.css";

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

bg-brand se nato prevede v background-color: var(--color-brand, #f00); in ne ustvari nobene deklaracije --color-brand.

Dve omejitvi v trenutni izdaji (#14):

• Referenčne uvoze in bloke @media reference postavite za @import za tailwindcss ali tailwindcss/utilities.css. Če jih postavite prednje, bo celoten izhod prazen.
• reference še ne vpliva na vgrajene navidezne module (@import "tailwindcss" reference;): tema, Preflight in pripomočki se še vedno ustvarijo.

Nadaljujte z razdelkom Tema o spremenljivkah teme ali z razdelkom @source o nadzoru nad datotekami, v katerih se iščejo imena razredov.