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

useBlockProps

По умолчанию Gutenberg должен создавать обертку вокруг блоков, чтобы сделать их интерактивными в редакторе. Для некоторых типов блоков, например контейнеров и колонок, это может стать проблемой, поскольку разметка в редакторе и внешнем интерфейсе будет различаться. Хук useBlockProps позволяет пометить элемент внутри шаблона блока как корневой и тем самым обеспечить одинаковую разметку в редакторе и внешнем интерфейсе.

Использование

Просто добавьте атрибут useBlockProps к корневому элементу блока.

PHP
<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 применяется к обертке как при отрисовке во внешнем интерфейсе, так и в редакторе. Поэтому классы, добавленные темой или интеграцией для конкретного экземпляра, отображаются и на холсте редактора, и в сохраненной разметке внешнего интерфейса.

Результат:

HTML
<div class="my-class wp-block-your-block-name alignright">
</div>

Особенности

Blockstudio отключает переход по ссылкам внутри редактора блоков, в том числе при target="_blank", щелчках с модификатором, нажатии средней кнопкой мыши и активации с клавиатуры. События щелчка по-прежнему доходят до Gutenberg, поэтому обычные щелчки выделяют блок. RichText остаётся доступным для редактирования. Это работает как с useBlockProps, так и без него, включая случаи, когда элементом корневого уровня блока служит якорь.

Ссылки на фронтенде и команды контекстного меню браузера работают как прежде. Удалять ссылки из шаблонов или проверять $isEditor не нужно.

Корневой элемент

Поскольку в шаблоне блока может быть только один корневой элемент, при использовании useBlockProps шаблон блока должен иметь один корневой элемент. Например, следующий вариант не сработает, и Gutenberg создаст обертку вокруг шаблона.

PHP
<div useBlockProps>
  First root element.
</div>
<span>
  Second root element.
</span>

Аналогично, useBlockProps можно использовать в шаблоне блока только один раз.

Символ @

Blockstudio преобразует шаблон блока в корректный код React внутри Gutenberg с помощью html-react-parser. Это означает, что символ @ нельзя использовать в имени атрибута HTML.

Такие библиотеки, как Alpine.js, используют символы @ для определения директив в элементах HTML.

PHP
<button useBlockProps @click="console.log('hi')">
  Click me
</button>

Внутри Gutenberg этот атрибут @click удаляется из элемента. (Во внешнем интерфейсе он, конечно, продолжит работать.)

Чтобы решить эту проблему, можно использовать альтернативный синтаксис, предоставляемый Alpine.js.

PHP
<button useBlockProps x-on:click="console.log('hi')">
  Click me
</button>

Приведенный выше вариант будет работать внутри Gutenberg и во внешнем интерфейсе.

Классы body на холсте

Когда включен assets.reset.enabled, Blockstudio также копирует на холст редактора классы после очистки, возвращаемые фильтром body_class у WordPress. Благодаря этому селекторы темы, например .brand-a .site-card, работают в обоих местах.

Этот фильтр позволяет задать более узкий набор классов, когда он нужен редактору:

PHP
add_filter('blockstudio/editor/canvas/body_class', function(array $classes) {
  return array_values(array_diff($classes, ['logged-in']));
});

Этот фильтр управляет только классами, копируемыми на холст редактора. Он не изменяет классы body во внешнем интерфейсе.