Перейти к содержимому

Переход на v7

В этом руководстве описаны изменения, которые нужно внести при обновлении с Blockstudio 6 до версии 7.

Импорт ES-модулей

Blockstudio 7 вводит новый префикс npm: для импорта ES-модулей, приводя его в соответствие с соглашением Deno: спецификатор npm.

До (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";

После (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";

Импорт CSS

То же изменение применяется к импорту CSS:

До (v6):

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

После (v7):

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

Пример перехода:

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

Канонические теги блоков

В Blockstudio 7.6 префиксы проектов и точные псевдонимы по-прежнему доступны как точки расширения во время выполнения, но в примерах, выводе каталога, объявлениях рендеринга и диагностических сообщениях используется <bs:namespace-slug> как каноническое написание. Канонические теги содержат настоящее зарегистрированное имя блока и не зависят от фильтра конкретного хоста.

Для проекта с brand => ["theme-components"] и 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>

Отдельная команда миграции анализирует существующий проект и заменяет сокращённые обозначения каноническим написанием. Сначала она формирует отчёт, останавливается при неразрешённых случаях и изменяет только имена тегов. Описание команды, её входных данных и мер безопасности см. в разделе Миграция тегов блоков.

Имена файлов ресурсов

В 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, теперь его нужно включать явно:

JSON
{
  "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, каждый запрос к фронтенду компилируется на стороне сервера. Этапы компиляции:

  1. WordPress отображает полную страницу HTML в буфер вывода
  2. Кандидаты на классы CSS извлекаются из HTML (быстрое сопоставление с регулярным выражением, без компиляции)
  3. Кандидаты сортируются и хешируются с конфигурацией CSS для создания ключа кэша
  4. При попадании в кэш: сохранённый файл CSS считывается и добавляется
  5. При промахе кэша: TailwindPHP компилирует CSS, записывает его в общий кэш среды выполнения Blockstudio в области tailwind и добавляет

Скомпилированный CSS добавляется как встроенный тег <style id="blockstudio-tailwind"> перед </head>. Он включает предварительную нормализацию Tailwind и все найденные утилитарные классы.

Скрипт CDN остаётся активным в редакторе только для предварительного просмотра в реальном времени. На фронтенде он не загружается.

Новый формат config

Свойство config изменилось: вместо объекта JSON (Tailwind v3) теперь используется строка CSS (синтаксис «Tailwind v4 CSS»).

До (v6):

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

После (v7):

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

Настройка customClasses удалена

Настройка-массив customClasses удалена. При подходе Tailwind v4 с приоритетом CSS пользовательские утилитарные классы задаются прямо в строке config с помощью @layer utilities.

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

После (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; } }"
  }
}

Или через фильтр для многострочных конфигураций:

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

Фильтр 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, указав новые имена и категории.