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
Nová predpona npm: (odporúčané)
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):
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):
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):
import "blockstudio/swiper@11.0.0/swiper.min.css";
Potom (v7):
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:
// 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"]:
<!-- 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:
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úť:
{
"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:
- WordPress vykreslí celú stránku HTML do výstupnej vyrovnávacej pamäte
- Kandidáty tried CSS sa extrahujú z HTML (rýchly regex, bez kompilácie)
- Kandidáty sa zoradia a zahashujú spolu s konfiguráciou CSS, čím sa vytvorí kľúč vyrovnávacej pamäte
- Pri zásahu vo vyrovnávacej pamäti: načíta sa súbor CSS z vyrovnávacej pamäte a vloží sa
- Pri nedosiahnutí zásahu: TailwindPHP skompiluje CSS, zapíše ho do zdieľanej runtime vyrovnávacej pamäte Blockstudio v rozsahu
tailwinda 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):
{
"tailwind": {
"config": {
"theme": {
"extend": {
"colors": {
"primary": "pink"
}
}
}
}
}
}
Potom (v7):
{
"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):
{
"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):
{
"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:
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.