Importer och virtuella moduler

TailwindPHP matchar reglerna @import före kompilering. Importer kan peka på inbyggda virtuella moduler (tailwindcss med flera), filer på disk via alternativet importPaths eller valfritt innehåll som returneras av en egen matchare.

Virtuella moduler

@import "tailwindcss" är den startpunkt som används i de flesta projekt. Den expanderas till de fyra raderna nedan – deklarationen av lagerordningen plus tre underimporter, som var och en tilldelas sitt kaskadlager:

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

Varje underimport är i sig en virtuell modul som du kan importera separat. Tillgängliga virtuella moduler:

Om du importerar delarna var för sig kan du hoppa över Preflight eller ändra lagerordningen (se nedan).

Animeringar med tw-animate-css

tw-animate-css är ett TailwindCSS animeringsbibliotek v4 – en direkt ersättning för tailwindcss-animate. Det levereras som en inbyggd virtuell modul, så om du importerar det tillsammans med verktygslagret kompileras dess animeringsklasser för in- och utpassering precis som andra verktyg:

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

Animeringsverktygen omfattar:

• Inpassering / utpassering — animate-in, animate-out
• Toning — fade-in, fade-out
• Zoomning — zoom-in, zoom-out
• Rotation — spin-in, spin-out
• Oskärpa — blur-in, blur-out
• Glidning — slide-in-from-top / -bottom / -left / -right och motsvarande slide-out-to-*, samt RTL-anpassade -start / -end
• Tidsinställning — duration-*, delay-*, repeat-1 / repeat-infinite, direction-normal / -reverse / -alternate och fill-mode-none / -forwards / -backwards / -both
• Uppspelningsläge — running, paused
• Komponentanimeringar — accordion-down / accordion-up, collapsible-down / collapsible-up och caret-blink

Dessa klasser kan kombineras med varianter för Tailwind precis som andra verktyg, vilket gör dem perfekta att använda direkt i mönster för dialogrutor och rullgardinsmenyer shadcn/ui.

Alternativet importPaths

För att matcha @import mot filsystemet anger du importPaths i arrayformatet för generate(). Det godtar en enskild sökväg, en katalog eller en array av dem.

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

Nästlade importer

Importer i en inläst fil matchas relativt till den filen. Om /path/to/styles.css innehåller @import "./components/buttons.css" matchas sökvägen mot /path/to/:

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

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

Dubblettrensning

Om samma fil eller virtuella modul importeras flera gånger görs inget efter den första importen. Upprepade rader med @import "tailwindcss" eller två filer som importerar samma del resulterar automatiskt i en enda import. Det skyddar även mot cirkulära importer.

Egen matchare

För virtuella filsystem, databaser eller andra källor än filsystem anger du en anropbar funktion som importPaths. Den tar emot importens URI och baskatalogen som importen matchas mot och returnerar 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
    },
]);

Om $uri är null (det första anropet, även med null som andra argument) returnerar du ingångsfilen CSS. För andra URI:er returnerar du innehållet i motsvarande CSS eller null för att fortsätta med filsökningen. Importen hoppas då över utan meddelande om ingen fil hittas.

Preflight

Preflight är Tailwinds bestämda grundåterställning, byggd på modern-normalize. Den jämnar ut skillnader mellan webbläsare så att verktygen fungerar förutsägbart. Bland annat tar den bort standardmarginaler, neutraliserar formateringen av rubriker och listor, gör bilder till blockelement, återställer kantlinjer så att enbart border-width ritar en kantlinje och låter knappar ärva teckensnitt.

Preflight ingår i @import "tailwindcss" – om du importerar hela paketet har du redan Preflight:

use TailwindPHP\tw;

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

Utöka Preflight

Lägg till egna grundstilar ovanpå 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; }
        }
    ',
]);

Inaktivera Preflight

När du integrerar i ett befintligt projekt importerar du bara de delar du behöver och utelämnar Preflight-raden:

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

Importmodifierare

När du importerar Tailwinds filer var för sig anger du modifierare på de importer de påverkar:

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

Referensimporter

@import "…" reference läser in en fil enbart för dess definitioner: värden för @theme, definitioner av @utility och @custom-variant i filen kan användas, men filen genererar ingen egen CSS. Det motsvarar att omsluta filens innehåll med @media reference { … }, vilket du också kan skriva direkt:

@import "tailwindcss/utilities.css";

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

bg-brand kompileras då till background-color: var(--color-brand, #f00); utan att någon deklaration av --color-brand genereras.

Två begränsningar i den aktuella versionen (#14):

• Placera referensimporter och block med @media reference efter @import för tailwindcss eller tailwindcss/utilities.css. Om de placeras före blir hela utdatan tom.
• reference på de inbyggda virtuella modulerna (@import "tailwindcss" reference;) har ännu ingen effekt: tema, Preflight och verktyg genereras fortfarande.

Fortsätt till Tema för temavariabler eller @source för att styra vilka filer som genomsöks efter klassnamn.