Към съдържанието

Мигриране към 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/ продължава да се поддържа за обратна съвместимост. Съществуващият ви код ще продължи да работи без промени. Препоръчваме обаче да преминете към префикса npm: за по-добро съответствие с цялата екосистема на JavaScript.

Префиксът 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 на страницата (което би обезсилвало кеша при всяка заявка заради 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“ е премахната. Настройката library в blockstudio.json и филтърът blockstudio/settings/library вече нямат ефект.

Ако сте използвали блоковете от библиотеката (Галерия, Слайдер, Сравнение на изображения, Код, Икона), копирайте папките с блокове от директорията includes/library/blockstudio-element/ на инсталацията на v6 в директорията blockstudio на темата си и актуализирайте файловете block.json с новите имена и категории.