Перейти до вмісту

Перехід на v7

У цьому посібнику описано зміни, які потрібно внести під час оновлення з Blockstudio 6 до версії 7.

Імпорти ES-модулів

Blockstudio 7 додає новий префікс npm: для імпортів ES-модулів, узгоджуючи його з конвенцією специфікатора Denonpm.

До (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 (швидкий regex, без компіляції)
  3. Кандидати сортуються й хешуються разом із конфігурацією CSS для створення ключа кешу
  4. Якщо кеш знайдено: зчитується кешований файл CSS і додається до виводу
  5. Якщо кешу немає: TailwindPHP компілює CSS, записує результат у спільний кеш середовища виконання Blockstudio в області tailwind і додає його до виводу

Скомпільований CSS додається як вбудований тег <style id="blockstudio-tailwind"> перед </head>. Він містить preflight від Tailwind і всі відповідні класи утиліт.

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

Змінено формат config

Властивість config змінилася з об’єкта JSON (Tailwind v3) на рядок CSS (синтаксис Tailwind v4 CSS-first).

До (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 також вилучено. Щоб додати користувацькі правила 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, указавши нові назви та категорії.