Перехід на v7
У цьому посібнику описано зміни, які потрібно внести під час оновлення з Blockstudio 6 до версії 7.
Імпорти ES-модулів
Новий префікс npm: (рекомендовано)
Blockstudio 7 додає новий префікс npm: для імпортів ES-модулів, узгоджуючи його з конвенцією специфікатора Denonpm.
До (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";
Після (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";
Імпорти CSS
Така сама зміна стосується імпортів CSS:
До (v6):
import "blockstudio/swiper@11.0.0/swiper.min.css";
Після (v7):
import "npm:swiper@11.0.0/swiper.min.css";
Зворотна сумісність
Префікс blockstudio/ і далі підтримується для зворотної сумісності. Ваш наявний код працюватиме без змін. Однак для узгодженості з ширшою екосистемою JavaScript рекомендуємо перейти на префікс npm:.
Префікс npm: має кілька переваг:
- Узгодженість з екосистемою — відповідає усталеній домовленості Deno
- Зрозумілість — одразу видно, що імпорт відбувається з npm
- Готовність до майбутніх змін — у майбутній основній версії префікс
blockstudio/можуть вилучити
Назви хуків
У Blockstudio 7 назви всіх хуків PHP приведено до стандарту: тепер вони використовують snake_case замість camelCase, відповідно до основних домовленостей WordPress.
Змінені назви хуків
| Стара назва (v6) | Нова назва (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 |
Зворотна сумісність
Старі назви хуків у camelCase і далі підтримуються для зворотної сумісності. Ваш наявний код працюватиме без змін. Однак для узгодженості рекомендуємо перейти на нові назви у snake_case.
Приклад переходу:
// 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'];
});
Канонічні теги блоків
Blockstudio 7.6 і далі підтримує префікси проєкту й точні псевдоніми як точки розширення під час виконання, але у прикладах, виводі каталогу, оголошеннях рендерингу та діагностиці використовує канонічне написання <bs:namespace-slug>. Канонічні теги містять справжню зареєстровану назву блоку й не залежать від фільтра, специфічного для хост-середовища.
Для проєкту з brand => ["theme-components"] і ui => ["bsui"]:
<!-- Legacy project shorthand -->
<brand-card>
<ui-input />
</brand-card>
<!-- Canonical output -->
<bs:theme-components-card>
<bs:bsui-input />
</bs:theme-components-card>
Окрема команда переходу аналізує наявний проєкт і замінює скорочені форми на канонічне написання. Спочатку вона формує звіт, зупиняється за наявності невирішених випадків і змінює лише назви тегів. Опис команди, її входів і правил безпечної роботи дивіться в розділі Перехід тегів блоків.
Назви файлів ресурсів
У Blockstudio 7 крапкову нотацію суфіксів файлів ресурсів рекомендовано замість старої нотації з дефісом.
Змінені назви файлів
| Стара назва (v6) | Нова назва (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 |
Зворотна сумісність
Стара нотація з дефісом і далі підтримується для зворотної сумісності. Ваші наявні файли працюватимуть і без перейменування. Однак для нових блоків рекомендуємо перейти на крапкову нотацію.
Приклад переходу:
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
Перемикач поля
Тепер властивість switch за замовчуванням має значення false замість true. У v6 кожне поле мало невидимий перемикач на лівому краї, увімкнений за замовчуванням. У v7 перемикач потрібно ввімкнути окремо; він позначений видимою іконкою ока в мітці поля.
Що змінилося
- Тепер вимкнено за замовчуванням
false: поля більше не мають перемикача, якщо ви явно не задасте"switch": true - Видима іконка ока: замість прихованої зони натискання ліворуч у ділянці мітки з’являється кнопка з іконкою ока
- Затемнення вимкненого поля: коли поле вимкнене, поверх нього відображається розмитий шар із текстом "Це поле вимкнено", а не просто зменшується його непрозорість
Перехід
Якщо ви покладалися на перемикач, увімкнений за замовчуванням у v6, потрібно явно ввімкнути його:
{
"id": "title",
"type": "text",
"label": "Title",
"switch": true
}
Якщо раніше ви задавали "switch": false, щоб вимкнути перемикач, це значення можна прибрати, оскільки тепер за замовчуванням використовується false.
Tailwind CSS
У Blockstudio 7 повністю замінено підхід v6 Tailwind. У v6 Tailwind CSS компілювався на стороні клієнта через CDN у редакторі й зберігався на диску після збереження запису. У v7 Tailwind CSS компілюється на сервері під час кожного запиту до фронтенду через TailwindPHP з автоматичним кешуванням на основі файлів.
Докладніше про нову систему читайте в Tailwind CSS документації.
Постійна компіляція на сервері
Коли tailwind.enabled має значення true, кожен запит до фронтенду компілюється на сервері. Процес компіляції:
- WordPress рендерить повну сторінку HTML у буфер виводу
- Кандидати класів CSS витягуються з HTML (швидкий regex, без компіляції)
- Кандидати сортуються й хешуються разом із конфігурацією CSS для створення ключа кешу
- Якщо кеш знайдено: зчитується кешований файл CSS і додається до виводу
- Якщо кешу немає: TailwindPHP компілює CSS, записує результат у спільний кеш середовища виконання Blockstudio в області
tailwindі додає його до виводу
Скомпільований CSS додається як вбудований тег <style id="blockstudio-tailwind"> перед </head>. Він містить preflight від Tailwind і всі відповідні класи утиліт.
Скрипт CDN залишається активним у редакторі лише для попереднього перегляду наживо. На фронтенді він ніколи не передається.
Змінено формат config
Властивість config змінилася з об’єкта JSON (Tailwind v3) на рядок CSS (синтаксис Tailwind v4 CSS-first).
До (v6):
{
"tailwind": {
"config": {
"theme": {
"extend": {
"colors": {
"primary": "pink"
}
}
}
}
}
}
Після (v7):
{
"tailwind": {
"config": "@theme { --color-primary: pink; }"
}
}
Налаштування customClasses вилучено
Налаштування-масив customClasses вилучено. За підходу Tailwind v4, де на першому місці CSS, користувацькі класи утиліт визначаються безпосередньо в рядку config за допомогою @layer utilities.
До (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" }
]
}
}
Після (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; } }"
}
}
Або за допомогою фільтра для багаторядкових конфігурацій:
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;
});
Фільтр blockstudio/settings/tailwind/custom_classes також вилучено. Щоб додати користувацькі правила CSS, використовуйте фільтр blockstudio/tailwind/css.
Кінцеву точку REST вилучено
Кінцеву точку POST /blockstudio/v1/editor/tailwind/save вилучено. Скомпільований CSS більше не зберігається з редактора. Якщо у вас був користувацький код, який викликав цю кінцеву точку, його можна безпечно прибрати.
Кешування
Blockstudio використовує стратегію кешування на основі кандидатів. Замість хешування всього HTML сторінки (через nonce і мітки часу це скидало б кеш під час кожного запиту) хешуються лише кандидати класів CSS. Це означає:
- Дві сторінки з однаковими класами CSS використовують спільний кешований файл
- Динамічний вміст (nonce, панелі адміністратора, мітки часу) не скидає кеш
- Кеш стає недійсним лише тоді, коли змінюється набір класів CSS або конфігурація
Файли кешу зберігаються у налаштованому кореневому каталозі середовища виконання Blockstudio у
sites/{network-blog}/{runtime-identity}/tailwind/. Викличте
Blockstudio\Runtime_Cache::purge('tailwind'), щоб примусово виконати повторну компіляцію.
Зміни фільтрів
| Стара назва (v6) | Нова назва (v7) |
|---|---|
blockstudio/tailwind/on_demand/css |
blockstudio/tailwind/css |
blockstudio/tailwind/assets/dir |
Вилучено |
blockstudio/settings/tailwind/custom_classes |
Вилучено |
Вилучені файли та ресурси в черзі
У v6 Tailwind CSS додавався до черги як зовнішні таблиці стилів (blockstudio-tailwind, blockstudio-tailwind-preflight). У v7 увесь CSS додається вбудовано через буфер виводу. На фронтенді для Tailwind немає тегів посилань чи таблиць стилів, доданих до черги.
Бібліотека блоків
Вбудовану бібліотеку “Blockstudio Elements” вилучено. Налаштування library у blockstudio.json і фільтр blockstudio/settings/library більше не впливають на роботу.
Якщо ви використовували блоки бібліотеки (Gallery, Slider, Image Comparison, Code, Icon), скопіюйте папки блоків зі встановленої версії v6, з каталогу includes/library/blockstudio-element/, до каталогу blockstudio вашої теми й оновіть їхні файли block.json, указавши нові назви та категорії.