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

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 с заданными принципами, построенный на основе 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 и утилиты всё равно выводятся.

Продолжите с разделом Тема о переменных темы или @source, чтобы настроить сканирование файлов на имена классов.