Przejdź do treści

Migracja do v7

Ten przewodnik opisuje zmiany wymagane przy aktualizacji z Blockstudio 6 do 7.

Importy modułów ES

Blockstudio 7 wprowadza nowy prefiks npm: dla importów modułów ES, zgodny z konwencją specyfikatora Denonpm.

Przed (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";

Po (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

Ta sama zmiana dotyczy importów CSS:

Przed (v6):

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

Po (v7):

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

Zgodność wsteczna

Prefiks blockstudio/ jest nadal obsługiwany ze względu na zgodność wsteczną. Istniejący kod będzie działał bez zmian. Zalecamy jednak migrację do prefiksu npm:, aby zachować spójność z szerszym ekosystemem JavaScript.

Prefiks npm: ma kilka zalet:

  • Zgodność z ekosystemem – odpowiada utrwalonej konwencji Deno
  • Czytelność – od razu widać, że importujesz z npm
  • Przygotowanie na przyszłość – prefiks blockstudio/ może zostać wycofany w przyszłej wersji głównej

Nazwy hooków

Blockstudio 7 ujednolica nazwy wszystkich hooków PHP: używa snake_case zamiast camelCase, zgodnie z konwencjami rdzenia WordPress.

Zmienione nazwy hooków

Stara nazwa (v6) Nowa nazwa (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

Zgodność wsteczna

Stare nazwy hooków w formacie camelCase są nadal obsługiwane ze względu na zgodność wsteczną. Istniejący kod będzie działał bez zmian. Zalecamy jednak migrację do nowych nazw w formacie snake_case, aby zachować spójność.

Przykład migracji:

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

Kanoniczne tagi bloków

Blockstudio 7.6 nadal obsługuje prefiksy projektu i dokładne aliasy jako punkty rozszerzeń w czasie działania, ale w przykładach, wynikach katalogu, deklaracjach renderowania i diagnostyce używa <bs:namespace-slug> jako kanonicznej pisowni. Kanoniczne tagi zawierają rzeczywistą zarejestrowaną nazwę bloku i nie zależą od filtra specyficznego dla hosta.

Dla projektu z 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>

Samodzielne polecenie migracji inwentaryzuje istniejący projekt i zamienia skrócone formy na zapis kanoniczny. Najpierw tworzy raport, zatrzymuje się w przypadku nierozstrzygniętych sytuacji i zmienia wyłącznie nazwy tagów. Informacje o poleceniu, jego danych wejściowych i zasadach bezpiecznego działania znajdziesz w sekcji Migracja tagów bloków.

Nazewnictwo plików zasobów

Blockstudio 7 wprowadza kropki w sufiksach nazw plików zasobów, zastępując dawne myślniki jako zalecaną konwencję.

Zmienione nazwy plików

Stara nazwa (v6) Nowa nazwa (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

Zgodność wsteczna

Zapis z myślnikami jest nadal obsługiwany ze względu na zgodność wsteczną. Istniejące pliki będą działać bez zmiany nazw. Zalecamy jednak stosowanie zapisu z kropkami w nowych blokach.

Przykład migracji:

Kod
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

Przełącznik pola

Właściwość switch ma teraz domyślnie wartość false zamiast true. W v6 każde pole miało niewidoczny przełącznik przy lewej krawędzi, domyślnie włączony. W v7 przełącznik jest opcjonalny i używa widocznej ikony oka w etykiecie pola.

Co się zmieniło

  • Domyślnie false: pola nie mają już przełącznika, chyba że jawnie ustawisz "switch": true
  • Widoczna ikona oka: zamiast ukrytego obszaru klikalnego po lewej stronie w obszarze etykiety pojawia się przycisk z ikoną oka
  • Nakładka wyłączenia: gdy pole jest wyłączone, wyświetlana jest rozmyta nakładka z tekstem „To pole jest wyłączone” zamiast samego zmniejszenia krycia

Migracja

Jeśli polegałeś na domyślnym działaniu przełącznika w v6, musisz jawnie go włączyć:

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

Jeśli wcześniej ustawiono "switch": false, aby wyłączyć przełącznik, można usunąć to ustawienie, ponieważ false jest teraz wartością domyślną.

Tailwind CSS

Blockstudio 7 całkowicie zastępuje podejście v6 Tailwind. W v6 Tailwind CSS było kompilowane po stronie klienta za pomocą CDN w edytorze i zapisywane na dysku po zapisaniu wpisu. W v7 Tailwind CSS jest kompilowane po stronie serwera przy każdym żądaniu frontendu za pomocą TailwindPHP, z automatycznym buforowaniem opartym na plikach.

Pełne informacje o nowym systemie znajdziesz w dokumentacji Tailwind CSS.

Kompilacja po stronie serwera przy każdym żądaniu

Gdy tailwind.enabled ma wartość true, każde żądanie frontendu jest kompilowane po stronie serwera. Proces kompilacji:

  1. WordPress renderuje całą stronę HTML do bufora wyjściowego
  2. Kandydaty klas CSS są wyodrębniane z HTML (szybkie wyrażenie regularne, bez kompilacji)
  3. Kandydaci są sortowani i haszowani wraz z konfiguracją CSS, aby utworzyć klucz pamięci podręcznej
  4. Przy trafieniu w pamięć podręczną: odczytywany jest plik CSS z pamięci podręcznej i wstawiany
  5. Przy braku trafienia: TailwindPHP kompiluje CSS, zapisuje go we współdzielonej pamięci podręcznej środowiska uruchomieniowego Blockstudio w zakresie tailwind i wstawia

Skompilowany CSS jest wstawiany jako wbudowany tag <style id="blockstudio-tailwind"> przed </head>. Obejmuje to preflight Tailwind i wszystkie dopasowane klasy narzędziowe.

Skrypt CDN pozostaje aktywny w edytorze wyłącznie na potrzeby podglądu na żywo. Nigdy nie jest udostępniany na frontendzie.

Zmiana formatu config

Właściwość config zmieniła format z obiektu JSON (Tailwind v3) na ciąg CSS (składnia Tailwind v4 CSS-first).

Przed (v6):

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

Po (v7):

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

Usunięcie ustawienia customClasses

Ustawienie tablicowe customClasses zostało usunięte. W podejściu Tailwind v4 CSS-first własne klasy narzędziowe definiuje się bezpośrednio w ciągu config za pomocą @layer utilities.

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

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

Lub za pomocą filtra w przypadku konfiguracji wielowierszowych:

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

Filtr blockstudio/settings/tailwind/custom_classes również został usunięty. Zamiast niego użyj filtra blockstudio/tailwind/css, aby dodać własne reguły CSS.

Usunięcie endpointu REST

Endpoint POST /blockstudio/v1/editor/tailwind/save został usunięty. Skompilowane CSS nie jest już zapisywane z edytora. Jeśli własny kod wywołuje ten endpoint, można go bezpiecznie usunąć.

Buforowanie

Blockstudio stosuje strategię buforowania opartą na kandydatach. Zamiast haszować całe HTML strony (co unieważniałoby pamięć podręczną przy każdym żądaniu z powodu nonce i znaczników czasu), haszowane są tylko kandydaty klas CSS. Oznacza to, że:

  • Dwie strony z tymi samymi klasami CSS współdzielą ten sam plik z pamięci podręcznej
  • Treści dynamiczne (nonce, paski administratora, znaczniki czasu) nie unieważniają pamięci podręcznej
  • Pamięć podręczna jest unieważniana tylko wtedy, gdy zmieni się zbiór klas CSS lub konfiguracja

Pliki pamięci podręcznej korzystają ze skonfigurowanego katalogu głównego środowiska uruchomieniowego Blockstudio w lokalizacji sites/{network-blog}/{runtime-identity}/tailwind/. Wywołaj Blockstudio\Runtime_Cache::purge('tailwind'), aby wymusić ponowną kompilację.

Zmiany filtrów

Stara nazwa (v6) Nowa nazwa (v7)
blockstudio/tailwind/on_demand/css blockstudio/tailwind/css
blockstudio/tailwind/assets/dir Usunięto
blockstudio/settings/tailwind/custom_classes Usunięto

Usunięte pliki i dołączane zasoby

W v6 Tailwind CSS był dołączany jako zewnętrzne arkusze stylów (blockstudio-tailwind, blockstudio-tailwind-preflight). W v7 wszystkie CSS są wstawiane bezpośrednio przez bufor wyjściowy. Na frontendzie nie ma tagów linków ani dołączanych arkuszy stylów dla Tailwind.

Biblioteka bloków

Wbudowana biblioteka „Elementy Blockstudio” została usunięta. Ustawienie library w blockstudio.json oraz filtr blockstudio/settings/library nie mają już żadnego wpływu.

Jeśli używano bloków biblioteki (Galeria, Karuzela, Porównanie obrazów, Kod, Ikona), skopiuj foldery bloków z katalogu includes/library/blockstudio-element/ instalacji v6 do katalogu blockstudio w motywie i zaktualizuj ich pliki block.json, podając nowe nazwy i kategorie.