Перейти до вмісту

Tailwind CSS

Blockstudio має вбудовану підтримку Tailwind CSS v4. Коли її ввімкнено, кожна сторінка сайту компілюється на сервері через TailwindPHP з автоматичним кешуванням на основі файлів. У редакторі блоків комплектний скрипт Tailwind CDN забезпечує попередній перегляд зі змінами під час редагування.

Не потрібні ні крок збірки, ні CLI, ні Node.js.

Як це працює

Blockstudio використовує дві окремі стратегії компіляції залежно від контексту:

Інтерфейс сайту (на сервері)

Під час кожного запиту до інтерфейсу сайту Blockstudio захоплює весь HTML-код сторінки HTML через буфер виводу, витягує всі потенційні класи CSS, компілює лише фактично використані CSS і вставляє результат як вбудований тег <style> перед </head>.

Процес компіляції:

  1. WordPress рендерить весь HTML-код сторінки HTML у буфер виводу
  2. TailwindPHP::extractCandidates() сканує HTML і витягує всі потенційні назви класів CSS (швидкий регулярний вираз, без компіляції)
  3. Кандидати сортуються та хешуються разом із конфігурацією CSS, щоб створити ключ кешу
  4. За влучання в кеш: скомпільований CSS зчитується з диска та вставляється
  5. За промаху кешу: TailwindPHP::generate() компілює CSS, записує його до каталогу кешу та вставляє

Скомпільований CSS вставляється так:

HTML
<style id="blockstudio-tailwind">
  /* compiled CSS */
</style>

Це включає preflight від Tailwind (скидання CSS) і всі відповідні класи утиліт.

Редактор (на клієнті)

У редакторі блоків на клієнті працює комплектний скрипт Tailwind CDN (браузерна збірка Tailwind CSS v4). Він забезпечує миттєвий попередній перегляд під час введення назв класів без запитів до сервера. CDN завантажується лише в редакторі й ніколи не віддається в інтерфейсі сайту.

Коли assets.reset.enabled активний, Blockstudio також відновлює поширені утиліти відображення й позиціювання Tailwind у полотні редактора. Завдяки цьому класи рівня обгортки, як-от flex, grid, absolute, fixed та sticky, не перекриваються правилами обгортки блоків редактора WordPress, тож макети з утилітами більше відповідають інтерфейсу сайту.

Увімкнення Tailwind

Додайте конфігурацію tailwind до blockstudio.json:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "tailwind": {
    "enabled": true
  }
}

Або ввімкніть через фільтр:

PHP
add_filter('blockstudio/settings/tailwind/enabled', '__return_true');

Коли для enabled задано значення true, на кожній сторінці інтерфейсу сайту автоматично компілюватиметься й вставлятиметься Tailwind CSS. Ви можете використовувати класи утиліт Tailwind будь-де: у шаблонах блоків, шаблонах тем, фільтрах the_content або будь-якому HTML, що з’являється у виводі сторінки.

Вивід інтерфейсу сайту

За замовчуванням скомпільований CSS вставляється в рядок, зберігаючи вивід попередніх версій. Сайти з багатьма спільними правилами можуть натомість використовувати таблицю стилів із хешем вмісту:

JSON
{
  "tailwind": {
    "enabled": true,
    "output": "link"
  }
}

"output": "link" виводить наявний файл кешу tailwind/{content-hash}.css як <link rel="stylesheet">. URL змінюється, коли змінюється ідентичність середовища виконання, кандидати, рушій або вхідні дані CSS, тож браузери й периферійні кеші можуть безпечно зберігати старі URL-адреси. Налаштуйте вебсервер або CDN на надсилання заголовка Cache-Control: public, immutable із тривалим строком дії для цієї області кешу.

Типовий корінь кешу є загальнодоступним і розташований у wp-content. Якщо cache.path вказує на приватний абсолютний том, Blockstudio повертається до вбудованого CSS, якщо наявний фільтр blockstudio/files/url не надає загальнодоступний URL для області tailwind:

PHP
add_filter(
    'blockstudio/files/url',
    function (string $url, string $path, string $scope): string {
        if ('tailwind' !== $scope) {
            return $url;
        }

        return 'https://static.example.com/blockstudio/' . basename($path);
    },
    10,
    3
);

Помічники для компонування шаблонів

Blockstudio надає шаблонам PHP той самий вбудований рушій TailwindPHP. Не потрібні копія на рівні теми чи резервна реалізація:

PHP
$classes = bs_tw_merge('px-2 text-sm', 'px-4');
// text-sm px-4

$button = bs_tw_variants([
    'base' => 'inline-flex items-center',
    'variants' => [
        'size' => [
            'sm' => 'h-8 px-3',
            'lg' => 'h-12 px-6',
        ],
    ],
    'defaultVariants' => [
        'size' => 'sm',
    ],
]);

echo $button(['size' => 'lg', 'class' => 'rounded']);

bs_tw_merge() приймає вкладені значення класів і розв’язує конфлікти між утилітами Tailwind. bs_tw_variants() повертає викликаний об’єкт у стилі CVA з підтримкою базових класів, варіантів, типових варіантів, складених варіантів, class і className.

Конфігурація

Tailwind v4 використовує підхід до конфігурації, у якому спочатку задається CSS. Замість файлу конфігурації JavaScript ви записуєте конфігурацію безпосередньо як CSS за допомогою директиви @theme.

JSON
{
  "tailwind": {
    "enabled": true,
    "config": "@theme { --color-primary: #3b82f6; --color-secondary: #10b981; --font-family-heading: 'Inter', sans-serif; }"
  }
}

Значення config — це рядок CSS, який додається після директиви @import "tailwindcss". Тут можна використовувати будь-який коректний синтаксис Tailwind v4 CSS:

JSON
{
  "tailwind": {
    "enabled": true,
    "config": "@theme { --color-brand: oklch(0.7 0.15 200); } @layer base { h1 { font-size: var(--text-4xl); } }"
  }
}

Для багаторядкових конфігурацій зручніше використовувати фільтр:

PHP
add_filter('blockstudio/settings/tailwind/config', function () {
    return <<<CSS
@theme {
    --color-primary: #3b82f6;
    --color-secondary: #10b981;
    --font-family-heading: 'Inter', sans-serif;
    --breakpoint-xs: 30rem;
}

@layer base {
    body {
        font-family: var(--font-family-sans);
    }
}

@layer utilities {
    .btn { @apply px-4 py-2 rounded-lg font-medium; }
    .btn-primary { @apply bg-blue-500 text-white hover:bg-blue-600; }
    .card { @apply bg-white rounded-xl shadow-lg p-6; }
}
CSS;
});

Користувацькі класи утиліт

Щоб визначити повторно використовувані псевдоніми класів, скористайтеся @layer utilities із директивою @apply від Tailwind безпосередньо у рядку конфігурації:

JSON
{
  "tailwind": {
    "enabled": true,
    "config": "@theme { --color-brand: #6366f1; } @layer utilities { .btn { @apply px-4 py-2 rounded-lg font-medium; } .section { @apply py-16 px-4 max-w-7xl mx-auto; } }"
  }
}

Це компілює ці класи разом зі стандартними утилітами Tailwind. Вони працюють і на фронтенді (компіляція на сервері), і в редакторі (попередній перегляд CDN).

Blockstudio зберігає канонічний порядок каскадних шарів Tailwind: theme, base, components, а потім utilities. Це відповідає Tailwind CSS, тож правила в пізніших шарах, як і очікується, можуть перевизначати попередні.

Тип поля Classes

Щоб використовувати класи Tailwind у полі classes блоку з підтримкою автодоповнення, задайте для поля tailwind: true:

JSON
{
  "name": "my-theme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      {
        "id": "classes",
        "type": "classes",
        "label": "Classes",
        "tailwind": true,
        "default": "bg-white text-gray-900"
      }
    ]
  }
}

Коли tailwind має значення true:

  • Поле пропонує варіанти автодоповнення з повного списку класів Tailwind
  • Скрипт Tailwind CDN завантажується в редакторі для інтерактивного попереднього перегляду
  • Класи зберігаються в атрибутах блоку як рядок, розділений пробілами

Використайте значення classes у шаблоні:

PHP
<div class="<?php echo $a['classes']; ?>">
  <!-- block content -->
</div>

Довідник налаштувань

Параметр Тип Типове значення Опис
enabled логічний false Увімкнути компіляцію Tailwind CSS на фронтенді
config рядок "" Рядок конфігурації з пріоритетом Tailwind v4 CSS

Налаштування через JSON

JSON
{
  "tailwind": {
    "enabled": true,
    "config": "@theme { --color-brand: pink; }"
  }
}

Налаштування через фільтри

PHP
add_filter('blockstudio/settings/tailwind/enabled', '__return_true');

add_filter('blockstudio/settings/tailwind/config', function () {
    return '@theme { --color-brand: pink; }';
});

Кешування

Blockstudio використовує спеціальну стратегію кешування, розроблену для утилітарної архітектури Tailwind.

Як працює кеш

Замість хешування всього HTML сторінки (через що кеш скидався б під час кожного запиту через nonce, часові мітки та інший динамічний вміст), Blockstudio вибирає з HTML лише кандидатні класи CSS. Ці кандидати сортуються та хешуються разом із конфігурацією CSS, утворюючи стабільний ключ кешу.

Це означає:

  • Дві сторінки з однаковим набором класів Tailwind використовують той самий кешований файл CSS, навіть якщо їхній HTML зовсім різний
  • Динамічний вміст, як-от nonce, панелі для авторизованих користувачів, кількість коментарів і часові мітки, не скидає кеш
  • Кеш інвалідовується лише тоді, коли змінюється набір класів CSS на сторінці або конфігурація Tailwind

Коли середовище виконання використовує джерело логічного виявлення, вибране джерело та контекст середовища виконання також беруть участь у просторі імен кешу. Останнє успішне значення CSS ізольоване між попередніми переглядами й не може потрапити з одного вибраного джерела до іншого.

Розташування кешу

Файли кешу зберігаються тут:

Код
wp-content/blockstudio/cache/sites/{network-blog}/{runtime-identity}/tailwind/

Налаштований cache.path, поточний ідентифікатор мультисайту та повний ідентифікатор середовища виконання визначають точний префікс. Назви файлів містять хеш MD5: {hash}.css.

Очищення кешу

Видаліть вміст каталогу кешу, щоб примусово виконати повторну компіляцію:

PHP
// Clear all cached Tailwind CSS
Blockstudio\Runtime_Cache::purge('tailwind');

Або через WP-CLI:

Командна оболонка
wp eval "Blockstudio\\Runtime_Cache::purge('tailwind');"

Наступний запит до фронтенду автоматично повторно скомпілює CSS і збереже його в кеші.

Фільтри

blockstudio/tailwind/css

Змініть вхідні дані CSS перед компіляцією. Вхідний рядок CSS починається з @import "tailwindcss";, після якого йде будь-яка конфігурація. Використовуйте цей фільтр, щоб додати директиви CSS, власні правила @layer або імпорти плагінів.

PHP
add_filter('blockstudio/tailwind/css', function (string $css): string {
    // Add a custom utility
    $css .= "\n@utility container-narrow { max-width: 48rem; margin-inline: auto; }";

    return $css;
});

Повний вміст вхідних даних CSS, які компілюються, має такий вигляд:

CSS
/* Base import */
@import 'tailwindcss';

/* Config from settings (if set) */
@theme {
  --color-brand: pink;
}

/* Anything added via the blockstudio/tailwind/css filter */

Буфер виводу

Компіляція Tailwind інтегрується із системою буфера виводу Blockstudio. Буфер захоплює повний HTML сторінки після завершення рендерингу WordPress, даючи змогу Tailwind просканувати всі класи з кожного джерела: шаблонів блоків і тем, виводу плагінів, фільтрів the_content та областей віджетів.

Фільтр компіляції запускається з пріоритетом 999999 на хуку blockstudio/buffer/output, щоб обробити остаточний HTML після всіх інших змін. Буфер запускається під час дії template_redirect, тому працює лише для запитів до фронтенду, а не в адмінці, REST API чи контекстах AJAX.

Буферизація всього документа дає змогу це робити, тому за замовчуванням вона ввімкнена. На сайті, де не використовуються ні Tailwind, ні ресурси блоків, її можна вимкнути:

PHP
add_filter( 'blockstudio/buffer/enabled', '__return_false' );

Повернення false повністю пропускає буферизацію, а також вимикає компіляцію Tailwind і перенесення стилів та скриптів блоків у head і footer.

Архітектура

Код
Frontend Request
  │
  ├─ WordPress renders HTML into output buffer
  │
  ├─ blockstudio/buffer/output filter (priority 999999)
  │   │
  │   ├─ Settings::get('tailwind/enabled') → false? Return HTML unchanged
  │   │
  │   ├─ build_css_input()
  │   │   ├─ @import "tailwindcss"
  │   │   ├─ + tailwind/config setting
  │   │   └─ + blockstudio/tailwind/css filter
  │   │
  │   ├─ TailwindPHP::extractCandidates($html)
  │   │   └─ Returns array of CSS class names found in HTML
  │   │
  │   ├─ Cache key = md5(sorted candidates + css input)
  │   │
  │   ├─ Cache hit?
  │   │   ├─ Yes → Read CSS from the shared runtime `tailwind/{hash}.css` scope
  │   │   └─ No  → TailwindPHP::generate() → Write to cache file
  │   │
  │   └─ Inject inline CSS, or link the content-hashed cache file when tailwind.output is "link"
  │
  └─ Browser receives HTML with compiled CSS


Editor Request
  │
  ├─ Admin loads block editor
  │
  ├─ Block with classes field (tailwind: true) detected
  │   └─ Block_Registry::set_tailwind_active(true)
  │
  ├─ Admin passes isTailwindActive + tailwindUrl to JS
  │
  └─ useTailwind() hook
      ├─ Injects Tailwind CDN script into document
      ├─ Creates hidden template div with HTML content
      ├─ Creates style tag for config
      └─ CDN compiles CSS in-browser for live preview

Повний приклад

Повністю робоче налаштування з власними кольорами теми та блоком, який їх використовує:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "tailwind": {
    "enabled": true,
    "config": "@theme { --color-brand: #6366f1; --color-brand-light: #a5b4fc; --color-surface: #f8fafc; } @layer utilities { .section-padding { @apply py-20 px-6; } .content-width { @apply max-w-5xl mx-auto; } .heading-xl { @apply text-4xl font-bold tracking-tight; } }"
  }
}
JSON
{
  "name": "my-theme/hero",
  "title": "Hero Section",
  "blockstudio": {
    "attributes": [
      {
        "id": "title",
        "type": "text",
        "label": "Title",
        "default": "Welcome"
      },
      {
        "id": "wrapperClasses",
        "type": "classes",
        "label": "Wrapper Classes",
        "tailwind": true,
        "default": "section-padding bg-surface"
      },
      {
        "id": "titleClasses",
        "type": "classes",
        "label": "Title Classes",
        "tailwind": true,
        "default": "heading-xl text-brand"
      }
    ]
  }
}
PHP
<section class="<?php echo $a['wrapperClasses']; ?>">
  <div class="content-width">
    <h1 class="<?php echo $a['titleClasses']; ?>">
      <?php echo esc_html($a['title']); ?>
    </h1>
  </div>
</section>

На фронтенді це відображається з усіма утилітами Tailwind і власними кольорами теми, скомпільованими в один вбудований тег <style>.

Створення бібліотеки блоків

Токени дизайну, власні утиліти та повне налаштування Tailwind v4 для продуктивної теми.