Імпорти та віртуальні модулі

Переглянути як Markdown Редагувати на GitHub Документація для 3843abd

TailwindPHP розв’язує правила @import до компіляції. Імпорти можуть указувати на вбудовані віртуальні модулі (tailwindcss тощо), файли на диску через параметр importPaths або будь-який ресурс, який повертає власний розв’язувач.

Віртуальні модулі

@import "tailwindcss" — точка входу, яку використовує більшість проєктів. Вона розгортається в наведені нижче чотири рядки: оголошення порядку шарів і три підімпорти, кожен із яких призначений своєму каскадному шару:

CSS

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

Кожен підімпорт — це окремий віртуальний модуль, який можна імпортувати самостійно. Доступні такі віртуальні модулі:

Модуль	Вміст
`tailwindcss`	Повний набір: тема + Preflight + утиліти.
`tailwindcss/theme.css`	Лише змінні теми (кольори, базовий інтервал, контрольні точки тощо).
`tailwindcss/preflight.css`	Базове скидання стилів Preflight.
`tailwindcss/utilities.css`	Шар утиліт.
`tw-animate-css`	Утиліти анімації `tw-animate-css`.

Імпортуючи частини окремо, можна пропустити Preflight або змінити порядок шарів (див. нижче).

Анімації з tw-animate-css

tw-animate-css — бібліотека анімацій TailwindCSS v4, яку можна безпосередньо підставити замість tailwindcss-animate. Вона постачається як вбудований віртуальний модуль, тож імпорт разом із шаром утиліт дає змогу компілювати класи анімацій появи й зникнення, як і будь-які інші утиліти:

CSS

@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-*, а також варіанти -start / -end з підтримкою RTL
Часові параметри — 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(). Він приймає один шлях, каталог або масив із них.

PHP

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/:

CSS

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

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

Усунення дублікатів

Повторне імпортування того самого файлу або віртуального модуля після першого разу нічого не робить: повторні рядки @import "tailwindcss" або два файли, що імпортують ту саму частину, автоматично усуваються як дублікати. Це також захищає від циклічних імпортів.

Власний розв’язувач

Для віртуальних файлових систем, баз даних або будь-якого джерела поза файловою системою передайте викликуваний об’єкт як importPaths. Він отримує URI імпорту та базовий каталог, відносно якого розв’язується імпорт, і повертає CSS або null:

PHP

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. Воно усуває розбіжності між браузерами, щоб утиліти працювали передбачувано. Зокрема, Preflight прибирає стандартні зовнішні відступи, скидає стилі заголовків і списків, задає зображенням блочно-рівневий режим, скидає стилі рамок, щоб рамку малював лише border-width, і налаштовує кнопки успадковувати шрифти.

Preflight входить до складу @import "tailwindcss" — якщо ви імпортуєте повний набір, він уже доступний:

PHP

use TailwindPHP\tw;

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

Розширення Preflight

Додайте власні базові стилі поверх Preflight за допомогою @layer base:

PHP

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:

PHP

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 окремо, модифікатори вказуються в імпортах, на які вони впливають:

CSS

/* 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 { … }, що також можна записати безпосередньо:

CSS

@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, щоб керувати файлами, у яких виконується пошук назв класів.