Переход на v7
В этом руководстве описаны изменения, которые нужно внести при обновлении с Blockstudio 6 до версии 7.
Импорт ES-модулей
Новый префикс npm: (рекомендуется)
Blockstudio 7 вводит новый префикс npm: для импорта ES-модулей, приводя его в соответствие с соглашением Deno: спецификатор npm.
До (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 (быстрое сопоставление с регулярным выражением, без компиляции)
- Кандидаты сортируются и хешируются с конфигурацией CSS для создания ключа кэша
- При попадании в кэш: сохранённый файл CSS считывается и добавляется
- При промахе кэша: TailwindPHP компилирует CSS, записывает его в общий кэш среды выполнения Blockstudio в области
tailwindи добавляет
Скомпилированный CSS добавляется как встроенный тег <style id="blockstudio-tailwind"> перед </head>. Он включает предварительную нормализацию Tailwind и все найденные утилитарные классы.
Скрипт CDN остаётся активным в редакторе только для предварительного просмотра в реальном времени. На фронтенде он не загружается.
Новый формат config
Свойство config изменилось: вместо объекта JSON (Tailwind v3) теперь используется строка CSS (синтаксис «Tailwind v4 CSS»).
До (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 также удалён. Вместо него используйте фильтр blockstudio/tailwind/css, чтобы добавлять пользовательские правила CSS.
Конечная точка REST удалена
Конечная точка POST /blockstudio/v1/editor/tailwind/save удалена. Скомпилированный CSS больше не сохраняется из редактора. Если ваш пользовательский код вызывает эту конечную точку, этот вызов можно безопасно удалить.
Кэширование
В Blockstudio используется стратегия кэширования на основе кандидатов. Вместо хеширования всей страницы HTML (из-за чего кэш обновлялся бы при каждом запросе из-за одноразовых токенов и меток времени) хешируются только кандидаты на классы CSS. Это означает, что:
- Страницы с одинаковыми классами CSS используют один и тот же файл кэша
- Динамический контент (одноразовые токены, панели администратора, метки времени) не сбрасывает кэш
- Кэш сбрасывается, только если изменился набор классов 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» удалена. Настройка library в blockstudio.json и фильтр blockstudio/settings/library больше ни на что не влияют.
Если вы использовали блоки из библиотеки (галерея, слайдер, сравнение изображений, код, значок), скопируйте папки блоков из каталога includes/library/blockstudio-element/ вашей установки v6 в каталог blockstudio вашей темы и обновите файлы block.json, указав новые имена и категории.