Tailwind CSS
Blockstudio ma wbudowaną obsługę Tailwind CSS v4. Po włączeniu każda strona frontendu jest kompilowana po stronie serwera za pomocą TailwindPHP z automatycznym buforowaniem opartym na plikach. W edytorze bloków dołączony skrypt Tailwind CDN zapewnia podgląd na żywo podczas edycji.
Bez procesu budowania, bez CLI, bez wymogu Node.js.
Jak to działa
Blockstudio stosuje dwie odrębne strategie kompilacji, zależnie od kontekstu:
Frontend (po stronie serwera)
Przy każdym żądaniu frontendu Blockstudio przechwytuje pełny kod strony HTML do bufora wyjściowego, wyodrębnia wszystkie kandydatury klas CSS, kompiluje tylko CSS faktycznie używane i wstawia wynik jako wbudowany znacznik <style> przed </head>.
Przebieg kompilacji:
- WordPress renderuje pełny kod strony HTML do bufora wyjściowego
TailwindPHP::extractCandidates()skanuje HTML i wyodrębnia wszystkie potencjalne nazwy klas CSS (szybkie wyrażenie regularne, bez kompilacji)- Posortowane kandydatury są łączone w skrót z konfiguracją CSS, aby utworzyć klucz pamięci podręcznej
- Przy trafieniu w pamięć podręczną: skompilowany CSS jest odczytywany z dysku i wstawiany
- Przy chybieniu w pamięci podręcznej:
TailwindPHP::generate()kompiluje CSS, zapisuje go w katalogu pamięci podręcznej i wstawia
Skompilowany CSS jest wstawiany jako:
<style id="blockstudio-tailwind">
/* compiled CSS */
</style>
Obejmuje to preflight Tailwind (reset CSS) i wszystkie dopasowane klasy narzędziowe.
Edytor (po stronie klienta)
W edytorze bloków działa po stronie klienta dołączony skrypt Tailwind CDN (przeglądarkowa kompilacja Tailwind CSS v4). Zapewnia natychmiastowy podgląd na żywo podczas wpisywania nazw klas, bez komunikacji z serwerem. CDN jest ładowany wyłącznie w edytorze i nigdy nie jest udostępniany na frontendzie.
Gdy aktywne jest assets.reset.enabled, Blockstudio przywraca też w kanwie edytora typowe narzędzia Tailwind do ustawiania wyświetlania i pozycji. Dzięki temu klasy na poziomie otaczającego elementu, takie jak flex, grid, absolute, fixed i sticky, nie są nadpisywane przez reguły WordPress dotyczące obudowy bloku w edytorze, a układy oparte na klasach narzędziowych lepiej odpowiadają frontendowi.
Włączanie Tailwind
Dodaj konfigurację tailwind do blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"tailwind": {
"enabled": true
}
}
Możesz też włączyć tę funkcję za pomocą filtra:
add_filter('blockstudio/settings/tailwind/enabled', '__return_true');
Gdy enabled ma wartość true, do każdej strony frontendu automatycznie zostanie skompilowane i wstawione Tailwind CSS. Klas narzędziowych Tailwind możesz używać wszędzie: w szablonach bloków, szablonach motywu, filtrach the_content lub dowolnym HTML pojawiającym się w wynikowym kodzie strony.
Wynik frontendu
Domyślnie skompilowane CSS jest wstawiane bezpośrednio w kod strony, co zachowuje sposób generowania wyniku z wcześniejszych wersji. Witryny ze wspólnymi regułami w dużej liczbie mogą zamiast tego używać arkusza stylów z hashem zawartości:
{
"tailwind": {
"enabled": true,
"output": "link"
}
}
"output": "link" emituje istniejący plik pamięci podręcznej tailwind/{content-hash}.css jako <link rel="stylesheet">. Wartość URL zmienia się po zmianie tożsamości środowiska wykonawczego, kandydatur, silnika lub danych wejściowych CSS, dzięki czemu przeglądarki i pamięci podręczne na brzegu sieci mogą bezpiecznie zachowywać stare adresy URL. Skonfiguruj serwer WWW lub CDN tak, aby dla tego zakresu pamięci podręcznej wysyłał długotrwały nagłówek Cache-Control: public, immutable.
Domyślny katalog główny pamięci podręcznej jest publiczny i znajduje się pod wp-content. Jeśli cache.path wskazuje prywatny wolumin z bezwzględną ścieżką, Blockstudio przechodzi na wbudowane CSS, chyba że istniejący filtr blockstudio/files/url udostępnia publiczne URL dla zakresu 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
);
Pomocniki kompozycji szablonów
Blockstudio udostępnia szablonom PHP ten sam dołączony silnik TailwindPHP. Nie trzeba kopiować go do motywu ani dostarczać zapasowej implementacji:
$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() przyjmuje zagnieżdżone wartości klas i rozstrzyga konflikty między narzędziami Tailwind. bs_tw_variants() zwraca wywoływalny obiekt w stylu CVA, obsługujący bazę, warianty, warianty domyślne, warianty złożone, class i className.
Konfiguracja
Tailwind v4 korzysta z podejścia konfiguracyjnego, w którym na pierwszym miejscu jest CSS. Zamiast pliku konfiguracyjnego JavaScript zapisujesz konfigurację bezpośrednio jako CSS przy użyciu dyrektywy @theme.
{
"tailwind": {
"enabled": true,
"config": "@theme { --color-primary: #3b82f6; --color-secondary: #10b981; --font-family-heading: 'Inter', sans-serif; }"
}
}
Wartość config to ciąg znaków CSS, który jest dodawany po dyrektywie @import "tailwindcss". Możesz tu użyć dowolnej poprawnej składni Tailwind v4 CSS:
{
"tailwind": {
"enabled": true,
"config": "@theme { --color-brand: oklch(0.7 0.15 200); } @layer base { h1 { font-size: var(--text-4xl); } }"
}
}
W przypadku konfiguracji wielowierszowych wygodniejsze jest podejście z filtrem:
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;
});
Niestandardowe klasy narzędziowe
Aby zdefiniować aliasy klas wielokrotnego użytku, użyj @layer utilities bezpośrednio w ciągu konfiguracyjnym, razem z dyrektywą @apply z 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; } }"
}
}
Te klasy są kompilowane razem ze wszystkimi standardowymi narzędziami Tailwind. Działają zarówno na stronie (kompilacja po stronie serwera), jak i w edytorze (podgląd CDN).
Blockstudio zachowuje kanoniczną kolejność warstw kaskady w Tailwind:
theme, base, components, a następnie utilities. Odpowiada to Tailwind CSS, dzięki czemu reguły z późniejszych warstw mogą zgodnie z oczekiwaniami nadpisywać wcześniejsze.
Typ pola Classes
Aby używać klas Tailwind w polu classes bloku z obsługą autouzupełniania, ustaw tailwind: true w polu:
{
"name": "my-theme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{
"id": "classes",
"type": "classes",
"label": "Classes",
"tailwind": true,
"default": "bg-white text-gray-900"
}
]
}
}
Gdy tailwind ma wartość true:
- Pole wyświetla sugestie autouzupełniania z pełnej listy klas Tailwind
- Skrypt Tailwind CDN jest ładowany w edytorze, aby umożliwić podgląd na żywo
- Klasy są przechowywane w atrybutach bloku jako ciąg znaków rozdzielonych spacjami
Użyj wartości klas w swoim szablonie:
<div class="<?php echo $a['classes']; ?>">
<!-- block content -->
</div>
Dokumentacja ustawień
| Opcja | Typ | Domyślna wartość | Opis |
|---|---|---|---|
enabled |
boolean | false |
Włącza kompilację Tailwind CSS na stronie |
config |
string | "" |
Ciąg konfiguracyjny, w którym pierwszeństwo ma Tailwind v4 CSS |
Ustawianie przez JSON
{
"tailwind": {
"enabled": true,
"config": "@theme { --color-brand: pink; }"
}
}
Ustawianie przez filtry
add_filter('blockstudio/settings/tailwind/enabled', '__return_true');
add_filter('blockstudio/settings/tailwind/config', function () {
return '@theme { --color-brand: pink; }';
});
Buforowanie
Blockstudio korzysta z niestandardowej strategii buforowania opracowanej z myślą o architekturze opartej na narzędziach Tailwind.
Jak działa buforowanie
Zamiast haszować cały kod strony HTML (co unieważniałoby bufor przy każdym żądaniu ze względu na nonce, sygnatury czasowe i inne dynamiczne treści), Blockstudio wyodrębnia z HTML tylko kandydatów klas CSS. Kandydaci są sortowani i haszowani razem z konfiguracją CSS, aby utworzyć stabilny klucz bufora.
Oznacza to, że:
- Dwie strony używające tego samego zestawu klas Tailwind korzystają z tego samego pliku CSS w buforze, nawet jeśli ich HTML są zupełnie różne
- Dynamiczne treści, takie jak nonce, paski zalogowanych użytkowników, liczby komentarzy i sygnatury czasowe, nie unieważniają bufora
- Bufor jest unieważniany tylko wtedy, gdy zmieni się zestaw klas CSS na stronie lub konfiguracja Tailwind
Gdy środowisko wykonawcze korzysta z logicznego źródła odkrywania, wybrane źródło i kontekst środowiska wykonawczego również są uwzględniane w przestrzeni nazw bufora. Ostatni poprawny wynik CSS jest odizolowany między podglądami i nie może przedostać się z jednego wyboru źródła do innego.
Lokalizacja bufora
Pliki bufora są przechowywane w:
wp-content/blockstudio/cache/sites/{network-blog}/{runtime-identity}/tailwind/
Skonfigurowane cache.path, bieżąca tożsamość witryny wielostanowiskowej i pełna tożsamość środowiska wykonawczego określają dokładny prefiks. Nazwa każdego pliku zawiera skrót MD5:
{hash}.css.
Czyszczenie bufora
Usuń zawartość katalogu bufora, aby wymusić ponowną kompilację:
// Clear all cached Tailwind CSS
Blockstudio\Runtime_Cache::purge('tailwind');
Lub przez WP-CLI:
wp eval "Blockstudio\\Runtime_Cache::purge('tailwind');"
Przy następnym żądaniu strony zostanie ponownie skompilowany i zapisany w buforze CSS.
Filtry
blockstudio/tailwind/css
Modyfikuj dane wejściowe CSS przed kompilacją. Ciąg wejściowy CSS zaczyna się od @import "tailwindcss";, po którym następuje dowolna konfiguracja. Użyj tego filtra, aby dodać dodatkowe dyrektywy CSS, niestandardowe reguły @layer lub importy wtyczek.
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;
});
Pełne dane wejściowe CSS poddawane kompilacji wyglądają tak:
/* Base import */
@import 'tailwindcss';
/* Config from settings (if set) */
@theme {
--color-brand: pink;
}
/* Anything added via the blockstudio/tailwind/css filter */
Bufor wyjściowy
Kompilacja Tailwind wykorzystuje system bufora wyjściowego Blockstudio. Bufor przechwytuje pełny kod strony HTML po zakończeniu renderowania przez WordPress, umożliwiając Tailwind skanowanie wszystkich klas ze wszystkich źródeł: szablonów bloków, szablonów motywów, wyjścia wtyczek, filtrów the_content i obszarów widżetów.
Filtr kompilacji działa z priorytetem 999999 na hooku blockstudio/buffer/output, dzięki czemu przetwarza końcowy HTML po wszystkich pozostałych modyfikacjach. Bufor jest uruchamiany w akcji template_redirect, więc działa tylko przy żądaniach ze strony, a nie w panelu administracyjnym, kontekstach REST API ani AJAX.
Buforowanie całego dokumentu umożliwia tę funkcję, dlatego jest domyślnie włączone. Witryna, która nie używa ani Tailwind, ani zasobów bloków, może je wyłączyć:
add_filter( 'blockstudio/buffer/enabled', '__return_false' );
Zwrócenie false całkowicie pomija bufor, co wyłącza również kompilację Tailwind oraz przenoszenie stylów i skryptów bloków do sekcji head i stopki.
Architektura
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
Pełny przykład
Kompletna, działająca konfiguracja z niestandardowymi kolorami motywu i blokiem, który z nich korzysta:
{
"$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>
Na stronie zostanie to wyrenderowane z wszystkimi narzędziami Tailwind i niestandardowymi kolorami motywu skompilowanymi do pojedynczego wbudowanego tagu <style>.
Tokeny projektowe, niestandardowe narzędzia i kompletna konfiguracja Tailwind v4 dla motywu produkcyjnego.