Přejít k obsahu

Tailwind CSS

Blockstudio obsahuje vestavěnou podporu Tailwind CSS v4. Je-li povolena, každá stránka frontendové části se kompiluje na serveru pomocí TailwindPHP s automatickým ukládáním do souborové mezipaměti. V editoru bloků zajišťuje průběžný náhled při úpravách přibalený skript Tailwind CDN.

Není potřeba sestavení, CLI ani Node.js.

Jak to funguje

Blockstudio používá dvě různé strategie kompilace podle kontextu:

Frontend (na straně serveru)

Při každém požadavku frontendové části zachytí Blockstudio kompletní HTML stránky do výstupního bufferu, získá všechny kandidáty tříd CSS, zkompiluje pouze skutečně použité CSS a výsledek vloží jako vložený tag <style> před </head>.

Postup kompilace:

  1. WordPress vykreslí kompletní HTML stránky do výstupního bufferu
  2. TailwindPHP::extractCandidates() prohledá HTML a získá všechny potenciální názvy tříd CSS (rychlý regulární výraz bez kompilace)
  3. Seřazené kandidáty se společně s konfigurací CSS zahashují a vytvoří klíč mezipaměti
  4. Při zásahu v mezipaměti se z disku načte zkompilované CSS a vloží se do stránky
  5. Při minutí v mezipaměti zkompiluje TailwindPHP::generate() CSS, zapíše ho do adresáře mezipaměti a vloží do stránky

Zkompilované CSS se vloží takto:

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

Zahrnuje preflight Tailwind (reset CSS) a všechny odpovídající pomocné třídy.

Editor (na straně klienta)

V editoru bloků běží na straně klienta přibalený skript Tailwind CDN (prohlížečová verze Tailwind CSS v4). Poskytuje okamžitý živý náhled při zadávání názvů tříd bez komunikace se serverem. Skript CDN se načítá pouze v editoru a nikdy se neposkytuje ve frontendové části.

Když je aktivní assets.reset.enabled, obnovuje Blockstudio v plátně editoru také běžné pomocné třídy Tailwind pro zobrazení a umístění. Tím se zabrání přepsání tříd na úrovni obalu, jako jsou flex, grid, absolute, fixed a sticky, pravidly obalů bloků editoru WordPress, takže rozvržení založená na pomocných třídách lépe odpovídají frontendové části.

Povolení Tailwind

Přidejte konfiguraci tailwind do souboru blockstudio.json:

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

Nebo funkci povolte pomocí filtru:

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

Když je enabled true, na každé stránce frontendové části se automaticky zkompiluje a vloží Tailwind CSS. Pomocné třídy Tailwind můžete použít kdekoli: v šablonách bloků, šablonách motivu, filtrech the_content nebo v jakémkoli HTML, které se objeví ve výstupu stránky.

Výstup frontendové části

Zkompilované CSS se ve výchozím nastavení vkládá přímo do stránky, čímž se zachovává výstup používaný v předchozích verzích. Weby s mnoha sdílenými pravidly mohou místo toho použít stylopis s hashem obsahu:

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

"output": "link" vytvoří z existujícího souboru mezipaměti tailwind/{content-hash}.css soubor <link rel="stylesheet">. Hodnota URL se změní, když se změní identita běhového prostředí, kandidáti, engine nebo vstup CSS, takže prohlížeče a edge mezipaměti mohou bezpečně uchovávat staré adresy URL. Nastavte webový server nebo CDN tak, aby tomuto rozsahu mezipaměti posílal dlouhodobou hlavičku Cache-Control: public, immutable.

Výchozí kořen mezipaměti je veřejný a nachází se pod wp-content. Pokud cache.path ukazuje na soukromý absolutní svazek, Blockstudio místo toho použije vložené CSS, pokud existující filtr blockstudio/files/url nenastaví veřejné URL pro rozsah 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
);

Pomocné funkce pro skládání šablon

Blockstudio zpřístupňuje šablonám PHP stejný přibalený engine TailwindPHP. Není potřeba kopie ani záložní implementace v motivu:

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() přijímá vnořené hodnoty tříd a řeší konflikty mezi Tailwind utilitami. bs_tw_variants() vrací volatelnou funkci ve stylu CVA, která podporuje základní třídy, varianty, výchozí varianty, složené varianty, class a className.

Konfigurace

Tailwind v4 používá přístup ke konfiguraci, v němž mají přednost CSS. Místo konfiguračního souboru JavaScript zapisujete konfiguraci přímo jako CSS pomocí direktivy @theme.

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

Hodnota config je řetězec CSS, který se připojí za direktivu @import "tailwindcss". Můžete zde použít jakoukoli platnou syntaxi 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); } }"
  }
}

U víceřádkových konfigurací je praktičtější přístup s filtrem:

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;
});

Vlastní třídy utilit

Chcete-li definovat opakovaně použitelné aliasy tříd, použijte @layer utilities s direktivou @apply v Tailwind přímo v konfiguračním řetězci:

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; } }"
  }
}

Tyto třídy se zkompilují spolu se všemi standardními utilitami Tailwind. Fungují jak na frontendu (kompilace na straně serveru), tak v editoru (náhled CDN).

Blockstudio zachovává kanonické pořadí vrstev kaskády Tailwind: theme, base, components a poté utilities. Odpovídá to Tailwind CSS, takže pravidla v pozdějších vrstvách mohou podle očekávání přepsat pravidla v dřívějších vrstvách.

Typ pole tříd

Chcete-li v poli classes bloku používat třídy Tailwind s podporou automatického doplňování, nastavte v poli 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"
      }
    ]
  }
}

Když je tailwind nastaveno na true:

  • Pole nabízí návrhy automatického doplňování z úplného seznamu tříd Tailwind
  • V editoru se načte skript Tailwind CDN pro živý náhled
  • Třídy se ukládají v atributech bloku jako řetězec oddělený mezerami

Hodnotu tříd použijte ve své šabloně:

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

Přehled nastavení

Možnost Typ Výchozí hodnota Popis
enabled boolean false Povolit kompilaci Tailwind CSS na frontendu
config string "" Konfigurační řetězec Tailwind v4 s předností CSS

Nastavení pomocí JSON

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

Nastavení pomocí filtrů

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

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

Ukládání do mezipaměti

Blockstudio používá vlastní strategii ukládání do mezipaměti navrženou pro architekturu založenou na utilitách Tailwind.

Jak funguje mezipaměť

Místo hashování celé stránky HTML (což by při každém požadavku zneplatnilo mezipaměť kvůli nonce, časovým značkám a dalšímu dynamickému obsahu) Blockstudio získá z HTML pouze kandidátní třídy CSS. Tyto kandidáty se seřadí a společně s konfigurací CSS se z nich vypočítá hash, který slouží jako stabilní klíč mezipaměti.

To znamená:

  • Dvě stránky používající stejnou sadu tříd Tailwind sdílejí tentýž soubor CSS v mezipaměti, i když se jejich HTML zcela liší
  • Dynamický obsah, jako jsou nonce, lišty přihlášených uživatelů, počty komentářů a časové značky, mezipaměť nezneplatní
  • Mezipaměť se zneplatní pouze tehdy, když se změní sada tříd CSS na stránce nebo konfigurace Tailwind

Pokud runtime používá logický zdroj pro zjišťování, vybraný zdroj a kontext runtime se také zahrnou do jmenného prostoru mezipaměti. Poslední dobrá verze CSS je mezi náhledy oddělena a nemůže se přenést z jednoho výběru zdroje do jiného.

Umístění mezipaměti

Soubory mezipaměti se ukládají do:

Kód
wp-content/blockstudio/cache/sites/{network-blog}/{runtime-identity}/tailwind/

Přesný prefix určuje nakonfigurované cache.path, aktuální identita multisite a úplná identita runtime. Název každého souboru tvoří hash MD5: {hash}.css.

Vymazání mezipaměti

Vynucení nové kompilace provedete smazáním obsahu adresáře mezipaměti:

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

Nebo pomocí WP-CLI:

Shell
wp eval "Blockstudio\\Runtime_Cache::purge('tailwind');"

Při příštím požadavku na frontend se CSS automaticky znovu zkompiluje a uloží do mezipaměti.

Filtry

blockstudio/tailwind/css

Před kompilací upravte vstup CSS. Vstupní řetězec CSS začíná na @import "tailwindcss";, za kterým následuje libovolná konfigurace. Tento filtr použijte k přidání dalších direktiv CSS, vlastních pravidel @layer nebo importů pluginů.

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;
});

Úplný vstup CSS, který se zkompiluje, vypadá takto:

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

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

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

Výstupní buffer

Kompilace Tailwind se napojuje na systém výstupního bufferu Blockstudio. Buffer zachytí celý obsah stránky HTML poté, co WordPress dokončí vykreslování, a umožní tak Tailwind prohledat všechny třídy ze všech zdrojů: šablon bloků, šablon motivu, výstupu pluginů, filtrů the_content a oblastí widgetů.

Kompilační filtr se spouští s prioritou 999999 na hooku blockstudio/buffer/output, takže zpracuje konečné HTML až po všech ostatních úpravách. Buffer se spouští při akci template_redirect, takže běží pouze při požadavcích na frontend, nikoli v administraci, v REST API ani v kontextech AJAX.

Zachycení celého dokumentu umožňuje tuto funkci, proto je ve výchozím nastavení zapnuté. Web, který nepoužívá Tailwind ani prostředky bloků, ho může vypnout:

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

Vrácením hodnoty false se buffer zcela přeskočí, čímž se také vypne kompilace Tailwind a přesunutí stylů a skriptů bloků do hlavičky a patičky.

Architektura

Kód
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

Úplný příklad

Kompletní funkční nastavení s vlastními barvami motivu a blokem, který je používá:

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>

Na frontendu se tak vykreslí všechny utility Tailwind a vlastní barvy motivu zkompilované do jediného vloženého tagu <style>.

Vytvoření knihovny bloků

Designové tokeny, vlastní utility a kompletní nastavení Tailwind v4 pro produkční motiv.