Tailwind CSS
Blockstudio включает встроенную поддержку Tailwind CSS v4. Если функция включена, каждая страница сайта компилируется на сервере через TailwindPHP с автоматическим кэшированием файлов. В редакторе блоков встроенный скрипт Tailwind CDN обеспечивает предварительный просмотр в реальном времени во время редактирования.
Без этапа сборки, без CLI и без Node.js.
Как это работает
Blockstudio использует две отдельные стратегии компиляции в зависимости от контекста:
Внешняя часть (на стороне сервера)
При каждом запросе к внешней части Blockstudio перехватывает вывод всей страницы HTML через буфер, извлекает все возможные классы CSS, компилирует только фактически используемый CSS и вставляет результат в виде встроенного тега <style> перед </head>.
Процесс компиляции:
- WordPress выводит весь код страницы HTML в буфер вывода
TailwindPHP::extractCandidates()сканирует HTML и извлекает все возможные имена классов CSS (быстрое регулярное выражение, без компиляции)- Отсортированные кандидаты хешируются вместе с конфигурацией CSS, образуя ключ кэша
- При попадании в кэш скомпилированный CSS считывается с диска и вставляется в страницу
- При промахе кэша
TailwindPHP::generate()компилирует CSS, записывает его в каталог кэша и вставляет в страницу
Скомпилированный CSS вставляется так:
<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:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"tailwind": {
"enabled": true
}
}
Или включите функцию через фильтр:
add_filter('blockstudio/settings/tailwind/enabled', '__return_true');
Если enabled включён (true), на каждой странице сайта Tailwind CSS будет автоматически скомпилирован и вставлен. Классы утилит Tailwind можно использовать где угодно: в шаблонах блоков, шаблонах темы, фильтрах the_content или любом HTML в выводе страницы.
Вывод внешней части
По умолчанию скомпилированный CSS вставляется в страницу, как и в предыдущих версиях. Для сайтов с множеством общих правил можно включить таблицу стилей с хешем содержимого:
{
"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:
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. Копия или резервная реализация в теме не требуются:
$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.
{
"tailwind": {
"enabled": true,
"config": "@theme { --color-primary: #3b82f6; --color-secondary: #10b981; --font-family-heading: 'Inter', sans-serif; }"
}
}
Значение config — это строка CSS, которая добавляется после директивы @import "tailwindcss". Здесь можно использовать любой допустимый синтаксис Tailwind v4 CSS:
{
"tailwind": {
"enabled": true,
"config": "@theme { --color-brand: oklch(0.7 0.15 200); } @layer base { h1 { font-size: var(--text-4xl); } }"
}
}
Для многострочных конфигураций удобнее использовать фильтр:
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 прямо в строке конфигурации:
{
"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:
{
"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 в шаблоне:
<div class="<?php echo $a['classes']; ?>">
<!-- block content -->
</div>
Справочник настроек
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
enabled |
boolean | false |
Включает компиляцию Tailwind CSS на внешней стороне сайта |
config |
string | "" |
Строка конфигурации Tailwind v4 с приоритетом CSS |
Настройка через JSON
{
"tailwind": {
"enabled": true,
"config": "@theme { --color-brand: pink; }"
}
}
Настройка через фильтры
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.
Очистка кэша
Удалите содержимое каталога кэша, чтобы принудительно запустить компиляцию заново:
// 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 или импорты плагинов.
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 для компиляции выглядят так:
/* 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, ни ресурсы блоков, буферизацию можно отключить:
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
Полный пример
Полностью рабочая конфигурация с пользовательскими цветами темы и блоком, который их использует:
{
"$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; } }"
}
}
{
"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"
}
]
}
}
<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 для рабочей темы.