Как изменить внутренний HTML Gutenberg блока в WordPress

В редакторе Gutenberg в WordPress блоки построены на React и используют JSX для описания своей структуры. Часто возникает задача изменить внутренний HTML уже существующего блока — например, чтобы добавить дополнительный элемент, изменить классы или вставить кастомный атрибут. В этой статье мы подробно рассмотрим, как это сделать, как для стандартных блоков WordPress, так и для своих кастомных, а также как избежать типичных ошибок при переопределении разметки.

Почему важно корректно изменять внутренний HTML блока Gutenberg

Gutenberg-блоки — это React-компоненты, которые формируют контент страницы. Изменение внутреннего HTML без понимания принципов работы может привести к ошибкам рендеринга, нарушению совместимости с другими плагинами и потерям данных при сохранении.

Правильное изменение позволяет:

• Добавлять новые элементы и улучшать функциональность блока.
• Изменять стили и атрибуты для кастомизации внешнего вида.
• Интегрировать дополнительные данные в блок, сохраняя его совместимость с редактором.

Как изменить внутренний HTML стандартного блока WordPress

Стандартные блоки WordPress (например, core/paragraph, core/image) не предоставляют прямого API для изменения внутреннего JSX. Однако мы можем использовать фильтр blocks.getSaveElement, чтобы перехватить и изменить разметку при сохранении.

Пример изменения внутреннего HTML параграфа — добавим к каждому параграфу дополнительный <span> с иконкой:

function wpblock_modifyParagraphSaveElement(element, blockType, attributes) {
    if (blockType.name === 'core/paragraph') {
        // Создаем новый элемент span
        const iconSpan = wp.element.createElement('span', { className: 'wpblock-icon' }, '📝');
        // Клонируем исходный элемент и добавляем span внутрь
        return wp.element.cloneElement(
            element,
            element.props,
            element.props.children,
            iconSpan
        );
    }
    return element;
}
wp.hooks.addFilter(
    'blocks.getSaveElement',
    'wpblock/modify-paragraph-save-element',
    wpblock_modifyParagraphSaveElement
);

В этом коде мы используем функцию cloneElement из React (доступный через wp.element) чтобы добавить новый дочерний элемент к сохранённому HTML параграфа. Этот способ позволяет аккуратно расширить разметку без полного переопределения блока.

Что важно учитывать при использовании фильтра blocks.getSaveElement

1. Фильтр срабатывает только при сохранении контента, то есть влияет на вывод на фронтенде.

2. Изменения не затрагивают отображение в редакторе (edit), для этого нужно дополнительно вмешиваться в компонент редактирования.

3. Не стоит радикально менять структуру блока — это может привести к проблемам с миграцией и совместимостью.

Изменение внутреннего HTML кастомного Gutenberg блока

В случае кастомных блоков у нас полный контроль над JSX в функциях edit и save. Чтобы изменить внутренний HTML, достаточно отредактировать функцию save, возвращающую JSX-разметку.

Пример базового кастомного блока и добавления дополнительного элемента в его сохранение:

const { registerBlockType } = wp.blocks;

registerBlockType('wpblock/custom-text-block', {
    title: 'WPBlock Кастомный Текст',
    icon: 'edit',
    category: 'common',
    attributes: {
        content: {
            type: 'string',
            default: ''
        }
    },
    edit: ({ attributes, setAttributes }) => {
        return (
            wp.element.createElement('textarea', {
                value: attributes.content,
                onChange: (e) => setAttributes({ content: e.target.value }),
                placeholder: 'Введите текст...'
            })
        );
    },
    save: ({ attributes }) => {
        return (
            wp.element.createElement('div', { className: 'wpblock-custom-text' }, [
                wp.element.createElement('p', null, attributes.content),
                wp.element.createElement('small', { className: 'wpblock-note' }, 'Это дополнительный текст')
            ])
        );
    }
});

Здесь в функции save мы создаем <div> с двумя элементами — параграфом с текстом и дополнительным <small> с пояснением. Такой подход позволяет полностью контролировать конечный HTML блока.

Советы при работе с JSX в save

• Используйте массивы элементов для вложенных компонентов.
• Соблюдайте семантику HTML для SEO и доступности.
• Добавляйте классы для стилизации через CSS.

Динамическое изменение HTML блока с использованием фильтров PHP

Иногда нужно изменить HTML блока не на уровне JS, а на уровне PHP — например, для серверного рендеринга динамических блоков. Для этого WordPress предоставляет фильтр render_block.

Пример добавления кастомного класса к блоку параграфа на стороне сервера:

function wpblock_add_class_to_paragraph_block($block_content, $block) {
    if ($block['blockName'] === 'core/paragraph') {
        // Добавляем класс wpblock-highlight
        $block_content = str_replace('<p', '<p class="wpblock-highlight"', $block_content);
    }
    return $block_content;
}
add_filter('render_block', 'wpblock_add_class_to_paragraph_block', 10, 2);

Этот метод подходит для динамического модифицирования HTML перед выводом. Однако будьте осторожны, чтобы не сломать структуру и не внести XSS уязвимости.

Полезные плагины для работы с HTML Gutenberg блоков

Для упрощения кастомизации HTML Gutenberg блоков можно использовать готовые плагины:

• Block Filters — расширяет возможности фильтров для блоков, позволяет менять сохранённый HTML и атрибуты.
• Advanced Custom Fields (ACF) Pro — с помощью ACF можно создавать динамические блоки с серверным рендерингом и кастомной разметкой.
• Gutenberg Plugin — официальный плагин с расширенными возможностями редактора, часто добавляет новые хуки и фильтры.

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

Заключение: лучшие практики изменения внутреннего HTML Gutenberg блоков

Изменение внутреннего HTML блоков – мощный инструмент, но требует аккуратности. Рекомендуется:

1. Использовать фильтры blocks.getSaveElement для легких изменений стандартных блоков.
2. Создавать собственные блоки для полной кастомизации через JSX.
3. Для серверной динамики применять фильтр render_block.
4. Тестировать изменения на разных устройствах и в редакторе.
5. Соблюдать стандарты безопасности и доступности.

Таким образом, вы сможете гибко и безопасно настраивать HTML разметку Gutenberg блоков под задачи вашего сайта на WordPress.