Импортиране и виртуални модули

TailwindPHP разрешава правилата @import преди компилация. Импортите могат да сочат към вградени виртуални модули (tailwindcss и други), към файлове на диска чрез опцията importPaths или към резултат, върнат от персонализиран разрешител.

Виртуални модули

@import "tailwindcss" е входната точка, която използват повечето проекти. Тя се разгръща до четирите реда по-долу — декларацията за реда на слоевете и трите подимпорта, всеки зададен към своя каскаден слой:

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

Можете да импортирате всеки подимпорт самостоятелно, тъй като самият той е виртуален модул. Наличните виртуални модули са:

Импортирането на частите поотделно позволява да пропуснете Preflight или да промените реда на слоевете (вижте по-долу).

Анимации с tw-animate-css

tw-animate-css е библиотека с анимации TailwindCSS v4 — директен заместител на tailwindcss-animate. Тя се предлага като вграден виртуален модул, така че импортирането ѝ заедно със слоя помощни класове позволява класовете за анимации при влизане и излизане да се компилират като всеки друг помощен клас:

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

Помощните класове за анимации включват:

• Влизане / излизане — animate-in, animate-out
• Постепенно появяване — fade-in, fade-out
• Мащабиране — zoom-in, zoom-out
• Завъртане — spin-in, spin-out
• Замъгляване — blur-in, blur-out
• Плъзгане — slide-in-from-top / -bottom / -left / -right и съответните slide-out-to-*, както и съобразени с RTL -start / -end
• Време — duration-*, delay-*, repeat-1 / repeat-infinite, direction-normal / -reverse / -alternate и fill-mode-none / -forwards / -backwards / -both
• Състояние на възпроизвеждане — running, paused
• Анимации на компоненти — accordion-down / accordion-up, collapsible-down / collapsible-up и caret-blink

Тези класове се комбинират с варианти Tailwind като всеки друг помощен клас, което ги прави подходящи за шаблони на диалогови прозорци и падащи менюта shadcn/ui.

Опцията importPaths

За да разрешавате @import спрямо файловата система, подайте importPaths във формата с масив на generate(). Приема единичен път, директория или масив от такива.

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

Вложени импорти

Импортите във файл се разрешават спрямо местоположението на този файл. Ако /path/to/styles.css съдържа @import "./components/buttons.css", пътят се разрешава спрямо /path/to/:

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

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

Премахване на дубликати

Повторното импортиране на същия файл или виртуален модул не прави нищо след първия път — повтарящи се редове @import "tailwindcss" или два файла, които импортират една и съща част, се премахват автоматично. Това също предотвратява циклични импорти.

Персонализиран разрешител

За виртуални файлови системи, бази данни или други източници, различни от файловата система, подайте извикваем обект като importPaths. Той получава URI адреса на импорта и базовата директория, спрямо която се разрешава импортът, и връща CSS или 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
    },
]);

Когато $uri е null (при първото извикване, също и с аргумент null), върнете входния CSS. За всеки друг URI върнете съдържанието му CSS или null, за да се премине към търсене във файловата система. Ако нищо не бъде намерено, импортът се пропуска без предупреждение.

Предварителна проверка

Preflight е зададеният от Tailwind базов reset, изграден върху modern-normalize. Той изглажда несъответствията между браузърите, така че помощните класове да се държат предвидимо. Наред с други неща премахва стандартните отстъпи, премахва стиловете на заглавията и списъците, прави изображенията блокови елементи, нулира стиловете на рамките, така че само border-width да рисува рамка, и позволява на бутоните да наследяват шрифтовете.

Preflight е включен в @import "tailwindcss" — ако импортирате целия пакет, вече го имате:

use TailwindPHP\tw;

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

Разширяване на Preflight

Добавете свои базови стилове върху Preflight с @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; }
        }
    ',
]);

Изключване на Preflight

Когато интегрирате в съществуващ проект, импортирайте само необходимите части и пропуснете реда за 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);
    ',
]);

Модификатори за импортиране

Когато импортирате файловете на Tailwind поотделно, поставяйте модификаторите върху импорта, към който се отнасят:

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

Импорти за справка

@import "…" reference зарежда файл само заради дефинициите в него: стойностите @theme, дефинициите @utility и @custom-variant в него могат да се използват, но самият файл не генерира CSS. Това е равносилно на обвиването на съдържанието на файла в @media reference { … }, което също можете да напишете директно:

@import "tailwindcss/utilities.css";

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

bg-brand след това се компилира до background-color: var(--color-brand, #f00); и не се генерира декларация --color-brand.

Две ограничения в текущата версия (#14):

• Поставяйте импорти за справка и блокове @media reference след @import на tailwindcss или tailwindcss/utilities.css. Ако ги поставите преди него, целият резултат ще бъде празен.
• reference върху вградените виртуални модули (@import "tailwindcss" reference;) все още няма ефект: темата, Preflight и помощните класове пак се генерират.

Продължете с Theme за променливите на темата или с @source, за да контролирате кои файлове се сканират за имена на класове.