Migrarea la v7
Acest ghid prezintă modificările necesare la actualizarea de la Blockstudio 6 la 7.
Importuri ES Module
Prefix nou npm: (recomandat)
Blockstudio 7 introduce un prefix nou npm: pentru importurile ES module, aliniat la convenția Deno pentru specificatorii npm.
Înainte (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";
După (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";
Importuri CSS
Aceeași modificare se aplică importurilor CSS:
Înainte (v6):
import "blockstudio/swiper@11.0.0/swiper.min.css";
După (v7):
import "npm:swiper@11.0.0/swiper.min.css";
Compatibilitate inversă
Prefixul blockstudio/ este în continuare acceptat pentru compatibilitate inversă. Codul existent va continua să funcționeze fără modificări. Totuși, vă recomandăm să migrați la prefixul npm: pentru a vă alinia la ecosistemul JavaScript mai larg.
Prefixul npm: oferă mai multe avantaje:
- Aliniere la ecosistem – Respectă convenția consacrată a Deno
- Claritate – Arată imediat că importați din npm
- Pregătire pentru viitor – Prefixul
blockstudio/poate fi învechit într-o versiune majoră viitoare
Numele hookurilor
Blockstudio 7 standardizează toate numele hookurilor PHP, folosind snake_case în loc de camelCase, în conformitate cu convențiile de bază WordPress.
Nume de hookuri modificate
| Nume vechi (v6) | Nume nou (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 |
Compatibilitate inversă
Numele vechi de hookuri în camelCase sunt acceptate în continuare pentru compatibilitate inversă. Codul existent va funcționa în continuare fără modificări. Totuși, vă recomandăm să migrați la noile nume în snake_case pentru consecvență.
Exemplu de migrare:
// 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'];
});
Etichete canonice de blocuri
Blockstudio 7.6 păstrează prefixele proiectului și aliasurile exacte ca puncte de extensie la runtime, dar folosește <bs:namespace-slug> drept formă canonică în exemple, rezultatele catalogului, declarațiile de randare și diagnosticări. Etichetele canonice poartă numele real al blocului înregistrat și nu depind de un filtru specific gazdei.
Pentru un proiect cu brand => ["theme-components"] și ui => ["bsui"]:
<!-- Legacy project shorthand -->
<brand-card>
<ui-input />
</brand-card>
<!-- Canonical output -->
<bs:theme-components-card>
<bs:bsui-input />
</bs:theme-components-card>
O comandă de migrare autonomă inventariază un proiect existent și rescrie prescurtările în forma canonică. Mai întâi generează un raport, se oprește în cazurile nerezolvate și modifică doar numele etichetelor. Consultați Migrarea etichetelor de blocuri pentru comandă, datele de intrare și comportamentul de siguranță.
Denumirea fișierelor cu resurse
Blockstudio 7 introduce notația cu punct pentru sufixele fișierelor cu resurse, înlocuind notația veche cu cratimă, recomandată până acum.
Nume de fișiere modificate
| Nume vechi (v6) | Nume nou (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 |
Compatibilitate inversă
Notația veche cu cratimă este acceptată în continuare pentru compatibilitate inversă. Fișierele existente vor funcționa fără să le redenumiți. Totuși, vă recomandăm să migrați la notația cu punct pentru blocurile noi.
Exemplu de migrare:
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
Comutatorul câmpului
Proprietatea switch are acum valoarea implicită false în loc de true. În v6, fiecare câmp avea în mod implicit un comutator invizibil pe marginea din stânga. În v7, comutatorul este opțional și folosește o pictogramă vizibilă cu ochi în eticheta câmpului.
Ce s-a schimbat
- Valoarea implicită este acum
false: câmpurile nu mai au un comutator dacă nu setați explicit"switch": true - Pictogramă vizibilă cu ochi: în locul unei zone de clic ascunse în stânga, în zona etichetei apare un buton cu pictogramă de ochi
- Suprapunere pentru dezactivare: când un câmp este dezactivat, apare o suprapunere neclară cu textul „Acest câmp este dezactivat”, în loc să i se reducă doar opacitatea
Migrare
Dacă vă bazați pe comportamentul implicit al comutatorului din v6, trebuie să îl activați explicit:
{
"id": "title",
"type": "text",
"label": "Title",
"switch": true
}
Dacă ați setat anterior "switch": false pentru a dezactiva comutatorul, îl puteți elimina, deoarece false este acum valoarea implicită.
Tailwind CSS
Blockstudio 7 înlocuiește complet abordarea v6 Tailwind. În v6, Tailwind CSS era compilat pe partea clientului prin CDN în editor și salvat pe disc la salvarea articolului. În v7, Tailwind CSS este compilat pe partea serverului la fiecare solicitare frontend prin TailwindPHP, cu memorare automată în cache pe baza fișierelor.
Pentru toate detaliile despre noul sistem, consultați documentația Tailwind CSS.
Compilare permanentă pe partea serverului
Când tailwind.enabled este true, fiecare solicitare frontend este compilată pe partea serverului. Fluxul compilării:
- WordPress redă pagina completă HTML într-un buffer de ieșire
- Candidații pentru clasele CSS sunt extrași din HTML (regex rapid, fără compilare)
- Candidații sunt sortați și hașurați împreună cu configurația CSS pentru a crea o cheie de cache
- La un cache hit: fișierul CSS din cache este citit și inserat
- La un cache miss: TailwindPHP compilează CSS, îl scrie în cache-ul partajat de runtime al Blockstudio, în domeniul
tailwind, apoi îl inserează
CSS compilat este inserat ca etichetă inline <style id="blockstudio-tailwind"> înainte de </head>. Include preflight-ul Tailwind și toate clasele utilitare potrivite.
Scriptul CDN rămâne activ în editor doar pentru previzualizarea în timp real. Nu este niciodată livrat în frontend.
Formatul config s-a schimbat
Proprietatea config s-a schimbat dintr-un obiect JSON (Tailwind v3) într-un șir CSS (sintaxă Tailwind v4-first CSS).
Înainte (v6):
{
"tailwind": {
"config": {
"theme": {
"extend": {
"colors": {
"primary": "pink"
}
}
}
}
}
}
După (v7):
{
"tailwind": {
"config": "@theme { --color-primary: pink; }"
}
}
Setarea customClasses a fost eliminată
Setarea de tip array customClasses a fost eliminată. Odată cu abordarea Tailwind v4 de tip CSS-first, clasele utilitare personalizate sunt definite direct în șirul config folosind @layer utilities.
Înainte (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" }
]
}
}
După (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; } }"
}
}
Sau prin filtrul pentru configurații pe mai multe linii:
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;
});
Filtrul blockstudio/settings/tailwind/custom_classes a fost, de asemenea, eliminat. Folosiți în schimb filtrul blockstudio/tailwind/css pentru a adăuga reguli personalizate CSS.
Endpointul REST a fost eliminat
Endpointul POST /blockstudio/v1/editor/tailwind/save a fost eliminat. CSS compilat nu mai este salvat din editor. Dacă aveați cod personalizat care apela acest endpoint, îl puteți elimina în siguranță.
Memorare în cache
Blockstudio folosește o strategie de memorare în cache bazată pe candidați. În loc să hașureze întregul HTML al paginii (ceea ce ar invalida cache-ul la fiecare solicitare din cauza nonce-urilor și marcajelor temporale), sunt hașurați doar candidații pentru clasele CSS. Asta înseamnă că:
- Două pagini cu aceleași clase CSS folosesc același fișier din cache
- Conținutul dinamic (nonce-uri, bare de administrare, marcaje temporale) nu invalidează cache-ul
- Cache-ul este invalidat doar când se schimbă setul de clase CSS sau configurația
Fișierele cache folosesc rădăcina runtime configurată pentru Blockstudio, în sites/{network-blog}/{runtime-identity}/tailwind/. Apelați Blockstudio\Runtime_Cache::purge('tailwind') pentru a forța recompilarea.
Modificări ale filtrelor
| Nume vechi (v6) | Nume nou (v7) |
|---|---|
blockstudio/tailwind/on_demand/css |
blockstudio/tailwind/css |
blockstudio/tailwind/assets/dir |
Eliminat |
blockstudio/settings/tailwind/custom_classes |
Eliminat |
Fișiere și încărcări eliminate
În v6, Tailwind CSS era încărcat ca foi de stil externe (blockstudio-tailwind, blockstudio-tailwind-preflight). În v7, tot CSS este inserat inline printr-un buffer de ieșire. În frontend nu există etichete link sau foi de stil încărcate pentru Tailwind.
Biblioteca de blocuri
Biblioteca încorporată „Elemente Blockstudio” a fost eliminată. Setarea library din blockstudio.json și filtrul blockstudio/settings/library nu mai au niciun efect.
Dacă foloseați blocurile bibliotecii (Galerie, Slider, Comparare imagini, Cod, Pictogramă), copiați dosarele blocurilor din directorul includes/library/blockstudio-element/ al instalării v6 în directorul blockstudio al temei și actualizați fișierele block.json cu nume și categorii noi.