ACF Blocks в Gutenberg: как сейчас правильно делать блоки в WordPress

ACF Blocks в Gutenberg сейчас лучше делать через block.json и отдельный PHP-шаблон render.php. Старый способ через acf_register_block_type() ещё может работать, но если начинать новый проект, я бы уже не строил всё на нём. У WordPress давно курс на block.json, и ACF тоже туда переехал.

Как сейчас устроен ACF-блок

Но есть нюанс. Когда начинаешь разбираться с ACF Blocks v3, быстро выясняется, что всё стало не так удобно, как раньше. В центре Gutenberg ты видишь превью блока, а сами поля уезжают в правый сайдбар или отдельную панель. Формально это правильно. По факту, если у блока много полей, редактировать их в узкой колонке — удовольствие сомнительное. Нормальная структура блока сейчас выглядит так:

theme/
  blocks/
    hero/
      block.json
      render.php
      style.css
      editor.css

То есть каждый блок живёт в своей папке. В block.json лежит описание блока, в render.php — обычная PHP-верстка, в style.css — стили для фронта, в editor.css — стили для редактора.

В functions.php блок регистрируется через register_block_type():

<?php

add_action('init', function () {
    register_block_type(get_stylesheet_directory() . '/blocks/hero');
});

Если это не дочерняя тема, можно использовать get_template_directory(). Главное, чтобы путь вёл именно к папке, где лежит block.json.

Пример block.json для ACF-блока

Минимальный рабочий вариант может быть таким:

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "mytheme/hero",
  "title": "Hero блок",
  "description": "Главный первый экран страницы",
  "category": "design",
  "icon": "cover-image",
  "acf": {
    "blockVersion": 3,
    "renderTemplate": "render.php"
  },
  "supports": {
    "anchor": true,
    "align": ["wide", "full"],
    "html": false
  },
  "style": "file:./style.css",
  "editorStyle": "file:./editor.css"
}

Самое важное здесь — секция acf. Именно она говорит ACF, что это ACF-блок, а renderTemplate указывает, какой PHP-файл использовать для вывода.

Поле name лучше сразу выбрать нормально и потом не менять. Например, если блок уже вставлен на странице как mytheme/hero, а потом ты переименуешь его в mytheme/hero-block, Gutenberg увидит старый блок как неподдерживаемый. Это одна из частых причин сообщения:

Ваш сайт не поддерживает этот блок.

Решение: после редактирования кода лучше полностью удалить блок из редактора и добавить заново.

Где реально рисуется блок

block.json ничего сам не выводит. Визуальный вид блока собирается в render.php. И именно этот файл отвечает сразу за две вещи: как блок выглядит на сайте и как он показывается в Gutenberg. Пример render.php:

<?php

$title = get_field('title');
$text = get_field('text');

$wrapper_attributes = get_block_wrapper_attributes([
    'class' => 'hero-block',
]);

?>

<section <?php echo $wrapper_attributes; ?>>
    <div class="hero-block__inner">
        <?php if ($title) : ?>
            <h1 class="hero-block__title">
                <?php echo esc_html($title); ?>
            </h1>
        <?php endif; ?>

        <?php if ($text) : ?>
            <div class="hero-block__text">
                <?php echo wp_kses_post($text); ?>
            </div>
        <?php endif; ?>
    </div>
</section>

Я бы не игнорировал get_block_wrapper_attributes(). Через него WordPress добавляет нужные классы и атрибуты блока. Особенно это важно, если ты включаешь align, отступы, цвета или другие настройки Gutenberg.

Почему блок в редакторе выглядит пустым

Это частая ситуация. Добавляешь ACF-блок в Gutenberg, а в центре почти ничего нет. Кажется, что что-то сломалось. На самом деле Gutenberg просто показывает результат render.php. Если поля ещё пустые, а в шаблоне нет заглушки, то и показывать особо нечего. Поэтому для нормальной работы лучше сразу делать preview-состояние. Например:

<?php

$title = get_field('title');
$text = get_field('text');

if (!empty($is_preview)) {
    $title = $title ?: 'Заголовок блока';
    $text = $text ?: 'Заполните поля блока справа.';
}

$wrapper_attributes = get_block_wrapper_attributes([
    'class' => 'hero-block',
]);

?>

<section <?php echo $wrapper_attributes; ?>>
    <div class="hero-block__inner">
        <h2><?php echo esc_html($title); ?></h2>
        <div><?php echo wp_kses_post($text); ?></div>
    </div>
</section>

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

Пример preview ACF блока

Главная боль ACF Blocks v3

Вот здесь начинается самое спорное. В ACF Blocks v3 старый режим, когда поля можно было видеть прямо внутри блока, по сути убрали. Теперь блок в центре редактора — это превью. А поля редактируются сбоку или в отдельной панели. С точки зрения архитектуры это можно понять. Gutenberg стал больше завязан на iframe, стили редактора и фронта стали ближе друг к другу, превью стало чище.

Но с точки зрения обычного клиента это иногда выглядит странно: блок перед глазами, а редактировать его нужно где-то справа. Если полей два-три, ещё терпимо. Например, заголовок, текст, кнопка. Но если там repeater, карточки, картинки, настройки фона, отступы и несколько вариантов отображения — правый сайдбар быстро превращается в мучение. Можно попробовать скрыть поля из сайдбара:

{
  "acf": {
    "blockVersion": 3,
    "renderTemplate": "render.php",
    "mode": "preview",
    "hideFieldsInSidebar": true
  }
}

Но это не магическая кнопка “сделать как Elementor”. Это просто другой способ показать поля, если версия ACF поддерживает расширенную панель редактирования. ACF-блоки всё равно остаются не визуальным билдером, а PHP-блоками с превью.

Textarea или WYSIWYG

Если клиенту нужен обычный текст без форматирования, можно использовать Textarea. Например, для короткого описания или подписи. Но если клиент должен выделять текст жирным, ставить ссылки, делать списки, тогда нужен WYSIWYG Editor. Обычный textarea для этого не подходит. Для WYSIWYG вывод должен быть таким:

<?php

$text = get_field('text');

if ($text) {
    echo wp_kses_post($text);
}

Не нужно выводить WYSIWYG через esc_html(), иначе HTML-разметка превратится в обычный текст, и весь смысл редактора потеряется. Я бы только не давал клиенту полный редактор со всеми кнопками. Лучше включить Basic toolbar, отключить загрузку медиа и оставить базовые вещи: жирный, ссылки, списки. Иначе клиент очень быстро начнёт ломать дизайн прямо внутри поля.

Предупреждение deprecated в консоли

При использовании ACF-поля типа WYSIWYG можно увидеть предупреждение вроде:

wp.data.select( 'core/preferences' ).get( 'core/edit-post', 'distractionFree' ) is deprecated since version 6.5.

Это не значит, что блок сломан. Обычно такое появляется, когда ACF подключает WYSIWYG/TinyMCE и связанные скрипты WordPress. Какой-то код обращается к настройке редактора старым способом, поэтому WordPress пишет предупреждение.

Предупреждение в консоли — wp.data.select is deprecated since version 6.5.

Если поле работает и сохраняется, я бы не тратил на это время. Это warning, а не fatal error. Для порядка можно обновить ACF PRO и остальные плагины, но сам по себе этот текст в консоли не означает, что render.php написан неправильно.

Когда ACF Blocks реально удобны

ACF-блоки хороши, когда нужно быстро делать кастомные секции без React. Например: первый экран, блок преимуществ, карточки услуг, FAQ, отзывы, контакты, текст с изображением. Разработчик контролирует HTML и CSS, клиент меняет только нужные поля. Это нормальная схема для сайтов, где дизайн должен оставаться аккуратным, а не превращаться в набор случайных Gutenberg-блоков.

Но я бы сразу объяснял клиенту: это не Elementor (в котором тоже бывают проблемы). Он не всегда будет редактировать текст прямо на странице. Часть данных будет в полях блока. Для кого-то это нормально, для кого-то — нет.

Какой подход я бы выбрал

Для нового проекта я бы делал так: block.json, render.php, отдельная папка на каждый блок, ACF-поля только для реально нужных данных. Не пытался бы запихнуть в один блок огромную админку на двадцать полей, потому что в Gutenberg это быстро становится неудобно. Если блок простой — ACF-поля подходят отлично. Если внутри нужен свободный текст, заголовки, списки и кнопки, иногда лучше использовать InnerBlocks и дать клиенту обычные Gutenberg-блоки внутри секции.

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

Итог

Сейчас правильный способ делать ACF-блоки в WordPress — это block.json, render.php и регистрация через register_block_type(). Старый acf_register_block_type() ещё можно встретить, но для новых проектов я бы уже не выбирал его как основной вариант. Главное — понимать ограничение ACF Blocks v3. Это не полноценное визуальное редактирование, а превью плюс поля. Поэтому нормальный render.php, заглушки для пустого состояния и аккуратная структура блока здесь важнее, чем кажется.

Если принять эту логику, ACF Blocks остаются рабочим и удобным инструментом. Просто не надо ждать от них поведения Elementor. Это другой подход: больше контроля у разработчика, меньше свободы у клиента, зато меньше шансов случайно развалить весь дизайн. Подробнее см. вводное руководство по ACF