Importy i moduły wirtualne

TailwindPHP rozwiązuje reguły @import przed kompilacją. Importy mogą wskazywać wbudowane moduły wirtualne (tailwindcss i podobne), pliki na dysku za pomocą opcji importPaths albo dowolną wartość zwracaną przez własny resolver.

Moduły wirtualne

@import "tailwindcss" to punkt wejścia używany w większości projektów. Rozwija się do czterech poniższych wierszy — deklaracji kolejności warstw i trzech importów podrzędnych, z których każdy jest przypisany do swojej warstwy kaskady:

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

Każdy import podrzędny jest osobnym modułem wirtualnym, który można importować samodzielnie. Dostępne moduły wirtualne:

Osobny import poszczególnych części pozwala pominąć Preflight lub zmienić kolejność warstw (zobacz poniżej).

Animacje z tw-animate-css

tw-animate-css to biblioteka animacji TailwindCSS v4 — gotowy zamiennik tailwindcss-animate. Jest wbudowana jako moduł wirtualny, więc importowanie jej wraz z warstwą utilities pozwala kompilować klasy animacji wejścia i wyjścia tak jak każde inne narzędzie:

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

Narzędzia animacji obejmują:

• Wejście / wyjście — animate-in, animate-out
• Zanikanie — fade-in, fade-out
• Powiększanie — zoom-in, zoom-out
• Obrót — spin-in, spin-out
• Rozmycie — blur-in, blur-out
• Przesunięcie — slide-in-from-top / -bottom / -left / -right i odpowiadające im slide-out-to-*, a także uwzględniające RTL -start / -end
• Czas — duration-*, delay-*, repeat-1 / repeat-infinite, direction-normal / -reverse / -alternate oraz fill-mode-none / -forwards / -backwards / -both
• Stan odtwarzania — running, paused
• Animacje komponentów — accordion-down / accordion-up, collapsible-down / collapsible-up i caret-blink

Te klasy można łączyć z wariantami Tailwind jak każde inne narzędzie, dzięki czemu idealnie pasują do wzorców dialogów i list rozwijanych shadcn/ui.

Opcja importPaths

Aby rozwiązywać @import względem systemu plików, przekaż importPaths w tablicowej formie generate(). Akceptuje pojedynczą ścieżkę, katalog lub tablicę takich elementów.

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

Zagnieżdżone importy

Importy w załadowanym pliku są rozwiązywane względem tego pliku. Jeśli /path/to/styles.css zawiera @import "./components/buttons.css", ścieżka jest rozwiązywana względem /path/to/:

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

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

Usuwanie duplikatów

Po pierwszym zaimportowaniu kolejne importy tego samego pliku lub modułu wirtualnego nic nie robią — powtórzone wiersze @import "tailwindcss" lub dwa pliki importujące tę samą część są automatycznie deduplikowane. Zapobiega to także importom cyklicznym.

Własny resolver

W przypadku wirtualnych systemów plików, baz danych lub innych źródeł spoza systemu plików przekaż funkcję jako importPaths. Otrzymuje ona URI importu i katalog bazowy, względem którego rozwiązywany jest import, a następnie zwraca CSS lub 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
    },
]);

Gdy $uri ma wartość null (przy pierwszym wywołaniu, także z argumentem null), zwróć wejściowy CSS. Dla każdego innego URI zwróć jego zawartość CSS albo null, aby przejść do wyszukiwania w systemie plików, które po cichu pomija import, jeśli niczego nie znajdzie.

Preflight

Preflight to stanowczy bazowy reset Tailwind, oparty na modern-normalize. Wyrównuje niespójności między przeglądarkami, aby narzędzia działały przewidywalnie. Między innymi usuwa domyślne marginesy, usuwa style nagłówków i list, wyświetla obrazy jako elementy blokowe, resetuje style obramowań tak, aby samo border-width rysowało obramowanie, i sprawia, że przyciski dziedziczą krój pisma.

Preflight jest częścią @import "tailwindcss" — jeśli importujesz pełny pakiet, masz go już dostępnego:

use TailwindPHP\tw;

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

Rozszerzanie Preflight

Dodaj własne style bazowe na wierzchu Preflight za pomocą @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; }
        }
    ',
]);

Wyłączanie Preflight

Podczas integracji z istniejącym projektem importuj tylko potrzebne części i pomiń wiersz 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);
    ',
]);

Modyfikatory importu

Podczas osobnego importowania plików Tailwind modyfikatory należy dodawać do importów, na które mają wpływać:

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

Importy referencyjne

@import "…" reference ładuje plik wyłącznie w celu udostępnienia definicji: dostępne są wartości @theme oraz definicje @utility i @custom-variant, ale plik nie emituje własnego CSS. Działa to tak samo jak umieszczenie zawartości pliku wewnątrz @media reference { … }, co również można zapisać bezpośrednio:

@import "tailwindcss/utilities.css";

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

bg-brand kompiluje się następnie do background-color: var(--color-brand, #f00); i nie jest emitowana żadna deklaracja --color-brand.

Dwa ograniczenia bieżącej wersji (#14):

• Umieść importy referencyjne i bloki @media reference za @import elementu tailwindcss lub tailwindcss/utilities.css. Umieszczenie ich przed nim powoduje pusty wynik.
• reference wbudowanych modułów wirtualnych (@import "tailwindcss" reference;) jeszcze nie działa: motyw, Preflight i utilities nadal są emitowane.

Przejdź dalej do sekcji Motyw, aby poznać zmienne motywu, lub do @source, aby określić, które pliki są skanowane w poszukiwaniu nazw klas.