useBlockProps
За замовчуванням Gutenberg має створювати обгортку навколо блоків, щоб зробити їх інтерактивними в редакторі. Це може створювати проблеми з деякими типами блоків, як-от контейнерами чи колонками, адже розмітка в редакторі та на фронтенді відрізнятиметься. Хук useBlockProps дає змогу позначити елемент у шаблоні блока як кореневий, забезпечуючи однакову розмітку в редакторі та на фронтенді.
Використання
Просто додайте атрибут useBlockProps до кореневого елемента блока.
<div useBlockProps class="my-class">
<!--
This element will be rendered
as the root element of your block
in Gutenberg.
-->
</div>
Blockstudio автоматично об’єднає класи й атрибути редактора (класи вирівнювання тощо) з тим, що визначено в шаблонах блоків. Для цього під капотом використовується get_block_wrapper_attributes.
Фільтр blockstudio/blocks/components/use_block_props/render застосовується до обгортки під час виведення як на фронтенді, так і в редакторі. Тому класи, додані темою або інтеграцією для окремого екземпляра, відображаються і на полотні редактора, і в збереженій розмітці фронтенду.
Результат:
<div class="my-class wp-block-your-block-name alignright">
</div>
Важливі зауваження
Посилання в редакторі
Blockstudio вимикає переходи за посиланнями в редакторі блоків, зокрема
target="_blank", кліки з клавішею-модифікатором, кліки середньою кнопкою миші та активацію з клавіатури.
Події кліку все одно надходять до Gutenberg, тому звичайний клік вибирає блок.
RichText залишається доступним для редагування. Це працює як із useBlockProps, так і без нього,
зокрема коли якірний елемент є кореневим елементом блоку.
Посилання на зовнішній сторінці та команди контекстного меню браузера не змінюються. Не потрібно видаляти посилання із шаблонів або перевіряти $isEditor.
Кореневий елемент
Оскільки в шаблоні блока може бути лише один кореневий елемент, під час використання useBlockProps шаблон має містити лише один кореневий елемент. Наприклад, наведений нижче варіант не працюватиме, і Gutenberg створить обгортку навколо шаблону.
<div useBlockProps>
First root element.
</div>
<span>
Second root element.
</span>
Так само useBlockProps можна використовувати в шаблоні блока лише один раз.
Символ @
Blockstudio перетворює шаблон блока на коректний код React у Gutenberg за допомогою html-react-parser. Через це символ @ не можна використовувати в назві атрибута HTML.
Такі бібліотеки, як Alpine.js, використовують символи @ для визначення директив в елементах HTML.
<button useBlockProps @click="console.log('hi')">
Click me
</button>
Усередині Gutenberg цей атрибут @click буде видалено з елемента. (Звісно, на фронтенді він і далі працюватиме.)
Щоб вирішити цю проблему, можна скористатися альтернативним синтаксисом Alpine.js.
<button useBlockProps x-on:click="console.log('hi')">
Click me
</button>
Наведений вище варіант працюватиме всередині Gutenberg і на фронтенді.
Класи body на полотні редактора
Коли assets.reset.enabled активний, Blockstudio також копіює на полотно редактора очищені класи, повернуті фільтром body_class об’єкта WordPress. Завдяки цьому селектори теми, як-от .brand-a .site-card, працюють в обох місцях.
Фільтруйте кінцевий список класів, якщо редактору потрібен вужчий набір:
add_filter('blockstudio/editor/canvas/body_class', function(array $classes) {
return array_values(array_diff($classes, ['logged-in']));
});
Цей фільтр керує лише класами, скопійованими на полотно редактора. Він не змінює класи body на фронтенді.