Migracja do v7
Ten przewodnik opisuje zmiany wymagane przy aktualizacji z Blockstudio 6 do 7.
Importy modułów ES
Nowy prefiks npm: (zalecany)
Blockstudio 7 wprowadza nowy prefiks npm: dla importów modułów ES, zgodny z konwencją specyfikatora Denonpm.
Przed (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";
Po (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
Ta sama zmiana dotyczy importów CSS:
Przed (v6):
import "blockstudio/swiper@11.0.0/swiper.min.css";
Po (v7):
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:
// 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"]:
<!-- 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:
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ć:
{
"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:
- WordPress renderuje całą stronę HTML do bufora wyjściowego
- Kandydaty klas CSS są wyodrębniane z HTML (szybkie wyrażenie regularne, bez kompilacji)
- Kandydaci są sortowani i haszowani wraz z konfiguracją CSS, aby utworzyć klucz pamięci podręcznej
- Przy trafieniu w pamięć podręczną: odczytywany jest plik CSS z pamięci podręcznej i wstawiany
- Przy braku trafienia: TailwindPHP kompiluje CSS, zapisuje go we współdzielonej pamięci podręcznej środowiska uruchomieniowego Blockstudio w zakresie
tailwindi 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):
{
"tailwind": {
"config": {
"theme": {
"extend": {
"colors": {
"primary": "pink"
}
}
}
}
}
}
Po (v7):
{
"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):
{
"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):
{
"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:
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.