ACF Blocks: InnerBlocks и родительские блоки

Обзор

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

К концу руководства вы узнаете, как создать блок «Информация об авторе», который сочетает блоки ACF и стандартные блоки WordPress и позволяет редакторам указать изображение автора, имя, биографию и ссылку на соцсеть.

В будущих руководствах мы покажем, как использовать API блокировки блоков (появившийся в WordPress 5.9), чтобы запретить изменение или перемещение некоторых блоков, а также как расширять свои блоки ACF альтернативными стилями блоков.

Новичок в блоках ACF? Начните с нашего руководства по созданию первого блока ACF!

Видео ниже показывает, как выглядит блок «Информация об авторе», который мы создадим.

Пример блока «Информация об авторе» с линиями, указывающими на различные блоки.

Шаги, которые нужно выполнить

Создать плагин WordPress для организации нашего пользовательского кода
Зарегистрировать родительский и дочерний блоки ACF с помощью block.json
Зарегистрировать поле ACF для Twitter автора
Создать логику отображения с помощью InnerBlocks и шаблона блока

Требования

Блоки ACF — это премиальная функция, доступная только в ACF PRO. Вам также понадобится сайт WordPress, где у вас есть доступ к каталогу wp-content. Мы настоятельно рекомендуем использовать Local или другую среду разработки WordPress, чтобы создать тестовый сайт и безопасно экспериментировать.

Вложение блоков с InnerBlocks

Компонент WordPress InnerBlocks удобен для создания пользовательского блока, который передаёт набор тщательно отобранных вложенных блоков. Перед тем как глубже погрузиться в руководство, стоит разобрать несколько особенностей работы InnerBlocks.

Некоторые стандартные блоки WordPress уже используют InnerBlocks как часть своей функциональности, включая блоки Columns и Social Icons.

Важно отметить, что блок может содержать только один компонент InnerBlocks. Это связано с тем, как содержимое InnerBlocks хранится в блоке.

Использование вложенных шаблонов в InnerBlocks

Передача шаблона блоков в компонент InnerBlocks может заранее заполнить вложенные блоки и атрибуты-заполнители, ускоряя работу редактора.

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

Создайте макет вложенных блоков в редакторе блоков, назначив все нужные стили и атрибуты.
Выберите родительский блок в редакторе и нажмите Копировать.
Откройте WPHTML Converter и вставьте разметку блока из редактора. Нажмите Convert to PHP и скопируйте преобразованную разметку.
Вставьте преобразованную разметку в файл template.php вашего блока и сохраните её в переменную, чтобы использовать позже. Обязательно вложите её в array(). Мы разберём это на последнем шаге руководства.

Вот простой пример того, как это может выглядеть:

Пример передачи шаблона в InnerBlocks

<?php
    $my_block_template = array(
        array(
            'core/group',
            array(
                'layout' => array(
                    'type' => 'constrained',
                ),
            ),
            array(
                array(
                    'core/paragraph',
                    array(
                        'align'   => 'center',
                        'content' => 'Это абзац.',
                    ),
                    array(),
                ),
                array(
                    'core/separator',
                    array(),
                    array(),
                ),
            ),
        ),
    );

    //...

    <InnerBlocks template="<?php echo esc_attr( wp_json_encode( $my_block_template ) ); ?>" />

Использование связей parent и ancestor в блоках

Распространённый подход при работе с InnerBlocks — создать пользовательский блок, который доступен только тогда, когда вставлен его родительский блок. Это позволяет выстраивать связь между блоками и одновременно ограничивать обнаруживаемость вложенного блока. Сейчас доступны две связи: parent и ancestor. Разница между ними такова:

Если указать parent, это означает, что вложенный блок можно использовать и вставлять только как непосредственного потомка родительского блока.
Если указать ancestor, это означает, что вложенный блок можно использовать и вставлять как любой потомок родительского блока.

Ключевое различие между parent и ancestor в том, что parent задаёт более точную привязку, а ancestor даёт большую гибкость во вложенной иерархии.

В нашем блоке «Информация об авторе» мы хотим, чтобы блок Author Twitter был вложен как непосредственный потомок. Автор Info определяется как родительский блок в файле block.json блока Author Twitter:

Пример block.json с ключом parent


{
    ...
    "parent": [ "acf/author-info" ]
}

Хорошо, давайте приступим к созданию нашего пользовательского плагина и блоков!

1. Создать плагин WordPress для организации нашего пользовательского кода

В нашем примере мы создадим пользовательский плагин WordPress, чтобы упорядочить код, хотя при желании вы можете создавать блоки прямо в теме. Создайте новую папку author-info-block в каталоге wp-content/plugins на сайте WordPress. Затем добавьте в неё файл author-info-block.php. Именно в этом файле мы определим наш новый плагин WordPress с помощью следующего кода:

wp-content/plugins/author-info-block/author-info-block.php

<?php
/**
 * Название плагина: Блок Author Info для ACF PRO
 * Описание: Пример блока ACF PRO для отображения информации об авторе.
 * Текстовый домен: demo-author-block-acf
 */

2. Зарегистрировать родительский и дочерний блоки ACF с помощью `block.json`

Нам нужно зарегистрировать два блока ACF:

Author Info (родительский)
Author Twitter (дочерний)

Если вы уже проходили наше руководство по созданию первого блока ACF, это должно быть довольно знакомо. Однако здесь мы делаем всё немного иначе, потому что в этом руководстве организуем блоки в пользовательском плагине WordPress, а не в дочерней теме.

Чтобы зарегистрировать наши блоки, продолжим редактировать author-info-blocks.php и добавим следующий код сразу после заголовка:

wp-content/plugins/author-info-block/author-info-block.php

<?php
/**
 * Регистрируем наши блоки.
 *
 * @link https://www.advancedcustomfields.com/resources/whats-new-with-acf-blocks-in-acf-6/
 *
 * @return void
 */
function demo_author_block_acf_blocks_register() {
    /**
     * Мы регистрируем наши блоки с помощью удобной
     * функции WordPress register_block_type();
     *
     * @link https://developer.wordpress.org/reference/functions/register_block_type/
     */
    // Блок Author Info (родительский).
    register_block_type( __DIR__ . '/blocks/author-info' );
    // Блок Author Twitter (дочерний).
    register_block_type( __DIR__ . '/blocks/author-twitter' );
}
add_action( 'init', 'demo_author_block_acf_blocks_register', 5 );

Приведённый выше фрагмент кода регистрирует два блока с помощью register_block_type(). Дополнительные сведения о параметрах, которые можно передавать в эту функцию, см. в документации WordPress.

Для регистрации свойств всем блокам WordPress, включая блоки ACF, нужен файл block.json. У каждого блока должен быть свой файл block.json.

Сначала создайте в плагине каталог blocks, а затем ещё два вложенных каталога: author-info и author-twitter.

Каждому из этих блоков нужен обязательный файл block.json. Мы также создадим пустой файл template.php в каждом каталоге — именно туда мы поместим логику отображения (мы доберёмся до этого позже). Когда закончите, в каталоге blocks вашего плагина должны быть следующие файлы:

author-info-block/blocks/author-info/block.json
author-info-block/blocks/author-info/template.php
author-info-block/blocks/author-twitter/block.json
author-info-block/blocks/author-twitter/template.php

Начнём с заполнения метаданных block.json блока Author Info.

blocks/author-info/block.json

{
    "name": "acf/author-info",
    "title": "Информация об авторе (блок ACF)",
    "description": "Отображение информации и фотографии автора.",
    "icon": "id",
    "keywords": ["автор", "писатель"],
    "acf": {
        "mode": "preview",
        "renderTemplate": "template.php"
    },
    "supports": {
        "align": false,
        "anchor": true,
        "mode": false
    }
}

А вот код block.json для блока Author Twitter.

blocks/author-twitter/block.json

{
    "name": "acf/author-twitter",
    "title": "Twitter автора (блок ACF)",
    "description": "Отображение ссылки автора на Twitter.",
    "icon": "twitter",
    "keywords": ["автор", "твиттер"],
    "acf": {
        "renderTemplate": "template.php"
    },
    "supports": {
        "anchor": false,
        "align": false
    },
    "parent": [ "acf/author-info" ]
}

Ключи конфигурации, используемые в блоках ACF, в целом такие же, как и в стандартных блоках WordPress, но с добавлением ключа конфигурации acf.

Если вы впервые регистрируете типы блоков WordPress с помощью метаданных block.json, обязательно загляните в справочник WordPress Block Editor Handbook: Метаданные в block.json.

Несколько моментов в файлах block.json:

"renderTemplate": "template.php": Есть в обоих файлах; здесь будет находиться логика шаблона для каждого блока. Вы можете свободно изменить имена файлов шаблонов, если это изменение также отражено в JSON-файле. Код для этих файлов шаблонов мы добавим на более позднем шаге.
"parent": [ "acf/author-info" ]: Это значение есть только в блоке Author Twitter, поэтому он доступен только внутри блока Author Info. Ключ конфигурации parent автоматически помечает блок как доступный только при использовании в качестве дочернего блока указанного родителя.

Не забудьте сохранить изменения, а затем активировать свой пользовательский плагин. Поскольку мы уже определили наши блоки ACF через block.json в плагине, при его активации эти блоки автоматически станут доступны. Однако блок Author Twitter будет доступен в вставщике блоков только если существует его родительский блок Author Info. Кроме того, так как файлы template.php пока пустые, в редакторе блоков вы ничего не увидите. Продолжим и исправим это.

3. Зарегистрировать поле ACF для Twitter автора

Мы хотим дать редакторам возможность добавлять пользовательское имя пользователя Twitter, которое затем будет превращаться в ссылку на профиль автора в Twitter. Поэтому нам нужно зарегистрировать для этого пользовательское поле и назначить его блоку Author Twitter. Сделать это можно двумя способами. Первый — зарегистрировать всё через интерфейс ACF, выбрать пункт «Generate PHP» в меню Tools ACF, а затем вставить сгенерированный код в файл author-info-block.php вашего плагина. Как вариант, вы можете зарегистрировать поля через PHP в файле author-info-block.php.

Если вы используете интерфейс ACF, создайте новую группу полей для Author Twitter и добавьте одно текстовое поле Twitter. Обязательно назначьте его блоку Author Twitter в настройках правил размещения.

Изменение настроек на вкладке Presentation поля Twitter может упростить работу редактора:

Presentation > Instructions: https://twitter.com/[username]
Presentation > Prepend: https://twitter.com/

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

Нажмите Tools в меню ACF, затем выберите группу полей Author Twitter и нажмите Generate PHP. Так вы получите код, который можно сразу вставить в плагин.

После того как вы добавите сгенерированный код в файл author-info-block.php вашего плагина, можете удалить группу полей, созданную в интерфейсе ACF, потому что теперь она зарегистрирована кодом.

wp-content/plugins/author-info-block/author-info-block.php

<?php
/**
 * Регистрируем нашу группу полей Author Twitter
 * прямо в PHP, чтобы она была переносимой.
 *
 * @link https://www.advancedcustomfields.com/resources/register-fields-via-php/
 */
add_action(
    'acf/include_fields',
    function() {
        if ( ! function_exists( 'acf_add_local_field_group' ) ) {
            return;
        }

        acf_add_local_field_group(
            array(
                'key'      => 'group_64e3e09959e8f',
                'title'    => 'Twitter автора',
                'fields'   => array(
                    array(
                        'key'          => 'field_64e3e09a7a544',
                        'label'        => 'Твиттер',
                        'name'         => 'twitter',
                        'type'         => 'text',
                        'instructions' => 'https://twitter.com/[username]',
                        'prepend'      => 'https://twitter.com/',
                    ),
                ),
                'location' => array(
                    array(
                        array(
                            'param'    => 'block',
                            'operator' => '==',
                            'value'    => 'acf/author-twitter',
                        ),
                    ),
                ),
            )
        );
    }
);

Мы немного упростили вывод выше, потому что не все параметры действительно нужны. ACF использует значения по умолчанию для опций, которые мы опустили. Как уже упоминалось, можно вообще не регистрировать поля через интерфейс, а просто написать нужный PHP-код. Блок Author Info управляется PHP в author-info-block.php, а не настройками, сделанными в админке.

4. Создать логику отображения с помощью InnerBlocks и шаблона блока

На этом этапе у вас зарегистрированы два блока, но для них пока нет логики отображения. Здесь мы используем InnerBlocks и передаём строку шаблона блока, чтобы назначить и автоматически заполнить блок Author Info сразу после создания.

Сначала мы настроим логику отображения для блока Author Twitter, который выводит группу полей Author Twitter, созданную на прошлом шаге.

Откройте файл author-info-block/blocks/author-twitter/template.php блока Author Twitter и вставьте следующий код.

blocks/author-twitter/template.php

<?php
/**
 * Блок Author Twitter (дочерний).
 * Этот блок доступен только как дочерний
 * внутри родительского блока Author Info.
 */

// Получаем наше поле ACF.
$twitter_handle = get_field( 'twitter' );
?>

<?php if ( empty( $twitter_handle ) ) : ?>
    <p>Пожалуйста, введите имя пользователя Twitter.</p>
<?php else : ?>
    <p>
        <svg height="0.95rem" width="0.95rem" xmlns="http://www.w3.org/2000/svg" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" class="icon icon-twitter" viewBox="0 0 24 24"><path d="M22 4s-.7 2.1-2 3.4c1.6 10-9.4 17.3-18 11.6 2.2.1 4.4-.6 6-2C3 15.5.5 9.6 3 5c2.2 2.6 5.6 4.1 9 4-.9-4.2 4-6.6 7-3.8 1.1 0 3-1.2 3-1.2z"/></svg>
        <a href="https://twitter.com/<?php echo esc_html( $twitter_handle ); ?>">
            @<?php echo esc_html( $twitter_handle ); ?>
        </a>
    </p>
<?php endif; ?>

Это проверит значение нашего поля Twitter и отобразит его, если оно есть.

Далее мы добавим логику отображения блока Author Info в соответствующий файл demo-acf-plugin/blocks/author-info/template.php.

blocks/author-info/template.php

<?php
/**
 * Блок Author Info (родительский).
 *
 * @param array  $block Настройки и атрибуты блока.
 * @param string $content Внутренний HTML блока (пустой).
 * @param bool   $is_preview Истина во время предварительного просмотра в админке.
 * @param int    $post_id ID записи, против которой рендерится содержимое блока.
 *                     Это либо ID записи, которая сейчас отображается внутри цикла запроса,
 *                     либо ID записи, на которой размещён этот блок.
 * @param array $context Контекст, переданный блоку записью или его родительским блоком.
 */

// Поддержка пользовательских значений id.
$block_id = '';
if ( ! empty( $block['anchor'] ) ) {
    $block_id = esc_attr( $block['anchor'] );
}

// Создаём атрибут class, позволяющий использовать пользовательский "className".
$class_name = 'demo-author-block-acf';
if ( ! empty( $block['className'] ) ) {
    $class_name .= ' ' . $block['className'];
}

/**
 * Строка шаблона блоков.
 * Нужна помощь в преобразовании HTML-разметки блока в массив?
 * 👉 https://happyprime.github.io/wphtml-converter/
 *
 * @link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-templates/
 */
$inner_blocks_template = array(
    array(
        'core/columns',
        array(
            'verticalAlignment' => 'center',
            'style'             => array(
                'spacing' => array(
                    'padding' => array(
                        'top'    => 'var:preset|spacing|30',
                        'right'  => 'var:preset|spacing|30',
                        'bottom' => 'var:preset|spacing|30',
                        'left'   => 'var:preset|spacing|30',
                    ),
                ),
            ),
        ),
        array(
            array(
                'core/column',
                array(
                    'verticalAlignment' => 'center',
                    'width'             => '120px',
                ),
                array(
                    array(
                        'core/image',
                        array(
                            'align'           => 'center',
                            'sizeSlug'        => 'thumbnail',
                            'linkDestination' => 'none',
                            'className'       => 'is-style-rounded',
                            'url'             => 'https://i.pravatar.cc/120',
                        ),
                        array(),
                    ),
                ),
            ),
            array(
                'core/column',
                array(
                    'verticalAlignment' => 'center',
                    'width'             => '',
                ),
                array(
                    array(
                        'core/paragraph',
                        array(
                            'fontSize' => 'large',
                            'content'  => 'Тейлор Свифт',
                        ),
                        array(),
                    ),
                    array(
                        'core/paragraph',
                        array(
                            'style'    => array(
                                'spacing' => array(
                                    'margin' => array(
                                        'bottom' => '0',
                                        'top'    => '0',
                                    ),
                                ),
                            ),
                            'fontSize' => 'small',
                            'content'  => 'Здесь расположен краткий текст о биографии автора.',
                        ),
                        array(),
                    ),
                    array(
                        'acf/author-twitter-v1',
                        array(
                            'name' => 'acf/author-twitter-v1',
                            'data' => array(
                                'twitter' => 'wp_acf',
                            ),
                            'mode' => 'auto',
                        ),
                        array(),
                    ),
                ),
            ),
        ),
    ),
);

?>

<?php if ( ! $is_preview ) { ?>
    <div
        <?php
        echo wp_kses_data(
            get_block_wrapper_attributes(
                array(
                    'id'    => $block_id,
                    'class' => esc_attr( $class_name ),
                )
            )
        );
        ?>
    >
<?php } ?>

    <InnerBlocks
        class="demo-author-block-acf__innerblocks"
        template="<?php echo esc_attr( wp_json_encode( $inner_blocks_template ) ); ?>"
    />

<?php if ( ! $is_preview ) { ?>
    </div>
<?php } ?>

В приведённом выше фрагменте кода происходит много всего. Разберём его по частям. Самая большая часть этого фрагмента — $inner_blocks_template (в верхней части), переменная, которую мы передаём в свойство template внутри <InnerBlocks> (внизу). Переменная $inner_blocks_template состоит из массива блоков и их атрибутов, внутри которых находятся ещё вложенные блоки. Ближе к концу длинного вложенного массива вы увидите, что мы передаём наш пользовательский блок acf/author-twitter со значением поля twitter по умолчанию wp_acf. Это поможет заранее заполнить поле, когда блок Author Info будет добавлен в новую запись.

Выстроить вложенность и правильный синтаксис для таких сложных строк шаблонов бывает довольно трудно. Массив, определяющий $inner_blocks_template, содержит ещё более 30 вложенных массивов. Первый массив — это core/columns, стандартный блок WordPress, который позволяет отображать несколько колонок, каждая из которых может содержать блоки. Если заглянуть чуть глубже в массив core/columns, можно увидеть ещё один массив со значениями стилей:

$inner_blocks_template = array(
    array(
        'core/columns',
        array(
            'verticalAlignment' => 'center',
            'style'             => array(
                'spacing' => array(
                    'padding' => array(
                        'top'    => 'var:preset|spacing|30',
                        'right'  => 'var:preset|spacing|30',
                        'bottom' => 'var:preset|spacing|30',
                        'left'   => 'var:preset|spacing|30',
                    ),
                ),
            ),
        ),

Такое вложение быстро становится сложным, даже при относительно простом использовании InnerBlocks. Самый простой способ создать такой массив — собрать макет и дизайн в редакторе блоков, затем перейти в «Список» и нажать три точки справа от блока. Нажмите Копировать блок, чтобы скопировать HTML блока WordPress в буфер обмена. Затем вставьте его в такой инструмент, как WPHTML Converter, чтобы преобразовать разметку в нужный формат массива.

Ниже показано видео, демонстрирующее процесс преобразования.

Если вы следовали руководству до этого места, ваш итоговый код плагина должен совпасть с нашей версией: author-info-block-v1.zip

Подводя итоги

Это руководство показывает, как создать блок Author Info и интегрировать InnerBlocks с блоками ACF, чтобы создавать вложенные блоки с родительско-дочерними связями. Однако впереди ещё многое, что можно изучить.

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

Обновлено: 01.06.2026

ACF Blocks: InnerBlocks и родительско-дочерние связи

Обзор

Шаги, которые нужно выполнить

Требования

Вложение блоков с InnerBlocks

Использование вложенных шаблонов в InnerBlocks

Пример передачи шаблона в InnerBlocks

Использование связей parent и ancestor в блоках

Пример block.json с ключом parent

1. Создать плагин WordPress для организации нашего пользовательского кода

wp-content/plugins/author-info-block/author-info-block.php

2. Зарегистрировать родительский и дочерний блоки ACF с помощью `block.json`

wp-content/plugins/author-info-block/author-info-block.php

blocks/author-info/block.json

blocks/author-twitter/block.json

3. Зарегистрировать поле ACF для Twitter автора

wp-content/plugins/author-info-block/author-info-block.php

4. Создать логику отображения с помощью InnerBlocks и шаблона блока

blocks/author-twitter/template.php

blocks/author-info/template.php

Подводя итоги

Смотрите также

ACF Blocks: InnerBlocks и родительско-дочерние связи

Обзор

Шаги, которые нужно выполнить

Требования

Вложение блоков с InnerBlocks

Использование вложенных шаблонов в InnerBlocks

Пример передачи шаблона в InnerBlocks

Использование связей parent и ancestor в блоках

Пример block.json с ключом parent

1. Создать плагин WordPress для организации нашего пользовательского кода

wp-content/plugins/author-info-block/author-info-block.php

2. Зарегистрировать родительский и дочерний блоки ACF с помощью block.json

wp-content/plugins/author-info-block/author-info-block.php

blocks/author-info/block.json

blocks/author-twitter/block.json

3. Зарегистрировать поле ACF для Twitter автора

wp-content/plugins/author-info-block/author-info-block.php

4. Создать логику отображения с помощью InnerBlocks и шаблона блока

blocks/author-twitter/template.php

blocks/author-info/template.php

Подводя итоги

Похожие записи

Смотрите также

2. Зарегистрировать родительский и дочерний блоки ACF с помощью `block.json`