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

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 на фронтенді.