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 во внешнем интерфейсе.