Importer og virtuelle moduler

TailwindPHP finder @import-regler før kompilering. Importer kan pege på indbyggede virtuelle moduler (tailwindcss og lignende), filer på disken via indstillingen importPaths eller hvad som helst, du returnerer fra en brugerdefineret resolver.

Virtuelle moduler

@import "tailwindcss" er det indgangspunkt, som de fleste projekter bruger. Det udvides til de fire linjer nedenfor — erklæringen om lagenes rækkefølge samt de tre underimporter, hver tildelt sit kaskadelag:

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

Hver underimport er selv et virtuelt modul, som du kan importere separat. De tilgængelige virtuelle moduler er:

Hvis du importerer delene enkeltvis, kan du springe Preflight over eller ændre lagenes rækkefølge (se nedenfor).

Animationer med tw-animate-css

tw-animate-css er et TailwindCSS-animationsbibliotek til v4 — en direkte erstatning for tailwindcss-animate. Det leveres som et indbygget virtuelt modul, så når du importerer det sammen med utilities-laget, kompileres dets klasser til ind- og udgangsanimationer som alle andre utilities:

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

Animationsutilities dækker:

• Ind/ud — animate-in, animate-out
• Indtoning — fade-in, fade-out
• Zoom — zoom-in, zoom-out
• Rotation — spin-in, spin-out
• Sløring — blur-in, blur-out
• Glidning — slide-in-from-top / -bottom / -left / -right og de tilsvarende slide-out-to-* samt RTL-bevidste -start / -end
• Tidsstyring — duration-*, delay-*, repeat-1 / repeat-infinite, direction-normal / -reverse / -alternate og fill-mode-none / -forwards / -backwards / -both
• Afspilningstilstand — running, paused
• Komponentanimationer — accordion-down / accordion-up, collapsible-down / collapsible-up og caret-blink

Disse klasser kan stables med Tailwind-varianter som enhver anden utility, så de passer direkte ind i shadcn/ui-mønstre for dialoger og rullemenuer.

Indstillingen importPaths

For at finde @import i filsystemet skal du angive importPaths i arrayformen af generate(). Den accepterer en enkelt sti, en mappe eller et array med begge dele.

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

Indlejrede importer

Importer i en indlæst fil findes relativt til den fil. Hvis /path/to/styles.css indeholder @import "./components/buttons.css", findes stien relativt til /path/to/:

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

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

Fjernelse af dubletter

Hvis den samme fil eller det samme virtuelle modul importeres mere end én gang, sker der intet efter første gang — gentagne @import "tailwindcss"-linjer eller to filer, der begge importerer samme del, fjernes automatisk som dubletter. Det beskytter også mod cirkulære importer.

Brugerdefineret resolver

Til virtuelle filsystemer, databaser eller andre kilder end filsystemet kan du angive en funktion som importPaths. Den modtager importens URI og basismappen, som importen findes relativt til, og returnerer CSS eller 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
    },
]);

Når $uri er null (det første kald, også med et null som andet argument), skal du returnere indgangens CSS. For enhver anden URI skal du returnere dens indhold som CSS eller null for at falde tilbage på filsøgning. Hvis intet findes, springes importen over uden meddelelse.

Preflight

Preflight er Tailwinds præskriptive grundnulstilling, bygget oven på modern-normalize. Den udjævner forskelle mellem browsere, så hjælpeklasser opfører sig forudsigeligt. Blandt andet fjerner den standardmargener, fjerner standardtypografien fra overskrifter og lister, gør billeder til blokkelementer, nulstiller kantstile, så kun border-width tegner en kant, og lader knapper arve skrifttyper.

Preflight følger med @import "tailwindcss" — hvis du importerer hele pakken, har du den allerede:

use TailwindPHP\tw;

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

Udvidelse af Preflight

Tilføj dine egne grundstile oven på Preflight med @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; }
        }
    ',
]);

Deaktivering af Preflight

Når du integrerer i et eksisterende projekt, skal du kun importere de dele, du har brug for, og udelade Preflight-linjen:

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

Importmodifikatorer

Når du importerer Tailwinds filer enkeltvis, skal modifikatorerne stå på de imports, de påvirker:

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

Referenceimports

@import "…" reference indlæser en fil kun for dens definitioner: @theme-værdier, @utility- og @custom-variant-definitioner i filen kan bruges, men filen udsender ikke selv noget CSS. Det svarer til at omslutte filens indhold i @media reference { … }, hvilket du også kan skrive direkte:

@import "tailwindcss/utilities.css";

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

bg-brand kompileres derefter til background-color: var(--color-brand, #f00);, og der udsendes ingen --color-brand-deklaration.

To begrænsninger i den aktuelle udgave (#14):

• Placér referenceimports og @media reference-blokke efter @import for tailwindcss eller tailwindcss/utilities.css. Hvis de står før, bliver hele outputtet tomt.
• reference på de indbyggede virtuelle moduler (@import "tailwindcss" reference;) har endnu ingen effekt: temaet, Preflight og hjælpeklasserne udsendes stadig.

Fortsæt med Theme for temavariabler eller @source for at styre, hvilke filer der scannes for klassenavne.