Tailwind CSS
Blockstudio include suport încorporat pentru Tailwind CSS v4. Când este activat, fiecare pagină frontend este compilată pe server prin TailwindPHP, cu memorare automată în cache bazată pe fișiere. În editorul de blocuri, un script Tailwind CDN inclus oferă o previzualizare live în timp ce editați.
Fără pas de build, fără CLI, fără Node.js necesar.
Cum funcționează
Blockstudio folosește două strategii de compilare separate, în funcție de context:
Frontend (pe server)
La fiecare cerere frontend, Blockstudio captează pagina completă HTML printr-un buffer de ieșire, extrage toți candidații pentru clase CSS, compilează doar CSS care sunt efectiv folosiți și inserează rezultatul ca etichetă <style> inline înainte de </head>.
Fluxul de compilare:
- WordPress randează pagina completă HTML într-un buffer de ieșire
TailwindPHP::extractCandidates()scanează HTML și extrage toate numele potențiale de clase CSS (regex rapid, fără compilare)- Candidații sortați sunt combinați prin hashing cu configurația CSS pentru a crea o cheie de cache
- La accesare în cache: CSS compilat este citit de pe disc și inserat
- La ratare din cache:
TailwindPHP::generate()compilează CSS, îl scrie în directorul cache și îl inserează
Elementul CSS compilat este inserat astfel:
<style id="blockstudio-tailwind">
/* compiled CSS */
</style>
Acesta include preflight-ul Tailwind (resetarea CSS) și toate clasele utilitare potrivite.
Editor (pe client)
În editorul de blocuri, un script Tailwind CDN inclus (build-ul de browser al Tailwind CSS v4) rulează pe client. Acesta oferă o previzualizare live instantanee pe măsură ce introduceți nume de clase, fără călătorii dus-întors către server. CDN se încarcă numai în editor și nu este niciodată servit pe frontend.
Când assets.reset.enabled este activ, Blockstudio restaurează și utilitarele obișnuite de afișare și poziționare ale Tailwind în canvas-ul editorului. Astfel, clasele la nivel de container, precum flex, grid, absolute, fixed și sticky, nu sunt suprascrise de regulile containerului WordPress al blocului din editor, astfel încât aspectele bazate pe utilitare să corespundă mai bine cu frontend-ul.
Activarea Tailwind
Adăugați configurația tailwind la blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"tailwind": {
"enabled": true
}
}
Sau activați-o printr-un filtru:
add_filter('blockstudio/settings/tailwind/enabled', '__return_true');
Când enabled este true, fiecare pagină frontend va avea Tailwind CSS compilat și inserat automat. Puteți folosi clase utilitare Tailwind oriunde: în șabloanele de blocuri, șabloanele temei, filtrele the_content sau orice HTML care apare în ieșirea paginii.
Ieșirea frontend
În mod implicit, CSS compilat este inline, păstrând ieșirea folosită de versiunile anterioare. Site-urile cu multe reguli partajate pot opta în schimb pentru o foaie de stil cu hash de conținut:
{
"tailwind": {
"enabled": true,
"output": "link"
}
}
"output": "link" emite fișierul cache tailwind/{content-hash}.css existent ca <link rel="stylesheet">. URL se schimbă când se modifică identitatea de execuție, candidații, motorul sau intrarea CSS, astfel încât browserele și cache-urile edge să poată păstra în siguranță URL-urile vechi. Configurați serverul web sau CDN să trimită un antet Cache-Control: public, immutable cu durată lungă pentru acest domeniu de cache.
Rădăcina cache-ului implicit este publică sub wp-content. Dacă cache.path indică spre un volum absolut privat, Blockstudio revine la CSS inline, cu excepția cazului în care filtrul existent blockstudio/files/url furnizează un URL public pentru domeniul 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
);
Funcții ajutătoare pentru compunerea șabloanelor
Blockstudio expune același motor TailwindPHP inclus și pentru șabloanele PHP. Nu este necesară o copie în temă sau o implementare alternativă:
$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() acceptă valori de clasă imbricate și rezolvă utilitățile Tailwind conflictuale. bs_tw_variants() returnează o funcție apelabilă de tip CVA care acceptă bază, variante, variante implicite, variante compuse, class și className.
Configurare
Tailwind v4 folosește o abordare de configurare bazată în primul rând pe CSS. În locul unui fișier de configurare JavaScript, scrieți configurația direct ca CSS folosind directiva @theme.
{
"tailwind": {
"enabled": true,
"config": "@theme { --color-primary: #3b82f6; --color-secondary: #10b981; --font-family-heading: 'Inter', sans-serif; }"
}
}
Valoarea config este un șir CSS care este adăugat după directiva @import "tailwindcss". Aici puteți folosi orice sintaxă validă Tailwind v4 CSS:
{
"tailwind": {
"enabled": true,
"config": "@theme { --color-brand: oklch(0.7 0.15 200); } @layer base { h1 { font-size: var(--text-4xl); } }"
}
}
Pentru configurații pe mai multe linii, abordarea cu filtru este mai comodă:
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;
});
Clase utilitare personalizate
Pentru a defini aliasuri de clase reutilizabile, folosiți @layer utilities cu directiva @apply din Tailwind, direct în șirul de configurare:
{
"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; } }"
}
}
Aceste clase sunt compilate alături de toate utilitățile standard Tailwind. Funcționează atât pe frontend (compilare pe server), cât și în editor (previzualizare CDN).
Blockstudio păstrează ordinea canonică a straturilor de cascadă din Tailwind:
theme, base, components, apoi utilities. Aceasta corespunde cu Tailwind CSS, astfel încât
regulile din straturile ulterioare le pot suprascrie pe cele din straturile anterioare, conform așteptărilor.
Tipul câmpului Classes
Pentru a folosi clasele Tailwind în câmpul classes al unui bloc, cu suport pentru completare automată, setați tailwind: true pentru câmp:
{
"name": "my-theme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{
"id": "classes",
"type": "classes",
"label": "Classes",
"tailwind": true,
"default": "bg-white text-gray-900"
}
]
}
}
Când tailwind este true:
- Câmpul oferă sugestii de completare automată din lista completă de clase Tailwind
- Scriptul Tailwind CDN este încărcat în editor pentru previzualizare în timp real
- Clasele sunt stocate ca șiruri separate prin spații în atributele blocului
Folosiți valoarea classes în șablon:
<div class="<?php echo $a['classes']; ?>">
<!-- block content -->
</div>
Referință pentru setări
| Opțiune | Tip | Implicit | Descriere |
|---|---|---|---|
enabled |
boolean | false |
Activează compilarea Tailwind CSS pe frontend |
config |
string | "" |
Șir de configurare Tailwind v4 bazat în primul rând pe CSS |
Setarea prin JSON
{
"tailwind": {
"enabled": true,
"config": "@theme { --color-brand: pink; }"
}
}
Setarea prin filtre
add_filter('blockstudio/settings/tailwind/enabled', '__return_true');
add_filter('blockstudio/settings/tailwind/config', function () {
return '@theme { --color-brand: pink; }';
});
Memorarea în cache
Blockstudio folosește o strategie personalizată de memorare în cache, concepută pentru arhitectura bazată pe utilități a Tailwind.
Cum funcționează memoria cache
În loc să calculeze hash-ul întregului HTML al paginii (ceea ce ar invalida memoria cache la fiecare solicitare din cauza nonce-urilor, marcajelor temporale și altui conținut dinamic), Blockstudio extrage doar candidații de clase CSS din HTML. Acești candidați sunt sortați și calculați împreună cu configurația CSS pentru a produce o cheie de cache stabilă.
Aceasta înseamnă că:
- Două pagini care folosesc același set de clase Tailwind partajează același fișier CSS memorat în cache, chiar dacă HTML diferă complet
- Conținutul dinamic, precum nonce-urile, barele utilizatorilor autentificați, numărul comentariilor și marcajele temporale, nu invalidează memoria cache
- Memoria cache este invalidată doar când se schimbă setul de clase CSS de pe o pagină sau configurația Tailwind
Când un runtime folosește o sursă de descoperire logică, sursa selectată și contextul runtime participă și ele la spațiul de nume al memoriei cache. Ultima configurație CSS validă este izolată între previzualizări și nu se poate scurge de la o selecție de sursă la alta.
Locația memoriei cache
Fișierele cache sunt stocate în:
wp-content/blockstudio/cache/sites/{network-blog}/{runtime-identity}/tailwind/
Prefixul exact este determinat de cache.path configurat, identitatea multisite curentă și identitatea completă a runtime-ului. Fiecare fișier este numit folosind un hash MD5:
{hash}.css.
Golirea memoriei cache
Ștergeți conținutul directorului cache pentru a forța recompilarea:
// Clear all cached Tailwind CSS
Blockstudio\Runtime_Cache::purge('tailwind');
Sau prin WP-CLI:
wp eval "Blockstudio\\Runtime_Cache::purge('tailwind');"
Următoarea solicitare către frontend va recompila și memora automat în cache CSS.
Filtre
blockstudio/tailwind/css
Modificați intrarea CSS înainte de compilare. Șirul de intrare CSS începe cu @import "tailwindcss";, urmat de orice configurație. Folosiți acest filtru pentru a adăuga directive CSS suplimentare, reguli personalizate @layer sau importuri de pluginuri.
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;
});
Intrarea completă CSS care este compilată arată astfel:
/* Base import */
@import 'tailwindcss';
/* Config from settings (if set) */
@theme {
--color-brand: pink;
}
/* Anything added via the blockstudio/tailwind/css filter */
Buffer de ieșire
Compilarea Tailwind se integrează în sistemul de buffer de ieșire al Blockstudio. Bufferul captează întregul HTML al paginii după ce WordPress a terminat randarea, permițându-i lui Tailwind să scaneze toate clasele din fiecare sursă: șabloanele blocurilor, șabloanele temei, ieșirea pluginurilor, filtrele the_content și zonele de widgeturi.
Filtrul de compilare rulează la prioritatea 999999 pe hook-ul blockstudio/buffer/output, asigurând procesarea finală a HTML după toate celelalte modificări. Bufferul este pornit la acțiunea template_redirect, ceea ce înseamnă că rulează doar la solicitările frontend, nu în admin, REST API sau în contexte AJAX.
Captarea întregului document face posibil acest lucru, de aceea este activată implicit. Un site care nu folosește nici Tailwind, nici resurse pentru blocuri o poate dezactiva:
add_filter( 'blockstudio/buffer/enabled', '__return_false' );
Returnarea valorii false omite complet bufferul, dezactivând totodată compilarea Tailwind și mutarea stilurilor și scripturilor blocurilor în antet și subsol.
Arhitectură
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
Exemplu complet
O configurare completă și funcțională, cu culori personalizate pentru temă și un bloc care le folosește:
{
"$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>
Astfel, frontend-ul afișează toate utilitățile Tailwind și culorile personalizate ale temei, compilate într-o singură etichetă inline <style>.
Crearea unei biblioteci de blocuri
Tokenuri de design, utilități personalizate și configurarea completă Tailwind v4 pentru o temă de producție.