Treci la conținut

Migrarea la v7

Acest ghid prezintă modificările necesare la actualizarea de la Blockstudio 6 la 7.

Importuri ES Module

Blockstudio 7 introduce un prefix nou npm: pentru importurile ES module, aliniat la convenția Deno pentru specificatorii npm.

Înainte (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";

După (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";

Importuri CSS

Aceeași modificare se aplică importurilor CSS:

Înainte (v6):

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

După (v7):

JavaScript
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:

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

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"]:

HTML
<!-- 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:

Cod
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:

JSON
{
  "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:

  1. WordPress redă pagina completă HTML într-un buffer de ieșire
  2. Candidații pentru clasele CSS sunt extrași din HTML (regex rapid, fără compilare)
  3. Candidații sunt sortați și hașurați împreună cu configurația CSS pentru a crea o cheie de cache
  4. La un cache hit: fișierul CSS din cache este citit și inserat
  5. 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):

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

După (v7):

JSON
{
  "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):

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

După (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; } }"
  }
}

Sau prin filtrul pentru configurații pe mai multe linii:

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

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.