Как создать первый ACF-блок в WordPress

Обзор

ACF Blocks дают вам возможность создавать практически любой блок, который только может понадобиться, с теми же возможностями, что и стандартные блоки WordPress, например InnerBlocks, Variations и Styles. В этом руководстве мы покажем, как создать блок с отзывом с помощью ACF Blocks, включая регистрацию необходимых полей ACF.

Блоки, которые вы создаёте с помощью ACF Blocks, — это пользовательский тип блока, похожий на нативные динамические блоки: они формируют свою структуру и контент на лету из PHP-шаблона, а ACF берёт на себя рендеринг.

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

Готовы пропустить пошаговые инструкции?
Вы можете сразу приступить, скачав tt3child.zip! Обязательно установите тему Twenty Twenty-Three, а также ACF PRO.

Составляющие блока

Есть несколько важных моментов, которые нужно учитывать, когда вы готовитесь создать новый блок. Какая информация понадобится редакторам для управления и обновления? Что может быть отрисовано статически (PHP, HTML), и нужен ли блоку собственный CSS? Ваш блок также может содержать пользовательский JavaScript для интерактивности, но наш первый блок в этом руководстве в нём не нуждается.

Прежде чем создавать блок, нужно продумать, какие функции ему потребуются.

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

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

Начало работы и требования

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

Для этого руководства вам понадобятся только три вещи:

ACF PRO. ACF Blocks — это премиум-функция, недоступная в бесплатной версии ACF.
Самостоятельно размещённый сайт WordPress, где у вас есть доступ к каталогу wp-content. Мы настоятельно рекомендуем развернуть тестовый сайт в Local.
Установленная и активированная стандартная тема Twenty Twenty-Three, чтобы вы могли создать дочернюю тему для организации своих настроек.

При этом для создания новых ACF Blocks потребуется базовое знание PHP и CSS, чтобы писать шаблоны и таблицы стилей. Также полезно иметь доступ к текстовому редактору кода, например Visual Studio Code, хотя это и не является обязательным требованием.

Создание дочерней темы

Для этого руководства мы воспользуемся плагином Create Block Theme из WordPress.org, чтобы сгенерировать дочернюю тему. После установки и активации плагина убедитесь, что тема Twenty Twenty-Three установлена и активирована, а затем нажмите Create Block Theme в разделе «Внешний вид» в админке WordPress. Откроется список параметров, основанный на текущей теме.

Чтобы продолжить, мы выбираем Create child of…, задаём имя дочерней теме: «TT3 Child», и нажимаем Generate. После этого вам предложат скачать и сохранить .zip-архив новой дочерней темы.

Дочерние темы следует размещать рядом с родительской темой, которая находится в wp-content/themes. Такая структура гарантирует, что WordPress сначала будет искать шаблоны в дочерней теме, а затем, если нужный шаблон не найден, проверит родительскую тему. После распаковки и размещения дочерней темы рядом с родительской темой Twenty Twenty-Three ваша итоговая структура каталога должна выглядеть так:

wp-content/themes/twentytwentythree [родительская тема]
wp-content/themes/tt3child [дочерняя тема]

Не забудьте активировать новую дочернюю тему после того, как добавите её. Также вы можете деактивировать плагин Create Block Theme, поскольку он больше не нужен.

Создание functions.php

Следующий шаг — создать файл functions.php и сохранить его в каталоге нашей дочерней темы. Вот как будет выглядеть итоговый код в новом functions.php.

<?php
/**
 * Мы используем хук init WordPress, чтобы убедиться,
 * что наши блоки зарегистрированы на раннем этапе
 * процесса загрузки.
 *
 * @link https://developer.wordpress.org/reference/hooks/init/
 */
function tt3child_register_acf_blocks() {
    /**
     * Мы регистрируем наш блок с помощью удобной
     * функции WordPress register_block_type();
     *
     * @link https://developer.wordpress.org/reference/functions/register_block_type/
     */
    register_block_type( __DIR__ . '/blocks/testimonial' );
}
// Здесь мы вызываем нашу функцию tt3child_register_acf_block() на init.
add_action( 'init', 'tt3child_register_acf_blocks' );

В приведённом выше коде мы добавляем новую функцию tt3child_register_acf_blocks(), которая вызывает функцию WordPress register_block_type(). Мы передаём путь к каталогу __DIR__ . '/blocks/testimonial', который в итоге найдёт нужный файл block.json. Файл block.json мы ещё не создали, но скоро создадим.

Наконец, мы привязываем вызов нашей новой функции tt3child_register_acf_blocks() к хуку init WordPress. Это гарантирует, что функция tt3child_register_acf_blocks() будет вызвана на раннем этапе жизненного цикла WordPress.

Регистрация блоков через block.json

Теперь нам нужно создать два новых каталога внутри дочерней темы. Первый называется blocks и будет хранить все наши ACF Blocks. Второй — acf-json, в нём будут храниться все данные групп полей, которые мы связываем с нашими блоками.

Также мы создадим подкаталог внутри blocks под названием testimonial. Каталог blocks/testimonial — это место, где мы будем хранить шаблон, таблицу стилей и файл block.json для нашего блока с отзывом.

Основные возможности и атрибуты любого блока ACF или WordPress определяются в файле block.json. Это сердце регистрации пользовательских блоков, и оно упрощает процесс, предоставляя единообразную структуру для определения настроек блока, стилей и метаданных в одном файле.

Поскольку наша функция register_block_type() ссылается на __DIR__ . '/blocks/testimonial' в каталоге темы, она должна найти файл block.json внутри каталога blocks/testimonial. Давайте создадим новый block.json и добавим следующие метаданные блока для нашего блока с отзывом.

{
    "name": "acf/testimonial",
    "title": "Отзыв",
    "description": "Пользовательский блок отзыва, использующий поля ACF.",
    "style": [ "file:./testimonial.css" ],
    "category": "formatting",
    "icon": "admin-comments",
    "keywords": ["отзыв", "цитата"],
    "acf": {
        "mode": "preview",
        "renderTemplate": "testimonial.php"
    },
    "supports": {
        "anchor": true
    }
}

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

name: Уникальный, пространственно-именованный идентификатор блока. Он должен иметь формат namespace/block-name. По умолчанию ACF Blocks используют пространство имён acf, если вы не укажете своё, но вы можете изменить его.
title: Понятное человеку название блока, используемое в интерфейсах ACF и WordPress.
description: Краткое описание назначения блока, отображаемое в вставщике блоков, когда редактор сайта наводит курсор на блок или нажимает на него.
style: Это ссылка на CSS, который будет применяться и в редакторе, и на фронтенде. В данном случае это testimonial.css из того же каталога, что и файл block.json.
category: Категория, в которой блок будет сгруппирован при отображении во вставщике блоков (например, “text”, “media”, “design”, “widgets”, “embed”).
icon: Значок, связанный с блоком, — либо slug Dashicon, либо SVG.
keywords: Массив поисковых фраз, которые можно добавить, чтобы помочь редакторам сайта найти ваш блок.
acf: Ключ ACF позволяет задать режим предпросмотра (preview, auto или edit) и указывает шаблон, который используется для вывода полей ACF в блоке; в данном случае это testimonial.php. Как и в случае со стилями, файл шаблона находится в том же каталоге, что и block.json.
supports: Объект, который указывает, какие возможности блок поддерживает или переопределяет, например пользовательские цвета, выравнивание текста или адаптивное встраивание.

Полный список метаданных вы можете найти в справочнике WordPress Block Editor Handbook: Метаданные в block.json.

Создание группы полей Testimonial

Файл testimonial.php, на который ссылается block.json, — это место, где мы добавим всю логику вывода и значения из наших пользовательских полей ACF. Сначала нам нужно зарегистрировать наши пользовательские поля ACF и назначить их нашему блоку с отзывом. Для этого сначала создадим новую группу полей в ACF под названием «Block: Testimonial». Затем добавим нужные поля:

Quote: Поле Text Area, которое содержит цитату, используемую в отзыве.
Author: Поле Text с именем человека, который оставил отзыв.
Role: Ещё одно текстовое поле, на этот раз с должностью клиента в его компании.
Image: Поле Image с изображением клиента.
Color Settings:
Настройки цвета
Содержит наши поля Color Picker для фона и текста.
Background Color: Поле Color Picker для управления цветом фона, используемым в блоке с отзывом.
Text Color: Как и выше, но управляет цветом текста.

Теперь нам нужно назначить новую группу полей «Block: Testimonial» нашему блоку с отзывом. Во время редактирования группы полей мы можем задать правило размещения в разделе «Settings > Location Rules». После того как мы добавим файл block.json нашего блока с отзывом, он должен появиться, если выбрать «Show this field group if: Block is equal to Testimonial».

Наконец, нажимаем Save Changes, и это автоматически сохранит файл group_xxxxxx.json внутри нашей дочерней темы. Помните, как мы создавали каталог acf-json в предыдущем разделе? Именно туда будет сохранена информация о группе полей «Block: Testimonial».

Каждый раз, когда мы обновляем группу полей «Block: Testimonial» и нажимаем Save Changes, существующий файл group_xxxxxx.json будет перезаписан последней информацией. Функция синхронизации JSON удобна для совместной работы, а также может быть версионирована.

Создание шаблона и таблицы стилей

После сохранения группы полей следующий шаг — создать файлы testimonial.css и testimonial.php, на которые ссылается block.json, и сохранить их в подкаталоге testimonial относительно файла block.json нашего блока с отзывом. После этого у вас должна получиться следующая структура:

wp-content/themes/tt3child/blocks/testimonial/block.json
wp-content/themes/tt3child/blocks/testimonial/testimonial.css
wp-content/themes/tt3child/blocks/testimonial/testimonial.php

Наличие этих важных файлов рядом друг с другом — одно из удобств, которые даёт использование ACF Blocks для создания пользовательских блоков.

Внутри `testimonial.php`

Вот как будет выглядеть весь файл testimonial.php после завершения работы. Ниже мы разберём некоторые важные фрагменты.

<?php
/**
 * Шаблон блока Testimonial.
 *
 * @param array $block Настройки и атрибуты блока.
 */

// Загружаем значения и задаём значения по умолчанию.
$quote             = !empty(get_field( 'quote' )) ? get_field( 'quote' ) : 'Ваша цитата здесь...';
$author            = get_field( 'author' );
$author_role       = get_field( 'role' );
$image             = get_field( 'image' );
$background_color  = get_field( 'background_color' ); // Цветовой пикер ACF.
$text_color        = get_field( 'text_color' ); // Цветовой пикер ACF.
$quote_attribution = '';

if ( $author ) {
    $quote_attribution .= '<footer class="testimonial__attribution">';
    $quote_attribution .= '<cite class="testimonial__author">' . $author . '</cite>';

    if ( $author_role ) {
        $quote_attribution .= '<span class="testimonial__role">' . $author_role . '</span>';
    }

    $quote_attribution .= '</footer><!-- .testimonial__attribution -->';
}

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

// Создаём атрибут class, позволяющий использовать пользовательские значения "className" и "align".
$class_name = 'testimonial';
if ( ! empty( $block['className'] ) ) {
    $class_name .= ' ' . $block['className'];
}
if ( ! empty( $block['align'] ) ) {
    $class_name .= ' align' . $block['align'];
}
if ( $background_color || $text_color ) {
    $class_name .= ' has-custom-acf-color';
}

// Формируем корректный атрибут style для цветов фона и текста.
$styles = array( 'background-color: ' . $background_color, 'color: ' . $text_color );
$style  = implode( '; ', $styles );
?>

<div <?php echo esc_attr( $anchor ); ?>class="<?php echo esc_attr( $class_name ); ?>" style="<?php echo esc_attr( $style ); ?>">
    <div class="testimonial__col">
        <blockquote class="testimonial__blockquote">
            <?php echo esc_html( $quote ); ?>

            <?php if ( !empty( $quote_attribution ) ) : ?>
                <?php echo wp_kses_post( $quote_attribution ); ?>
            <?php endif; ?>
        </blockquote>
    </div>

    <?php if ( $image ) : ?>
        <div class="testimonial__col">
            <figure class="testimonial__image">
                <?php echo wp_get_attachment_image( $image['ID'], 'full', '', array( 'class' => 'testimonial__img' ) ); ?>
            </figure>
        </div>
    <?php endif; ?>
</div>

Разберём некоторые части файла testimonial.php. Сначала у нас идёт PHP DocBlock с комментариями к коду, где описаны параметры, передаваемые через $block.

<?php
/**
 * Шаблон блока Testimonial.
 *
 * @param array $block Настройки и атрибуты блока.
 */

Следующий раздел загружает значения и задаёт значения по умолчанию из нашей группы полей «Block: Testimonial». Для этой части в ACF Blocks нет никакой особой процедуры. Вы регистрируете поля так же, как обычно:

// Загружаем значения и задаём значения по умолчанию
$quote             = !empty(get_field( 'quote' )) ? get_field( 'quote' ) : 'Ваша цитата здесь...';
$author            = get_field( 'author' );
$author_role       = get_field( 'role' );
$image             = get_field( 'image' );
$background_color  = get_field( 'background_color' ); // Цветовой пикер ACF.
$text_color        = get_field( 'text_color' ); // Цветовой пикер ACF.
$quote_attribution = '';

if ( $author ) {
    $quote_attribution .= '<footer class="testimonial__attribution">';
    $quote_attribution .= '<cite class="testimonial__author">' . $author . '</cite>';

    if ( $author_role ) {
        $quote_attribution .= '<span class="testimonial__role">' . $author_role . '</span>';
    }

    $quote_attribution .= '</footer><!-- .testimonial__attribution -->';
}

Мы используем логику для quote_attribution, чтобы убедиться, что автор контента заполнил эту информацию. Здесь можно задать разумные значения по умолчанию и помочь редакторам быстрее добиться нужного результата.

Далее мы передаём ID якоря, который редакторы могут задавать для каждого блока в редакторе блоков.

$anchor = '';
if ( ! empty( $block['anchor'] ) ) {
    $anchor = 'id="' . esc_attr( $block['anchor'] ) . '" ';
}

Мы также хотим передать вниз все уникальные классы. Имейте в виду, что редакторы также могут добавлять специальные классы для каждого блока прямо в редакторе блоков. Поэтому сначала мы проверяем if ( ! empty( $block[‘className’]).

Затем мы проверяем специальные классы выравнивания, которые включены по умолчанию и наследуются из Block Supports APIs ядра WordPress. Кроме того, мы передадим наш пользовательский цвет фона и цвет текста.

// Создаём атрибут class, позволяющий использовать пользовательские значения "className" и "align".
$class_name = 'testimonial';
if ( ! empty( $block['className'] ) ) {
    $class_name .= ' ' . $block['className'];
}
if ( ! empty( $block['align'] ) ) {
    $class_name .= ' align' . $block['align'];
}
if ( $background_color || $text_color ) {
    $class_name .= ' has-custom-acf-color';
}

Наконец, мы подходим к сердцу логики вывода. В этом разделе мы передаём стили для фона, цвета текста и т. д.:

$styles = array( 'background-color: ' . $background_color, 'color: ' . $text_color );
$style  = implode( '; ', $styles );

… и, наконец, данные из наших полей ACF:

<div <?php echo esc_attr( $anchor ); ?>class="<?php echo esc_attr( $class_name ); ?>" style="<?php echo esc_attr( $style ); ?>">
    <div class="testimonial__col">
        <blockquote class="testimonial__blockquote">
            <?php echo esc_html( $quote ); ?>

            <?php if ( !empty($quote_attribution) ) : ?>
                <?php echo wp_kses_post( $quote_attribution ); ?>
            <?php endif; ?>
        </blockquote>
    </div>

    <?php if ( $image ) : ?>
        <div class="testimonial__col">
            <figure class="testimonial__image">
                <?php echo wp_get_attachment_image( $image['ID'], 'full', '', array( 'class' => 'testimonial__img' ) ); ?>
            </figure>
        </div>
    <?php endif; ?>
</div>

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

Если включить в шаблоне функцию get_block_wrapper_attributes(), вы сможете использовать нативные для WordPress supports для блоков, например цвета и отступы. Функция автоматически выведет полный атрибут style в обёртке, которую WordPress добавляет вокруг вашего блока, но для корректного рендера ACF Blocks её нужно использовать вместе с переменной ACF is_preview.

Внутри testimonial.css

Практически никаких ограничений на то, как вы будете стилизовать блоки, нет. Ниже для удобства приведён CSS, использованный для стилизации нашего примера блока с отзывом. Мы сделали здесь определённые выборы в отношении box-sizing, display и т. д., но в конечном счёте то, как вы оформите блоки, зависит только от вас.

.testimonial {
    --testimonial-font-family: Baskerville,Baskerville Old Face,Hoefler Text,Garamond,Times New Roman,serif; 
    --testimonial-font-size: 1.5rem;
    --testimonial-spacing: 0.5rem;
}

.testimonial {
    align-items: center;
    box-sizing: border-box;
    display: flex;
    flex-wrap: wrap;
}

.testimonial > * {
    box-sizing: border-box;
    flex-grow: 1;
    min-width: 0;
    overflow-wrap: break-word;
    width: 100%;
    word-break: break-word;
}

.testimonial__blockquote {
    align-self: center;
    font-family: var(--testimonial-font-family);
    font-size: var(--testimonial-font-size);
    line-height: 1.18;
    padding: calc(4 * var(--testimonial-spacing)) calc(4.5 * var(--testimonial-spacing)) calc(2.5 * var(--testimonial-spacing));
    position: relative;
}

.testimonial__blockquote::before {
    color: currentColor;
    content: "“";
    display: block;
    font-family: var(--testimonial-font-family);
    font-size: calc(8 * var(--testimonial-spacing));
    position: absolute;
    top: calc(-1.25 * var(--testimonial-spacing));
}

.testimonial__attribution {
    font-family: var(--wp--preset--font-family--system-font);
    font-size: calc(0.6 * var(--testimonial-font-size));
    line-height: 1.5;
    margin-top: calc(2 * var(--testimonial-spacing));
}

.testimonial__author {
    font-style: normal;
    font-weight: 700;
}

.testimonial__role {
    display: block;
}

.testimonial__image {
    box-sizing: border-box;
    height: 100%;
    line-height: 0;
    margin-bottom: 0;
}

.testimonial__image img {
    height: 100%;
}

.testimonial__img {
    box-sizing: border-box;
    max-width: 100%;
    object-fit: cover;
}

@media (min-width: 600px) {
    .testimonial {
        flex-wrap: nowrap;
    }

    .testimonial__col:first-of-type {
        flex-basis: 64%;
    }

    .testimonial__col:last-of-type {
        flex-basis: 38%;
    }
}

Тестирование блока

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

Мы создаём новую запись и выбираем Testimonial во вставщике блоков. Затем заполняем все поля, включая изображение. При желании здесь же можно изменить цвета фона и текста, но если мы этого не сделаем, блок будет использовать цвета темы. Когда вы заполните все поля, нажмите Publish, и отзыв, который мы создали, появится на фронтенде сайта. Вы можете посмотреть весь процесс в видео ниже.

Заключение

Следуя этому руководству, вы создадите базовый блок с отзывом, но у ACF Blocks гораздо больший потенциал. ACF Blocks предоставляет большую часть возможностей, доступных при создании блоков WordPress с React, но в PHP-ориентированном фреймворке.

Есть множество способов улучшить созданный здесь базовый блок с отзывом. В следующих руководствах мы покажем, как вы можете использовать компонент InnerBlocks из ядра WordPress с ACF Blocks, чтобы передавать массив стандартных блоков и предварительно заполнять вложенные данные блока с помощью <InnerBlocks template="">, а затем использовать <code>templateLock= и подготовить наших редакторов контента к успешной работе.

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

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

Когда вы поймёте, как всё это работает, ACF Blocks откроет вам мир безграничных возможностей. После этого руководства нам очень интересно увидеть, что вы создадите.

Обновлено: 01.06.2026

Создайте свой первый блок ACF

Обзор

Составляющие блока

Начало работы и требования

Создание дочерней темы

Создание functions.php

Регистрация блоков через block.json

Создание группы полей Testimonial

Создание шаблона и таблицы стилей

Внутри `testimonial.php`

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

Внутри testimonial.css

Тестирование блока

Заключение

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

Создайте свой первый блок ACF

Обзор

Составляющие блока

Начало работы и требования

Создание дочерней темы

Создание functions.php

Регистрация блоков через block.json

Создание группы полей Testimonial

Создание шаблона и таблицы стилей

Внутри testimonial.php

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

Внутри testimonial.css

Тестирование блока

Заключение

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

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

Внутри `testimonial.php`