Как изменить вывод содержимого блока Gutenberg в WordPress через фильтры и хуки

В редакторе Gutenberg каждый блок WordPress выводится с определённой разметкой HTML, которая формируется на сервере или на клиенте. Иногда возникает задача модифицировать этот вывод — добавить дополнительные элементы, изменить структуру или внедрить динамические данные. В этой статье подробно разберём, как изменить вывод содержимого блоков Gutenberg с помощью фильтров PHP и хуков, а также рассмотрим примеры для стандартных и кастомных блоков.

Почему важно уметь изменять вывод блоков Gutenberg

Визуальный редактор Gutenberg предоставляет мощный инструментарий для создания контента, но не всегда стандартный вывод блока полностью подходит под задачи сайта. Например, требуется добавить дополнительный класс, обернуть содержимое в другую разметку, вставить динамические данные из пользовательских полей или интегрировать сторонние сервисы. Редактирование шаблонов блоков напрямую в JavaScript — сложная задача, особенно для новичков. Именно поэтому применение PHP-фильтров — наиболее удобный путь модификации вывода на сервере.

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

Обзор основных хуков и фильтров для изменения вывода Gutenberg

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

Фильтр render_block принимает три параметра:

• $block_content — текущий HTML-код блока;
• $block — массив с данными блока (атрибуты, имя, настройки);
• $context — дополнительный контекст (редко используется).

Используя этот фильтр, можно целенаправленно изменять только нужные блоки по имени, например, только core/paragraph или core/image и так далее.

Пример 1. Добавление CSS-класса к параграфу (core/paragraph)

Допустим, нам нужно добавить класс wpboot-custom-paragraph ко всем параграфам, чтобы их стилизовать отдельно. Для этого используем фильтр render_block:

add_filter('render_block', 'wpboot_render_block_add_class', 10, 2);
function wpboot_render_block_add_class($block_content, $block) {
    if ($block['blockName'] === 'core/paragraph') {
        // Вставляем дополнительный класс к тегу <p>
        $block_content = preg_replace(
            '/<p(.*?)class="(.*?)"(.*?)>/i',
            '<p$1class="$2 wpboot-custom-paragraph"$3>',
            $block_content
        );
    }
    return $block_content;
}

Этот код добавляет необходимый класс ко всем параграфам без изменения других блоков.

Пример 2. Оборачивание содержимого блока "core/image" в div с дополнительным атрибутом

Иногда нужно добавить обёртку вокруг блока, чтобы применить кастомное позиционирование или добавить JavaScript-обработчики. Сделаем это для блока изображения:

add_filter('render_block', 'wpboot_wrap_image_block', 10, 2);
function wpboot_wrap_image_block($block_content, $block) {
    if ($block['blockName'] === 'core/image') {
        $block_content = '<div class="wpboot-image-wrapper" data-block-id="' . esc_attr($block['attrs']['id'] ?? '') . '">'
                         . $block_content
                         . '</div>';
    }
    return $block_content;
}

Добавление обёртки позволит гибко управлять стилями и поведением изображений.

Пример 3. Изменение вывода кастомного блока с динамическими данными

Если вы создаёте собственный блок с динамическим выводом, можно реализовать функцию рендеринга на PHP, зарегистрировав её в register_block_type. Рассмотрим пример для кастомного блока wpboot/dynamic-text, который выводит текст из опции сайта:

function wpboot_render_dynamic_text_block($attributes) {
    $text = get_option('wpboot_dynamic_text', 'Текст по умолчанию');
    return '<div class="wpboot-dynamic-text">' . esc_html($text) . '</div>';
}

add_action('init', function() {
    register_block_type('wpboot/dynamic-text', [
        'render_callback' => 'wpboot_render_dynamic_text_block',
    ]);
});

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

Как отлаживать изменения вывода блоков

Изменения через фильтр render_block влияют на фронтенд и бэкенд редактора. Для проверки корректности кода используйте стандартные методы отладки:

• Логи ошибок PHP и WP_DEBUG для выявления синтаксических ошибок;
• Вывод var_dump и error_log внутри фильтра для отслеживания параметров;
• Очистка кэша браузера и WordPress-кэша;
• Проверка конфликта с другими плагинами, отключая их по очереди.

Это поможет избежать неожиданных сбоев и сохранит стабильность сайта.

Рекомендации и лучшие практики

При изменении вывода блоков Gutenberg стоит придерживаться следующих принципов:

• Изменять только необходимые блоки, не трогая остальные — это минимизирует риск конфликтов;
• Использовать безопасные функции WordPress для экранирования данных (esc_html, esc_attr);
• Писать чистый и читаемый код с комментариями для поддержки;
• Тестировать изменения на тестовом сайте перед деплоем;
• При необходимости использовать плагины, расширяющие возможности Gutenberg, например, Clearfy Pro для оптимизации и кастомизации.

Заключение

Фильтр render_block — мощный инструмент для изменения вывода блоков Gutenberg на уровне PHP. Он позволяет легко добавлять CSS-классы, обёртки, динамически формировать содержимое и интегрировать сложную логику без глубокого погружения в JavaScript. Используйте приведённые примеры как основу для своих решений и адаптируйте их под задачи проекта.