Preskočiť na obsah

Migrácia na v7

Táto príručka opisuje zmeny, ktoré treba vykonať pri aktualizácii z verzie Blockstudio 6 na verziu 7.

Importy modulov ES

Verzia Blockstudio 7 zavádza novú predponu npm: pre importy modulov ES, čím zosúlaďuje konvenciu špecifikátora npm s Deno.

Predtým (v6):

JavaScript
import { h, render } from "blockstudio/preact@10.15.1";
import htm from "blockstudio/htm@3.1.1";
import confetti from "blockstudio/canvas-confetti@1.6.0";

Potom (v7):

JavaScript
import { h, render } from "npm:preact@10.15.1";
import htm from "npm:htm@3.1.1";
import confetti from "npm:canvas-confetti@1.6.0";

Importy CSS

Rovnaká zmena sa týka aj importov CSS:

Predtým (v6):

JavaScript
import "blockstudio/swiper@11.0.0/swiper.min.css";

Potom (v7):

JavaScript
import "npm:swiper@11.0.0/swiper.min.css";

Spätná kompatibilita

Predpona blockstudio/ je naďalej podporovaná z dôvodu spätnej kompatibility. Váš existujúci kód bude fungovať aj naďalej bez zmien. Odporúčame však prejsť na predponu npm:, aby ste zachovali súlad so širším ekosystémom JavaScript.

Predpona npm: ponúka niekoľko výhod:

  • Súlad s ekosystémom – zodpovedá zavedenej konvencii Deno
  • Prehľadnosť – hneď je jasné, že importujete z npm
  • Pripravenosť na budúcnosť – predpona blockstudio/ môže byť v budúcej hlavnej verzii zastaraná

Názvy hookov

Verzia Blockstudio 7 štandardizuje všetky názvy hookov PHP tak, aby používali snake_case namiesto camelCase, čím ich zosúlaďuje so základnými konvenciami WordPress.

Zmenené názvy hookov

Starý názov (v6) Nový názov (v7)
blockstudio/blocks/components/useblockprops/render blockstudio/blocks/components/use_block_props/render
blockstudio/blocks/components/innerblocks/render blockstudio/blocks/components/inner_blocks/render
blockstudio/blocks/components/innerblocks/frontend/wrap blockstudio/blocks/components/inner_blocks/frontend/wrap
blockstudio/blocks/components/richtext/render blockstudio/blocks/components/rich_text/render
blockstudio/assets/process/scss/importPaths blockstudio/assets/process/scss/import_paths
blockstudio/settings/assets/process/scssFiles blockstudio/settings/assets/process/scss_files
blockstudio/settings/editor/formatOnSave blockstudio/settings/editor/format_on_save
blockstudio/settings/blockEditor/disableLoading blockstudio/settings/block_editor/disable_loading
blockstudio/settings/blockEditor/cssClasses blockstudio/settings/block_editor/css_classes
blockstudio/settings/blockEditor/cssVariables blockstudio/settings/block_editor/css_variables
blockstudio/settings/ai/enableContextGeneration blockstudio/settings/ai/enable_context_generation

Spätná kompatibilita

Staré názvy hookov v zápise camelCase sú naďalej podporované z dôvodu spätnej kompatibility. Váš existujúci kód bude fungovať aj naďalej bez zmien. Odporúčame však prejsť na nové názvy v zápise snake_case, aby ste zachovali jednotnosť.

Príklad migrácie:

PHP
// Before (v6)
add_filter('blockstudio/settings/blockEditor/cssClasses', function() {
    return ['my-stylesheet'];
});

// After (v7)
add_filter('blockstudio/settings/block_editor/css_classes', function() {
    return ['my-stylesheet'];
});

Kanonické značky blokov

Verzia Blockstudio 7.6 ponecháva predpony projektov a presné aliasy ako body rozšírenia za behu, no v príkladoch, výstupe katalógu, deklaráciách vykresľovania a diagnostike používa zápis <bs:namespace-slug> ako kanonický. Kanonické značky obsahujú skutočný registrovaný názov bloku a nezávisia od filtra špecifického pre hostiteľa.

Pre projekt s brand => ["theme-components"] a ui => ["bsui"]:

HTML
<!-- Legacy project shorthand -->
<brand-card>
  <ui-input />
</brand-card>

<!-- Canonical output -->
<bs:theme-components-card>
  <bs:bsui-input />
</bs:theme-components-card>

Samostatný migračný príkaz vytvorí inventár existujúceho projektu a prepíše skrátené zápisy na kanonický tvar. Najprv vytvorí prehľad, pri nevyriešených prípadoch sa zastaví a zmení iba názvy značiek. Príkaz, jeho vstupy a bezpečné správanie nájdete v časti Migrácia značiek blokov.

Pomenovanie súborov zdrojov

Verzia Blockstudio 7 zavádza bodkovú notáciu pre prípony súborov zdrojov, ktorá nahrádza starú pomlčkovú notáciu ako odporúčanú konvenciu.

Zmenené názvy súborov

Starý názov (v6) Nový názov (v7)
*-inline.(s)css *.inline.(s)css
*-inline.js *.inline.js
*-editor.(s)css *.editor.(s)css
*-editor.js *.editor.js
*-scoped.(s)css *.scoped.(s)css
*-view.js *.view.js

Spätná kompatibilita

Starý zápis s pomlčkou je naďalej podporovaný z dôvodu spätnej kompatibility. Vaše existujúce súbory budú fungovať aj naďalej bez premenovania. Pre nové bloky však odporúčame prejsť na bodkovú notáciu.

Príklad migrácie:

Kód
my-block/
├── block.json
├── index.php
├── style.css
├── style-inline.css   →  style.inline.css
├── style-scoped.css   →  style.scoped.css
├── style-editor.css   →  style.editor.css
├── script.js
├── script-inline.js   →  script.inline.js
├── script-editor.js   →  script.editor.js
└── script-view.js     →  script.view.js

Prepínač poľa

Predvolená hodnota vlastnosti switch je teraz false namiesto true. Vo verzii v6 malo každé pole na ľavom okraji neviditeľný prepínač, ktorý bol predvolene zapnutý. Vo verzii v7 je prepínač voliteľný a v označení poľa sa používa viditeľná ikona oka.

Čo sa zmenilo

  • Predvolená hodnota je teraz false: polia už nemajú prepínač, pokiaľ výslovne nenastavíte "switch": true
  • Viditeľná ikona oka: namiesto skrytej klikateľnej oblasti na ľavej strane sa v oblasti označenia zobrazí tlačidlo s ikonou oka
  • Prekrytie pri vypnutí: keď je pole vypnuté, zobrazí sa rozmazané prekrytie s textom „Toto pole je vypnuté“ namiesto samotného zníženia nepriehľadnosti

Migrácia

Ak ste sa vo verzii v6 spoliehali na predvolené správanie prepínača, musíte ho výslovne zapnúť:

JSON
{
  "id": "title",
  "type": "text",
  "label": "Title",
  "switch": true
}

Ak ste predtým nastavili "switch": false, aby sa prepínač vypol, môžete toto nastavenie odstrániť, pretože false je teraz predvolená hodnota.

Tailwind CSS

Verzia Blockstudio 7 úplne nahrádza prístup v6 Tailwind. Vo verzii v6 sa Tailwind CSS kompilovalo na strane klienta pomocou CDN v editore a pri uložení príspevku sa ukladalo na disk. Vo verzii v7 sa Tailwind CSS kompiluje na strane servera pri každej požiadavke na frontend prostredníctvom TailwindPHP s automatickým ukladaním do vyrovnávacej pamäte podľa súborov.

Podrobné informácie o novom systéme nájdete v dokumentácii Tailwind CSS.

Kompilácia na strane servera vždy zapnutá

Keď má tailwind.enabled hodnotu true, každá požiadavka na frontend sa kompiluje na strane servera. Postup kompilácie:

  1. WordPress vykreslí celú stránku HTML do výstupnej vyrovnávacej pamäte
  2. Kandidáty tried CSS sa extrahujú z HTML (rýchly regex, bez kompilácie)
  3. Kandidáty sa zoradia a zahashujú spolu s konfiguráciou CSS, čím sa vytvorí kľúč vyrovnávacej pamäte
  4. Pri zásahu vo vyrovnávacej pamäti: načíta sa súbor CSS z vyrovnávacej pamäte a vloží sa
  5. Pri nedosiahnutí zásahu: TailwindPHP skompiluje CSS, zapíše ho do zdieľanej runtime vyrovnávacej pamäte Blockstudio v rozsahu tailwind a vloží ho

Skompilované CSS sa vloží ako vložená značka <style id="blockstudio-tailwind"> pred </head>. Zahŕňa preflight Tailwind a všetky zodpovedajúce pomocné triedy.

Skript CDN zostáva aktívny v editore len na účely živého náhľadu. Na frontende sa nikdy neposkytuje.

Zmenený formát config

Vlastnosť config sa zmenila z objektu JSON (Tailwind v3) na reťazec CSS (syntaxa najprv Tailwind v4 CSS).

Predtým (v6):

JSON
{
  "tailwind": {
    "config": {
      "theme": {
        "extend": {
          "colors": {
            "primary": "pink"
          }
        }
      }
    }
  }
}

Potom (v7):

JSON
{
  "tailwind": {
    "config": "@theme { --color-primary: pink; }"
  }
}

Nastavenie customClasses bolo odstránené

Nastavenie poľa customClasses bolo odstránené. V prístupe CSS na prvom mieste v Tailwind v4 sa vlastné pomocné triedy definujú priamo v reťazci config pomocou @layer utilities.

Predtým (v6):

JSON
{
  "tailwind": {
    "customClasses": [
      { "className": "btn", "value": "px-4 py-2 rounded-lg font-medium" },
      { "className": "card", "value": "bg-white rounded-xl shadow-lg p-6" }
    ]
  }
}

Potom (v7):

JSON
{
  "tailwind": {
    "config": "@layer utilities { .btn { @apply px-4 py-2 rounded-lg font-medium; } .card { @apply bg-white rounded-xl shadow-lg p-6; } }"
  }
}

Alebo pomocou filtra pre viacriadkové konfigurácie:

PHP
add_filter('blockstudio/settings/tailwind/config', function () {
    return <<<CSS
@layer utilities {
    .btn { @apply px-4 py-2 rounded-lg font-medium; }
    .card { @apply bg-white rounded-xl shadow-lg p-6; }
}
CSS;
});

Filter blockstudio/settings/tailwind/custom_classes bol tiež odstránený. Ak chcete pridať vlastné pravidlá CSS, použite namiesto neho filter blockstudio/tailwind/css.

Koncový bod REST bol odstránený

Koncový bod POST /blockstudio/v1/editor/tailwind/save bol odstránený. Skompilované CSS sa už z editora neukladá. Ak ste mali vlastný kód, ktorý tento koncový bod volal, môžete ho bezpečne odstrániť.

Ukladanie do vyrovnávacej pamäte

Blockstudio používa stratégiu ukladania do vyrovnávacej pamäte založenú na kandidátoch. Namiesto zahashovania celého HTML stránky (čo by pri každej požiadavke zrušilo platnosť vyrovnávacej pamäte kvôli nonce hodnotám a časovým pečiatkam) sa hashujú iba kandidáti tried CSS. To znamená:

  • Dve stránky s rovnakými triedami CSS zdieľajú rovnaký súbor vo vyrovnávacej pamäti
  • Dynamický obsah (nonce hodnoty, panely správcu, časové pečiatky) nezruší platnosť vyrovnávacej pamäte
  • Vyrovnávacia pamäť sa zneplatní len vtedy, keď sa zmení množina tried CSS alebo konfigurácia

Súbory vyrovnávacej pamäte používajú nakonfigurovaný koreňový adresár runtime Blockstudio v umiestnení sites/{network-blog}/{runtime-identity}/tailwind/. Volaním Blockstudio\Runtime_Cache::purge('tailwind') vynútite opätovnú kompiláciu.

Zmeny filtrov

Starý názov (v6) Nový názov (v7)
blockstudio/tailwind/on_demand/css blockstudio/tailwind/css
blockstudio/tailwind/assets/dir Odstránené
blockstudio/settings/tailwind/custom_classes Odstránené

Odstránené súbory a načítania

Vo verzii v6 sa Tailwind CSS načítavalo ako externé štýlopisy (blockstudio-tailwind, blockstudio-tailwind-preflight). Vo verzii v7 sa celé CSS vkladá priamo do výstupnej vyrovnávacej pamäte. Na frontende sa pre Tailwind nevytvárajú žiadne značky odkazov ani nenačítavajú štýlopisy.

Knižnica blokov

Vstavaná knižnica „Blockstudio Elements“ bola odstránená. Nastavenie library vo verzii blockstudio.json a filter blockstudio/settings/library už nemajú žiadny účinok.

Ak ste používali bloky z knižnice (Galéria, Prezentácia, Porovnanie obrázkov, Kód, Ikona), skopírujte priečinky blokov z inštalačného adresára v6 includes/library/blockstudio-element/ do adresára blockstudio svojej témy a aktualizujte ich súbory block.json s novými názvami a kategóriami.