Siirry sisältöön

Tailwind CSS

Blockstudio sisältää sisäänrakennetun Tailwind CSS v4 -tuen. Kun se on käytössä, jokainen käyttöliittymän sivu käännetään palvelinpuolella TailwindPHP:n kautta automaattisella tiedostopohjaisella välimuistilla. Lohkoeditorissa mukana toimitettava Tailwind CDN -skripti näyttää esikatselun reaaliajassa muokkauksen aikana.

Ei koontivaihetta, ei CLI:tä eikä Node.js:tä.

Näin se toimii

Blockstudio käyttää kahta erillistä käännösstrategiaa kontekstin mukaan:

Käyttöliittymä (palvelinpuoli)

Jokaisella käyttöliittymän pyynnöllä Blockstudio sieppaa koko sivun HTML-sisällön tulospuskuriin, poimii kaikki CSS-luokkavaihtoehdot, kääntää vain todellisuudessa käytetyn CSS-sisällön ja lisää tuloksen sisäiseksi <style>-tunnisteeksi ennen kohtaa </head>.

Käännösprosessi:

  1. WordPress renderöi koko sivun HTML-sisällön tulospuskuriin
  2. TailwindPHP::extractCandidates() käy HTML-sisällön läpi ja poimii kaikki mahdolliset CSS-luokkanimet (nopea regex-haku, ei käännöstä)
  3. Lajitellut ehdokkaat tiivistetään yhdessä CSS-asetusten kanssa välimuistiavaimeksi
  4. Välimuistiosuma: käännetty CSS luetaan levyltä ja lisätään sivulle
  5. Välimuistin ohitus: TailwindPHP::generate() kääntää CSS-sisällön, kirjoittaa sen välimuistihakemistoon ja lisää sen sivulle

Käännetty CSS lisätään näin:

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

Tämä sisältää Tailwind-esikäsittelyn (CSS-nollauksen) sekä kaikki tunnistetut apuluokat.

Editori (asiakaspuoli)

Lohkoeditorissa mukana toimitettava Tailwind CDN -skripti (selaimeen käännetty versio: Tailwind CSS v4) suoritetaan asiakaspuolella. Se näyttää esikatselun välittömästi luokkien nimien kirjoittamisen aikana ilman palvelimelle tehtäviä edestakaisia pyyntöjä. CDN ladataan vain editorissa, eikä sitä koskaan tarjoilla käyttöliittymässä.

Kun assets.reset.enabled on aktiivinen, Blockstudio palauttaa editorin canvas-alueelle myös Tailwindn yleiset näyttö- ja sijaintiapuluokat. Näin kääreetason luokkia, kuten flex, grid, absolute, fixed ja sticky, eivät kumoa WordPress-editorin lohkokääreen sääntöjä, joten apuluokilla ohjatut asettelut vastaavat paremmin käyttöliittymää.

Tailwindn käyttöönotto

Lisää tailwind-määritys tiedostoon blockstudio.json:

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

Tai ota se käyttöön suodattimen kautta:

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

Kun enabled on true, jokaisella käyttöliittymän sivulla on automaattisesti käännetty ja lisätty Tailwind CSS. Voit käyttää apuluokkia Tailwind missä tahansa: lohkomalleissa, teemamalleissa, the_content-suodattimissa tai missä tahansa sivun tulosteessa esiintyvässä HTML-sisällössä.

Käyttöliittymän tuloste

Käännetty CSS lisätään oletusarvoisesti sivulle sisäisesti, mikä säilyttää aiempien versioiden tulosteen. Sivustot, joilla on paljon yhteisiä sääntöjä, voivat valita sen sijaan sisältötiivisteellisen tyylitiedoston:

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

"output": "link" julkaisee nykyisen tailwind/{content-hash}.css-välimuistitiedoston muodossa <link rel="stylesheet">. URL muuttuu, kun ajonaikainen identiteetti, ehdokkaat, moottori tai CSS-syöte muuttuu, joten selaimet ja reunavälimuistit voivat säilyttää vanhat URL-osoitteet turvallisesti. Määritä verkkopalvelin tai CDN lähettämään tälle välimuistialueelle pitkäkestoinen Cache-Control: public, immutable-otsake.

Oletusarvoinen välimuistin juurihakemisto on julkinen, sijainnissa wp-content. Jos cache.path osoittaa yksityiseen absoluuttiseen levyasemaan, Blockstudio käyttää sisäistä CSS-sisältöä, ellei olemassa oleva blockstudio/files/url-suodatin määritä julkista URL-arvoa alueelle 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
);

Mallien koostamisapurit

Blockstudio tarjoaa malleille saman mukana toimitettavan TailwindPHP-moottorin kuin PHP. Teeman puolelle ei tarvita erillistä kopiota tai varatoteutusta:

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() hyväksyy sisäkkäisiä luokka-arvoja ja ratkaisee ristiriitaiset Tailwind-apuohjelmat. bs_tw_variants() palauttaa CVA-tyylisen kutsuttavan funktion, joka tukee perusluokkia, variantteja, oletusvariantteja, yhdistelmävariantteja, class ja className.

Määritykset

Tailwind v4 käyttää CSS-keskeistä määritystapaa. Erillisen JavaScript-määritystiedoston sijaan kirjoitat määritykset suoraan CSS-koodina @theme-direktiivillä.

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

config-arvo on CSS-merkkijono, joka lisätään @import "tailwindcss"-direktiivin jälkeen. Tässä voit käyttää mitä tahansa kelvollista Tailwind v4 CSS-syntaksia:

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

Monirivisissä määrityksissä suodatin on kätevämpi tapa:

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

Mukautetut apuluokat

Määritä uudelleenkäytettävät luokka-aliakset käyttämällä @layer utilities-määritystä ja Tailwind-järjestelmän @apply-direktiiviä suoraan määritysmerkkijonossa:

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

Nämä luokat käännetään kaikkien tavallisten Tailwind-apuohjelmien rinnalla. Ne toimivat sekä käyttöliittymässä (palvelinpuolen käännös) että editorissa (CDN-esikatselu).

Blockstudio säilyttää Tailwind-järjestelmän kanonisen CSS-kerrosten järjestyksen: theme, base, components ja sitten utilities. Tämä vastaa Tailwind CSS-määritystä, joten myöhemmissä kerroksissa olevat säännöt voivat odotetusti ohittaa aiempien kerrosten säännöt.

Classes-kentän tyyppi

Jos haluat käyttää Tailwind-luokkia lohkon classes-kentässä automaattisen täydennyksen kanssa, määritä kentälle 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"
      }
    ]
  }
}

Kun tailwind on true:

  • Kenttä tarjoaa automaattisen täydennyksen ehdotuksia koko Tailwind-luokkaluettelosta
  • Tailwind CDN-skripti ladataan editorissa reaaliaikaista esikatselua varten
  • Luokat tallennetaan lohkon attribuutteihin välilyönneillä eroteltuna merkkijonona

Käytä luokka-arvoa mallipohjassasi:

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

Asetusten viite

Valinta Tyyppi Oletus Kuvaus
enabled boolean false Ota Tailwind CSS-käännös käyttöliittymässä käyttöön
config merkkijono "" Tailwind v4 CSS-keskeinen määritysmerkkijono

Asetus JSON-määrityksellä

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

Asetus suodattimilla

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

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

Välimuisti

Blockstudio käyttää mukautettua välimuististrategiaa, joka on suunniteltu Tailwind-järjestelmän apuluokkiin perustuvalle arkkitehtuurille.

Välimuistin toiminta

Sen sijaan, että koko sivun HTML laskettaisiin tiivisteeksi (mikä tyhjentäisi välimuistin jokaisella pyynnöllä nonce-arvojen, aikaleimojen ja muun dynaamisen sisällön vuoksi), Blockstudio poimii HTML-koodista vain CSS-luokkaehdokkaat. Ehdokkaat lajitellaan, ja niistä lasketaan tiiviste yhdessä CSS-määrityksen kanssa vakaan välimuistiavaimen muodostamiseksi.

Tämä tarkoittaa seuraavaa:

  • Kaksi sivua, joilla käytetään samaa Tailwind-luokkajoukkoa, käyttävät samaa välimuistissa olevaa CSS-tiedostoa, vaikka niiden HTML olisi täysin erilainen
  • Dynaaminen sisältö, kuten nonce-arvot, kirjautuneen käyttäjän palkit, kommenttimäärät ja aikaleimat, ei tyhjennä välimuistia
  • Välimuisti mitätöidään vain, kun sivun CSS-luokkajoukko tai Tailwind-määritys muuttuu

Kun ajonaikainen ympäristö käyttää loogista löytämislähdettä, valittu lähde ja ajonaikainen konteksti vaikuttavat myös välimuistin nimiavaruuteen. Viimeisin onnistunut CSS eristetään esikatselujen välillä, eikä se voi vuotaa lähdevalinnasta toiseen.

Välimuistin sijainti

Välimuistitiedostot tallennetaan seuraavaan sijaintiin:

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

Määritetty cache.path, nykyisen multisite-asennuksen tunniste ja koko ajonaikaisen ympäristön tunniste määrittävät tarkan etuliitteen. Jokaisen tiedoston nimi sisältää MD5-tiivisteen: {hash}.css.

Välimuistin tyhjentäminen

Pakota uudelleenkäännös poistamalla välimuistihakemiston sisältö:

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

Tai käytä komentoa WP-CLI:

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

Seuraavan käyttöliittymäpyynnön yhteydessä CSS käännetään ja tallennetaan välimuistiin automaattisesti.

Suodattimet

blockstudio/tailwind/css

Muokkaa CSS-syötettä ennen kääntämistä. CSS-syötemerkkijono alkaa arvolla @import "tailwindcss";, jota seuraa määritys. Lisää tämän suodattimen avulla CSS-direktiivejä, mukautettuja @layer-sääntöjä tai liitännäisten tuonteja.

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

Koko käännettävä CSS-syöte näyttää tältä:

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

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

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

Tulospuskuri

Tailwind-käännös liittyy Blockstudio-järjestelmän tulospuskurijärjestelmään. Puskuri kerää koko sivun HTML-sisällön sen jälkeen, kun WordPress on suorittanut renderöinnin. Näin Tailwind voi etsiä luokkia kaikista lähteistä: lohkomallipohjista, teeman mallipohjista, liitännäisten tulosteesta, the_content-suodattimista ja vimpaimista.

Käännössuodatin suoritetaan prioriteetilla 999999 blockstudio/buffer/output-koukussa, jotta se käsittelee lopullisen HTML-tuloksen kaikkien muiden muutosten jälkeen. Puskuri käynnistetään template_redirect-toiminnossa, joten se toimii vain käyttöliittymäpyynnöissä, ei hallintapaneelissa, REST API- tai AJAX-konteksteissa.

Koko dokumentin puskurointi tekee tämän mahdolliseksi, joten se on oletusarvoisesti käytössä. Jos sivusto ei käytä Tailwind-järjestelmää eikä lohkoresursseja, puskuroinnin voi poistaa käytöstä:

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

Arvon false palauttaminen ohittaa puskurin kokonaan. Samalla se poistaa käytöstä myös Tailwind-käännöksen sekä lohkotyylien ja -skriptien siirtämisen head-osioon ja alatunnisteeseen.

Arkkitehtuuri

Koodi
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

Täydellinen esimerkki

Täydellinen toimiva esimerkki mukautetuista teeman väreistä ja niitä käyttävästä lohkosta:

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>

Käyttöliittymässä tämä tuottaa yhden inline-<style>-tunnisteen, joka sisältää kaikki Tailwind-apuohjelmat ja mukautetut teemavärit.

Lohkokirjaston rakentaminen

Suunnittelutunnisteet, mukautetut apuluokat ja täydellinen Tailwind v4 -määritys tuotantoteemaa varten.