Как добавить поддержку Gutenberg блоков в своем плагине WordPress

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

Что такое Gutenberg блоки и почему они важны

Gutenberg — это современный визуальный редактор WordPress, который заменил классический редактор. Контент создается из блоков: параграфы, заголовки, изображения, видео и т.д. Разработчики могут создавать свои собственные блоки, которые позволяют внедрять кастомный функционал прямо в редактор, обеспечивая интерактивность и удобство настройки.

Поддержка Gutenberg блоков в плагинах важна, чтобы:

• Обеспечить пользователям удобный интерфейс добавления и настройки функционала;
• Интегрировать сложные интерактивные элементы без необходимости писать код;
• Упростить редактирование и визуализацию данных прямо в редакторе.

Как структурирован Gutenberg блок: основные компоненты

Каждый блок состоит из двух частей — JavaScript (React) для редактора и PHP для рендеринга на фронтенде (если нужен динамический вывод). Основные элементы блока:

• registerBlockType — функция регистрации блока в JS;
• edit — компонент React, отображающийся в редакторе;
• save — функция, определяющая HTML для сохранения в контенте (статические блоки);
• render_callback — PHP функция для динамического рендеринга блока;
• assets — скрипты и стили, которые подключаются для редактора и фронтенда.

Подключение блоков в плагине WordPress: подготовка файлов и регистрация

Создадим минимальную структуру для плагина с Gutenberg блоком:

<?php
/**
 * Plugin Name: WPDevelop Gutenberg Block
 * Description: Пример добавления собственного Gutenberg блока
 * Version: 1.0
 * Author: WPDevelop
 */

function wpdevelop_register_block() {
    // Регистрируем скрипт блока
    wp_register_script(
        'wpdevelop-block',
        plugins_url( 'block/build/index.js', __FILE__ ),
        array( 'wp-blocks', 'wp-element', 'wp-editor', 'wp-components' ),
        filemtime( plugin_dir_path( __FILE__ ) . 'block/build/index.js' )
    );

    // Регистрируем стиль для фронтенда
    wp_register_style(
        'wpdevelop-block-style',
        plugins_url( 'block/build/style.css', __FILE__ ),
        array(),
        filemtime( plugin_dir_path( __FILE__ ) . 'block/build/style.css' )
    );

    // Регистрируем стиль для редактора
    wp_register_style(
        'wpdevelop-block-editor-style',
        plugins_url( 'block/build/editor.css', __FILE__ ),
        array( 'wp-edit-blocks' ),
        filemtime( plugin_dir_path( __FILE__ ) . 'block/build/editor.css' )
    );

    register_block_type( 'wpdevelop/custom-block', array(
        'editor_script' => 'wpdevelop-block',
        'style' => 'wpdevelop-block-style',
        'editor_style' => 'wpdevelop-block-editor-style',
        'render_callback' => 'wpdevelop_render_custom_block',
    ) );
}
add_action( 'init', 'wpdevelop_register_block' );

// PHP функция для динамического вывода блока
function wpdevelop_render_custom_block( $attributes ) {
    $content = isset( $attributes['content'] ) ? esc_html( $attributes['content'] ) : '';
    return '<div class="wpdevelop-custom-block">' . $content . '</div>';
}

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

Создание JavaScript блока с использованием React и JSX

В папке block/src создадим файл index.js с кодом блока:

import { registerBlockType } from '@wordpress/blocks';
import { RichText } from '@wordpress/block-editor';

registerBlockType('wpdevelop/custom-block', {
    title: 'WPDevelop: Кастомный блок',
    icon: 'smiley',
    category: 'common',
    attributes: {
        content: {
            type: 'string',
            source: 'html',
            selector: 'div',
        },
    },
    edit({ attributes, setAttributes }) {
        const { content } = attributes;
        return (
            <RichText
                tagName="div"
                className="wpdevelop-custom-block"
                onChange={ (content) => setAttributes({ content }) }
                value={content}
                placeholder="Введите текст..."
            />
        );
    },
    save() {
        // Рендер через PHP
        return null;
    },
});

Обратите внимание, что метод save() возвращает null, так как мы используем динамический рендеринг через PHP.

Работа с атрибутами блока и их безопасность

Атрибуты блока – это данные, передаваемые из редактора в рендер. Их нужно правильно обрабатывать, чтобы избежать XSS уязвимостей. В примере PHP функции wpdevelop_render_custom_block используется esc_html для экранирования содержимого.

Если вам нужно принимать более сложные данные, например, URL или HTML, используйте соответствующие функции WordPress:

• esc_url для URL;
• wp_kses_post для безопасного HTML;
• sanitize_text_field для простого текста.

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

Для сборки JS кода используйте инструменты сборки, например, webpack или @wordpress/scripts. После сборки подключите скрипты и проверьте работу блока в редакторе и на фронтенде.

Если блок не отображается, проверьте консоль браузера и логи сервера. Частая ошибка — некорректное указание путей к скриптам или отсутствие зависимостей.

Дополнительные плагины для расширения Gutenberg блоков

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

• Clearfy Pro — оптимизация и расширенные возможности редактора;
• WPCommunity — расширение для социальных функций с поддержкой блоков;
• WPRemark — система отзывов с интеграцией в Gutenberg.

Заключение

Добавление поддержки Gutenberg блоков в плагин WordPress — важный навык для современного разработчика. Правильная структура, безопасная работа с атрибутами и динамический рендеринг позволяют создавать удобные и мощные расширения для редактора. Используйте приведенные примеры, чтобы быстро начать разработку собственных блоков и улучшить UX вашего плагина.