Gå til indhold

Tailwind CSS

Blockstudio har indbygget understøttelse af Tailwind CSS v4. Når funktionen er aktiveret, kompileres hver frontendside på serveren via TailwindPHP med automatisk filbaseret caching. I blokeditoren giver et medfølgende Tailwind CDN-script en liveforhåndsvisning, mens du redigerer.

Intet buildtrin, ingen CLI og ingen Node.js kræves.

Sådan fungerer det

Blockstudio bruger to separate kompileringsstrategier afhængigt af konteksten:

Frontend (serverbaseret)

Ved hver frontend-anmodning opsamler Blockstudio hele sidens HTML i en outputbuffer, udtrækker alle kandidater til CSS-klasser, kompilerer kun den CSS, der faktisk bruges, og indsætter resultatet som et indlejret <style>-tag før </head>.

Kompileringsforløbet:

  1. WordPress renderer hele sidens HTML i en outputbuffer
  2. TailwindPHP::extractCandidates() scanner HTML og udtrækker alle mulige CSS-klassenavne (hurtig regex, ingen kompilering)
  3. De sorterede kandidater hashes sammen med CSS-konfigurationen for at oprette en cache-nøgle
  4. Ved cache-hit: Den kompilerede CSS læses fra disken og indsættes
  5. Ved cache-miss: TailwindPHP::generate() kompilerer CSS, skriver det til cachemappen og indsætter det

Den kompilerede CSS indsættes som:

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

Dette omfatter Tailwinds preflight (CSS-nulstilling) og alle matchende hjælpeklasser.

Editor (klientside)

Inde i blokeditoren kører et medfølgende Tailwind CDN-script (browser-build af Tailwind CSS v4) på klientsiden. Det giver øjeblikkelig liveforhåndsvisning, mens du skriver klassenavne, uden rundture til serveren. CDN indlæses kun i editoren og leveres aldrig på frontend.

Når assets.reset.enabled er aktiv, gendanner Blockstudio også Tailwinds almindelige visnings- og placeringsværktøjer i editorens lærred. Det forhindrer, at klasser på wrapper-niveau som flex, grid, absolute, fixed og sticky tilsidesættes af WordPresss regler for editorens blok-wrappere, så layout, der styres af utility-klasser, stemmer bedre overens med frontend.

Aktivering af Tailwind

Føj konfigurationen tailwind til din blockstudio.json:

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

Eller aktivér den via et filter:

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

Når enabled er true, kompileres Tailwind CSS og indsættes automatisk på hver frontendside. Du kan bruge hjælpeklasser fra Tailwind hvor som helst: i blokskabeloner, temaskabeloner, the_content-filtre eller enhver HTML, der forekommer i sidens output.

Frontend-output

Kompileret CSS indsættes som standard direkte i siden, så outputtet fra tidligere versioner bevares. Websteder med mange fælles regler kan i stedet vælge et indholds-hashet stylesheet:

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

"output": "link" udsender den eksisterende cachefil tailwind/{content-hash}.css som en <link rel="stylesheet">. URL ændres, når runtimeidentiteten, kandidaterne, motoren eller CSS-input ændres, så browsere og edge-cacher trygt kan beholde gamle URL’er. Konfigurer webserveren eller CDN til at sende en langtidsholdbar Cache-Control: public, immutable-header for dette cachescope.

Standardroden for cachen er offentlig under wp-content. Hvis cache.path peger på et privat absolut drev, falder Blockstudio tilbage til indlejret CSS, medmindre det eksisterende blockstudio/files/url-filter angiver en offentlig URL for scopet 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
);

Hjælpere til skabelonsammensætning

Blockstudio stiller den samme medfølgende TailwindPHP-motor til rådighed for PHP-skabeloner. Der kræves ingen kopi eller reserveimplementering i temaet:

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() accepterer indlejrede klasseværdier og løser konflikter mellem Tailwind-værktøjer. bs_tw_variants() returnerer en callable i CVA-stil, der understøtter base, varianter, standardvarianter, sammensatte varianter, class og className.

Konfiguration

Tailwind v4 bruger en konfigurationstilgang, hvor CSS kommer først. I stedet for en JavaScript-konfigurationsfil skriver du konfigurationen direkte som CSS ved hjælp af direktivet @theme.

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

Værdien config er en streng af typen CSS, som føjes til efter direktivet @import "tailwindcss". Her kan du bruge enhver gyldig Tailwind v4 CSS-syntaks:

JSON
{
  "tailwind": {
    "enabled": true,
    "config": "@theme { --color-brand: oklch(0.7 0.15 200); } @layer base { h1 { font-size: var(--text-4xl); } }"
  }
}

Ved konfigurationer over flere linjer er filtertilgangen mere praktisk:

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

Brugerdefinerede utility-klasser

Hvis du vil definere genanvendelige klassealiaser, skal du bruge @layer utilities med direktivet @apply fra Tailwind direkte i din konfigurationsstreng:

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

Dette kompilerer disse klasser sammen med alle standardværktøjer i Tailwind. De fungerer både på frontend (serverbaseret kompilering) og i editoren (forhåndsvisning i CDN).

Blockstudio bevarer Tailwinds kanoniske rækkefølge for cascade-lag: theme, base, components og derefter utilities. Dette stemmer overens med Tailwind CSS, så regler i senere lag kan tilsidesætte tidligere lag som forventet.

Klassetype for felt

Hvis du vil bruge Tailwind-klasser i et bloks classes-felt med understøttelse af autofuldførelse, skal du indstille tailwind: true på feltet:

JSON
{
  "name": "my-theme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      {
        "id": "classes",
        "type": "classes",
        "label": "Classes",
        "tailwind": true,
        "default": "bg-white text-gray-900"
      }
    ]
  }
}

Når tailwind er true:

  • Feltet viser forslag til autofuldførelse fra hele Tailwind-klasselisten
  • Scriptet Tailwind CDN indlæses i editoren til liveforhåndsvisning
  • Klasser gemmes som en streng med mellemrum mellem værdierne i blokkens attributter

Brug værdien for klasser i din skabelon:

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

Reference til indstillinger

Indstilling Type Standard Beskrivelse
enabled boolean false Aktivér kompilering af Tailwind CSS på frontend
config string "" Konfigurationsstreng med Tailwind v4 CSS først

Indstilling via JSON

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

Indstilling via filtre

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

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

Caching

Blockstudio bruger en brugerdefineret cachestrategi, der er udviklet til Tailwinds værktøjsbaserede arkitektur.

Sådan fungerer cachen

I stedet for at hashe hele sidens HTML (hvilket ville tømme cachen ved hver anmodning på grund af nonces, tidsstempler og andet dynamisk indhold) udtrækker Blockstudio kun kandidaterne til CSS-klasser fra HTML. Kandidaterne sorteres og hashes sammen med konfigurationen for CSS, så der dannes en stabil cache-nøgle.

Det betyder:

  • To sider, der bruger det samme sæt Tailwind-klasser, deler den samme cachede CSS-fil, selvom deres HTML er helt forskellige
  • Dynamisk indhold som nonces, bjælker for indloggede brugere, kommentartællinger og tidsstempler tømmer ikke cachen
  • Cachen ugyldiggøres kun, når sættet af CSS-klasser på en side ændres, eller konfigurationen for Tailwind ændres

Når et runtime bruger en logisk opdagelseskilde, indgår den valgte kilde og runtime-konteksten også i cache-navnerummet. Senest vellykkede CSS er isoleret mellem forhåndsvisninger og kan ikke lække fra ét kildevalg til et andet.

Cacheplacering

Cachefiler gemmes her:

Kode
wp-content/blockstudio/cache/sites/{network-blog}/{runtime-identity}/tailwind/

Den konfigurerede cache.path, den aktuelle multisite-identitet og den komplette runtime-identitet bestemmer det præcise præfiks. Hver fil navngives med en MD5-hash: {hash}.css.

Ryd cachen

Slet indholdet i cachemappen for at gennemtvinge kompilering igen:

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

Eller via WP-CLI:

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

Den næste frontend-anmodning kompilerer og cacher automatisk CSS.

Filtre

blockstudio/tailwind/css

Rediger inputtet CSS før kompilering. Inputstrengen CSS starter med @import "tailwindcss"; efterfulgt af enhver konfiguration. Brug dette filter til at tilføje flere CSS-direktiver, brugerdefinerede @layer-regler eller plugin-importer.

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

Det fulde input CSS, der kompileres, ser sådan ud:

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

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

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

Outputbuffer

Tailwind-kompilering kobles på Blockstudios outputbuffersystem. Bufferen opfanger hele sidens HTML, efter at WordPress er færdig med at rendere, så Tailwind kan scanne alle klasser fra hver kilde: blokskabeloner, temas skabeloner, plugin-output, the_content-filtre og widgetområder.

Kompileringsfilteret køres med prioritet 999999 på hooken blockstudio/buffer/output, så det behandler den endelige HTML efter alle andre ændringer. Bufferen startes ved handlingen template_redirect, hvilket betyder, at den kun kører ved frontend-anmodninger, ikke i admin, REST API eller AJAX-kontekster.

Buffering af hele dokumentet gør dette muligt, så det er slået til som standard. Et websted, der hverken bruger Tailwind eller blokaktiver, kan slå det fra:

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

Hvis der returneres false, springes bufferen helt over, hvilket også deaktiverer Tailwind-kompilering samt flytning af bloktypografier og -scripts til head og footer.

Arkitektur

Kode
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

Fuldt eksempel

Et komplet fungerende setup med brugerdefinerede temafarver og en blok, der bruger dem:

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>

Dette rendrer på frontend med alle Tailwind-værktøjer og brugerdefinerede temafarver kompileret i et enkelt indlejret <style>-tag.

Byg et blokbibliotek

Designtokens, brugerdefinerede værktøjer og det komplette setup med Tailwind v4 til et produktionstema.