Перейти к содержимому

Tailwind CSS

Blockstudio включает встроенную поддержку Tailwind CSS v4. Если функция включена, каждая страница сайта компилируется на сервере через TailwindPHP с автоматическим кэшированием файлов. В редакторе блоков встроенный скрипт Tailwind CDN обеспечивает предварительный просмотр в реальном времени во время редактирования.

Без этапа сборки, без CLI и без Node.js.

Как это работает

Blockstudio использует две отдельные стратегии компиляции в зависимости от контекста:

Внешняя часть (на стороне сервера)

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

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

  1. WordPress выводит весь код страницы HTML в буфер вывода
  2. TailwindPHP::extractCandidates() сканирует HTML и извлекает все возможные имена классов CSS (быстрое регулярное выражение, без компиляции)
  3. Отсортированные кандидаты хешируются вместе с конфигурацией CSS, образуя ключ кэша
  4. При попадании в кэш скомпилированный CSS считывается с диска и вставляется в страницу
  5. При промахе кэша TailwindPHP::generate() компилирует CSS, записывает его в каталог кэша и вставляет в страницу

Скомпилированный CSS вставляется так:

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

В него входят предварительные стили Tailwind (сброс CSS) и все найденные классы утилит.

Редактор (на стороне клиента)

В редакторе блоков на стороне клиента запускается встроенный скрипт Tailwind CDN (браузерная сборка Tailwind CSS v4). Он обеспечивает мгновенный предварительный просмотр при вводе имён классов без запросов к серверу. CDN загружается только в редакторе и никогда не отправляется на сайт для посетителей.

Если активен assets.reset.enabled, Blockstudio также восстанавливает в холсте редактора стандартные утилиты отображения и позиционирования из Tailwind. Это не позволяет правилам обёртки блоков редактора WordPress переопределять классы уровня обёртки, такие как flex, grid, absolute, fixed и sticky, благодаря чему макеты на основе утилит точнее соответствуют внешней части сайта.

Включение 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
  • В редактор загружается скрипт CDN Tailwind для предварительного просмотра в реальном времени
  • Классы хранятся в атрибутах блока в виде строки с разделителями-пробелами

Используйте значение classes в шаблоне:

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

Справочник настроек

Параметр Тип По умолчанию Описание
enabled boolean false Включает компиляцию Tailwind CSS на внешней стороне сайта
config string "" Строка конфигурации 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-кода страницы 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-код страницы 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 и перенос стилей и скриптов блоков в заголовок и нижнюю часть страницы.

Архитектура

Код
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 для рабочей темы.