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

InnerBlocks

Вложенные блоки позволяют добавлять блоки внутрь других блоков. Внутри Blockstudio использует компонент InnerBlocks. Обратите внимание: в каждом блоке можно использовать только один компонент InnerBlocks. Это WordPress ограничение.

Основы использования

Чтобы использовать InnerBlocks, добавьте компонент <InnerBlocks /> в шаблон блока:

PHP
<InnerBlocks />

Вы сами определяете композицию. Компонент InnerBlocks можно вкладывать на любую глубину или использовать отдельно.

Свойства

allowedBlocks

Свойство allowedBlocks позволяет указать, какие блоки можно вставлять в компонент InnerBlocks.

PHP

PHP
<InnerBlocks allowedBlocks="<?php echo esc_attr(wp_json_encode(['core/heading', 'core/paragraph'])); ?>" />

Twig

Twig
<InnerBlocks allowedBlocks="{{ ['core/heading', 'core/paragraph']|json_encode|escape('html_attr') }}" />

allowedBlocks также поддерживает токены, раскрываемые на сервере. Токены раскрываются до передачи шаблона редактору, а буквальные имена блоков остаются без изменений.

Токен Описание
namespace/* Каждый зарегистрированный блок в этом пространстве имен
category:<slug> Каждый зарегистрированный блок категории WordPress
@theme Каждый блок Blockstudio, зарегистрированный в активной теме

Развернутые записи удаляются при повторении, сохраняя порядок автора:

PHP
<InnerBlocks allowedBlocks="<?php echo esc_attr(wp_json_encode([
  'core/paragraph',
  'category:content',
  'bsui/field',
])); ?>" />

Токены, соответствующие блокам, которые не найдены, игнорируются. Вывод на внешней части сайта не меняется, поскольку allowedBlocks используется только в редакторе.

тег

По умолчанию компонент InnerBlocks отображается как элемент div. Это можно изменить с помощью свойства tag.

PHP
<InnerBlocks tag="section" />

шаблон

Свойство template позволяет задать шаблон для компонента InnerBlocks.

PHP

PHP
<InnerBlocks template="<?php echo esc_attr(wp_json_encode([
  ['core/heading', ['placeholder' => 'Book Title']],
  ['core/paragraph', ['placeholder' => 'Summary']]
])); ?>" />

Twig

Twig
<InnerBlocks template="{{ [
  ['core/heading', { placeholder: 'Book Title' }],
  ['core/paragraph', { placeholder: 'Summary' }]
]|json_encode|escape('html_attr') }}" />

templateLock

Свойство templateLock позволяет указать, можно ли изменять шаблон.

Значение Описание
contentOnly Запрещает все операции. Типы блоков без содержимого скрыты в режиме списка. Потомки не могут переопределить это значение.
all Запрещает все операции. Нельзя вставлять, перемещать или удалять блоки.
insert Запрещает вставку и удаление блоков, но позволяет перемещать существующие.
false Запрещает блокировку, даже если она задана для родительского блока.

renderAppender

Свойство renderAppender позволяет задать тип добавителя блоков.

Значение Описание
default Отображать аппендер блока по умолчанию (аппендер в стиле абзаца, если разрешен блок абзаца)
button Отображать кнопку аппендера со значком +

useBlockProps

useBlockProps удалит внешнюю обертку компонента InnerBlocks в редакторе. Подробнее см. в useBlockProps.

Контекст

Регистрация

Blockstudio поддерживает контекст для компонента InnerBlocks. Это позволяет передавать данные от родительского блока дочерним блокам. Хотя внутри используется базовый механизм контекста WordPress, Blockstudio предлагает более удобный API.

Вместо того чтобы отдельно определять все атрибуты, которые нужно передать в контексте, можно просто подписаться на все атрибуты родительского блока.

Каждый дочерний блок получает значения своего родителя, в том числе при первой предварительно загруженной отрисовке в редакторе. При изменении полей провайдера дочерние блоки обновляются в редакторе, даже если предыдущая отрисовка еще загружается. Одинаковые дочерние блоки у разных провайдеров сохраняют отдельные кэшированные отрисовки с учетом контекста.

Предположим, у вас настроен блок-контейнер следующим образом:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/container",
  "title": "Container",
  "category": "design",
  "icon": "star-filled",
  "description": "Container block.",
  "blockstudio": {
    "attributes": [
      {
        "id": "full-width",
        "type": "toggle",
        "label": "Makes section full width"
      }
    ]
  }
}

В дочернем блоке просто используйте свойство usesContext с именем родительского блока, чтобы получить доступ ко всем атрибутам родителя в шаблоне блока.

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/element",
  "title": "Element",
  "category": "design",
  "icon": "star-filled",
  "description": "Element block.",
  "usesContext": ["blockstudio/container"],
  "parent": ["blockstudio/container"],
  "blockstudio": true
}

Шаблоны

Переменные $context и $c доступны в шаблонах блока для доступа ко всем атрибутам родителя. При изменении данных родительского блока дочерние блоки автоматически перезагружаются в редакторе.

PHP

PHP
<?php $container = $context['blockstudio/container']; ?>

<h1>
  <?php echo $container['full-width']
      ? 'is full width'
      : 'no full width'; ?>
</h1>

Twig

Twig
{% set container = context['blockstudio/container'] %}

<h1>
  {{ container['full-width']
      ? 'is full width'
      : 'no full width' }}
</h1>

Обертка во внешнем интерфейсе

InnerBlocks должен выводить элемент-обертку вокруг дочерних элементов в редакторе, но ее можно убрать во внешнем интерфейсе с помощью фильтра blockstudio/blocks/components/inner_blocks/frontend/wrap.

PHP
add_filter('blockstudio/blocks/components/inner_blocks/frontend/wrap', function($wrap, $block) {
  return false; // Remove wrapper
}, 10, 2);

Досрочный возврат

Если нужно досрочно выйти из метода render вашего блока, проверьте, пустая ли переменная $innerBlocks. Это удобно, если при отсутствии вложенных блоков ничего выводить не нужно.

PHP
<?php if (strip_tags($innerBlocks) === '') {
  return;
} ?>
<InnerBlocks tag="section" />

Поскольку <InnerBlocks/> всегда выводит пустой тег абзаца, с помощью функции strip_tags можно проверить, пуст ли контент.

Динамические шаблоны

Типы полей Выбор и Переключатель поддерживают динамическое создание шаблона InnerBlocks в зависимости от значения поля. Это полезно, если вы хотите позволить пользователю выбрать другой шаблон для компонента InnerBlocks.

Для этого просто добавьте ключ innerBlocks в массив параметров, указав шаблон:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/dynamic-layout",
  "title": "Dynamic Layout",
  "blockstudio": {
    "attributes": [
      {
        "id": "layout",
        "type": "select",
        "label": "Layout",
        "options": [
          {
            "value": "1",
            "label": "Two Columns",
            "innerBlocks": [
              {
                "name": "core/columns",
                "innerBlocks": [
                  {
                    "name": "core/column",
                    "innerBlocks": [
                      {
                        "name": "core/heading",
                        "attributes": {
                          "content": "Left Heading",
                          "level": 1
                        }
                      }
                    ]
                  },
                  {
                    "name": "core/column",
                    "innerBlocks": [
                      {
                        "name": "core/heading",
                        "attributes": {
                          "content": "Right Heading",
                          "level": 1
                        }
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "value": "2",
            "label": "Single Column",
            "innerBlocks": [
              {
                "name": "core/heading",
                "attributes": {
                  "content": "Main Heading",
                  "level": 1
                }
              },
              {
                "name": "core/paragraph",
                "attributes": {
                  "content": "Main content goes here."
                }
              }
            ]
          }
        ],
        "allowNull": "Select a layout"
      }
    ]
  }
}

Контекст и взаимодействие блоков

Узнайте, как родительские и дочерние блоки обмениваются данными с помощью контекста.