Создание динамических блоков в Gutenberg: Полное руководство

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

Что такое динамические блоки в Gutenberg?

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

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

Основные преимущества использования динамических блоков:

1. Автоматическое обновление содержимого: Динамические блоки полезны для информации, которая часто меняется, например, последние новости, события или статистика.
2. Гибкость и адаптивность: Обновления кода блока, например добавление нового класса или изменение HTML-структуры, сразу же отображаются на сайте. В случае статических блоков такие изменения требовали бы повторного сохранения блоков для их обновления.
3. Поддержка серверного рендеринга: В отличие от статических блоков, которые полностью рендерятся в редакторе, динамические блоки позволяют использовать серверный рендеринг (с помощью PHP), обеспечивая гибкость отображения, например, извлечение данных из базы данных для отображения на фронтенде.

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

Планирование и подготовка к созданию динамического блока

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

1. Определение функциональности блока

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

• Какое количество записей отображать?
• Нужно ли выводить только заголовки или заголовки и краткое описание?
• Будут ли какие-то фильтры (например, только записи определенной категории)?

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

2. Настройка атрибутов блока

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

Пример основных атрибутов для блока последних записей:

attributes: {
    postsToShow: {
        type: 'number',
        default: 5, // Количество записей для отображения по умолчанию
    },
    displayExcerpt: {
        type: 'boolean',
        default: true, // Отображать краткое описание записи
    },
    categoryFilter: {
        type: 'string',
        default: 'all', // Категория, по которой фильтруются записи
    },
}

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

3. Использование рендеринга на сервере

Рендеринг на сервере (или серверный рендеринг) — это ключевая особенность динамических блоков. Он позволяет создавать содержимое блока на стороне сервера, что особенно полезно для работы с часто изменяющимися данными, такими как списки записей, данные о погоде или статистика.

Рендеринг на сервере выполняется с помощью PHP-функции, назначенной через параметр render_callback. Эта функция отвечает за получение данных и формирование HTML-кода, который будет отображаться на фронтенде.

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

register_block_type( 'my-plugin/latest-posts', array(
    'api_version' => 2,
    'editor_script' => 'my-plugin-editor-script', // Скрипт редактора
    'render_callback' => 'render_latest_posts_block', // Функция рендеринга
) );

Здесь render_callback указывает на функцию PHP, которая будет выполняться каждый раз при рендеринге блока на фронтенде.

4. Настройка параметров блока

На этапе планирования также полезно продумать и указать параметры блока, такие как:

• title: заголовок, отображаемый в списке блоков в редакторе;
• icon: иконка для визуального представления блока в интерфейсе;
• category: категория, к которой относится блок (например, «виджеты» или «медиа»).

Пример настройки базовых параметров:

registerBlockType( 'my-plugin/latest-posts', {
    title: 'Последние записи', // Заголовок блока
    icon: 'megaphone', // Иконка блока
    category: 'widgets', // Категория
    ...
} );

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

Создание функции edit для блока

Функция edit отвечает за отображение блока в редакторе WordPress. Важно, чтобы она была удобной для пользователя и показывала блок в том виде, в котором он будет отображаться на сайте. Это помогает пользователю сразу видеть результат внесенных изменений и позволяет редактировать блок с учетом всех доступных настроек.

1. Использование useBlockProps для базовых свойств блока

Базовые свойства блока можно настроить с помощью useBlockProps, который помогает обрабатывать стили и классы для блока. Это упрощает процесс стилизации блока и делает код более читабельным.

import { useBlockProps } from '@wordpress/block-editor';

const blockProps = useBlockProps();

2. Использование useSelect для получения данных

Функция useSelect позволяет извлекать данные из хранилища WordPress в режиме реального времени. Это полезно для динамических блоков, где данные могут часто изменяться, например, список последних записей, данные о пользователях и т.д.

Пример извлечения последних записей для блока:

import { useSelect } from '@wordpress/data';

const posts = useSelect((select) => {
    return select('core').getEntityRecords('postType', 'post', { per_page: 5 });
}, []);

В данном примере getEntityRecords извлекает записи типа post с ограничением по количеству (5 записей). Эти данные затем можно использовать для отображения записей в редакторе.

3. Настройка визуального отображения блока в редакторе

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

Полный пример функции edit:

import { useBlockProps } from '@wordpress/block-editor';
import { useSelect } from '@wordpress/data';

const Edit = (props) => {
    const { attributes, setAttributes } = props;
    const blockProps = useBlockProps();

    // Получаем последние записи
    const posts = useSelect((select) => {
        return select('core').getEntityRecords('postType', 'post', { per_page: attributes.postsToShow });
    }, [attributes.postsToShow]);

    // Отображаем данные в редакторе
    return (
        <div { ...blockProps }>
            {!posts && <p>Загрузка...</p>}
            {posts && posts.length === 0 && <p>Записей не найдено</p>}
            {posts && posts.length > 0 && (
                <ul>
                    {posts.map((post) => (
                        <li key={post.id}>
                            <a href={post.link}>{post.title.rendered}</a>
                            {attributes.displayExcerpt && (
                                <p>{post.excerpt.rendered}</p>
                            )}
                        </li>
                    ))}
                </ul>
            )}
        </div>
    );
};

4. Управление атрибутами через редактор

Мы также можем добавить элементы управления атрибутами (например, количество отображаемых записей или включение описаний). Это делается через дополнительные панели настройки блока.

Пример добавления элемента управления атрибутами:

import { InspectorControls } from '@wordpress/block-editor';
import { PanelBody, ToggleControl, RangeControl } from '@wordpress/components';

const Edit = (props) => {
    const { attributes, setAttributes } = props;
    const blockProps = useBlockProps();

    return (
        <>
            <InspectorControls>
                <PanelBody title="Настройки блока">
                    <RangeControl
                        label="Количество записей"
                        value={attributes.postsToShow}
                        onChange={(value) => setAttributes({ postsToShow: value })}
                        min={1}
                        max={10}
                    />
                    <ToggleControl
                        label="Показывать описание"
                        checked={attributes.displayExcerpt}
                        onChange={(value) => setAttributes({ displayExcerpt: value })}
                    />
                </PanelBody>
            </InspectorControls>
            <div { ...blockProps }>
                {/* Вывод списка записей аналогичен предыдущему примеру */}
            </div>
        </>
    );
};

Здесь:

• RangeControl позволяет пользователю выбирать количество записей для отображения.
• ToggleControl управляет видимостью описаний записей.
• Если вам нужны другие компоненты, зайдите в наш кодекс React Компонентов и пролистайте.

Создание функции рендеринга на стороне сервера

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

Почему важен рендеринг на сервере?

Рендеринг на стороне сервера полезен для блоков, данные которых могут часто изменяться (например, последние записи, данные пользователя и т.п.). Основные преимущества:

• Данные обновляются в реальном времени.
• Пользователь всегда видит актуальные данные на сайте.
• Легкость в управлении и использовании PHP-функций для обработки данных.

Настройка функции render_callback

Для реализации рендеринга на сервере нам потребуется зарегистрировать callback-функцию рендеринга (render_callback) при регистрации блока в PHP. Эта функция будет отвечать за генерацию HTML для блока на фронтенде.

Пример кода для PHP-функции рендеринга:

function my_dynamic_block_render_callback( $attributes, $content ) {
    // Получение последних записей
    $recent_posts = get_posts( array(
        'numberposts' => $attributes['postsToShow'],
        'post_status' => 'publish',
    ) );

    // Если записей нет, выводим сообщение
    if ( count( $recent_posts ) === 0 ) {
        return '<p>Записей не найдено.</p>';
    }

    // Создание HTML-вывода для блока
    $output = '<ul class="my-dynamic-block">';
    foreach ( $recent_posts as $post ) {
        $post_id = $post->ID;
        $output .= '<li>';
        $output .= '<a href="' . esc_url( get_permalink( $post_id ) ) . '">' . esc_html( get_the_title( $post_id ) ) . '</a>';

        // Если атрибут `displayExcerpt` активирован, добавляем описание записи
        if ( $attributes['displayExcerpt'] ) {
            $output .= '<p>' . esc_html( wp_trim_words( get_the_excerpt( $post_id ), 20 ) ) . '</p>';
        }

        $output .= '</li>';
    }
    $output .= '</ul>';

    return $output;
}

Регистрация блока с функцией render_callback

После создания функции рендеринга, необходимо зарегистрировать её при регистрации блока. Это можно сделать с помощью параметра render_callback в функции register_block_type.

function my_register_dynamic_block() {
    register_block_type( 'my-plugin/my-dynamic-block', array(
        'api_version' => 2,
        'editor_script' => 'my-block-editor-script',
        'render_callback' => 'my_dynamic_block_render_callback',
        'attributes' => array(
            'postsToShow' => array(
                'type' => 'number',
                'default' => 5,
            ),
            'displayExcerpt' => array(
                'type' => 'boolean',
                'default' => false,
            ),
        ),
    ) );
}
add_action( 'init', 'my_register_dynamic_block' );

Описание атрибутов в функции рендеринга

В нашем примере мы используем два атрибута:

• postsToShow: количество отображаемых записей.
• displayExcerpt: флаг, указывающий, следует ли отображать описание.

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

Полный цикл работы рендеринга

1. Пользователь задает параметры блока в редакторе (например, количество записей и показ описания).
2. Атрибуты сохраняются в базе данных и передаются в функцию render_callback.
3. Функция render_callback генерирует HTML, используя переданные атрибуты и данные, извлекаемые через PHP.
4. На фронтенде отображается актуальный контент, без необходимости обновления кода вручную.

Использование ServerSideRender для динамического отображения блока в редакторе

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

Зачем использовать ServerSideRender?

ServerSideRender полезен, когда блок опирается на динамические данные, которые не сохраняются в атрибутах, но зависят от серверных данных, например, последних публикаций или статистики. Вместо того чтобы воссоздавать структуру на JavaScript, мы можем использовать ServerSideRender, чтобы редактор получал готовый HTML от функции рендеринга на сервере.

Настройка компонента ServerSideRender в блоке

Для использования ServerSideRender в блоке необходимо добавить его в функцию edit в registerBlockType. Этот компонент подключает рендеринг PHP-функции, зарегистрированной как render_callback, и показывает содержимое прямо в редакторе.

import { registerBlockType } from '@wordpress/blocks';
import ServerSideRender from '@wordpress/server-side-render';
import { useBlockProps } from '@wordpress/block-editor';

registerBlockType( 'my-plugin/my-dynamic-block', {
    apiVersion: 2,
    title: 'My Dynamic Block',
    icon: 'megaphone',
    category: 'widgets',
    attributes: {
        postsToShow: {
            type: 'number',
            default: 5,
        },
        displayExcerpt: {
            type: 'boolean',
            default: false,
        },
    },
    edit: (props) => {
        const blockProps = useBlockProps();

        return (
            <div { ...blockProps }>
                <ServerSideRender
                    block="my-plugin/my-dynamic-block"
                    attributes={ props.attributes }
                />
            </div>
        );
    },
    save: () => {
        return null;
    },
} );

Объяснение кода

1. Импорт компонента ServerSideRender: Компонент импортируется из пакета @wordpress/server-side-render.
2. Передача атрибутов: Внутри ServerSideRender мы указываем блок, который должен отрендериться (my-plugin/my-dynamic-block), и передаем ему атрибуты через props.attributes.
3. Отсутствие сохранения: В методе save мы возвращаем null, так как рендеринг осуществляется на сервере.

Как работает рендеринг в редакторе?

ServerSideRender обращается к функции render_callback, указанной для блока в PHP (в данном случае my_dynamic_block_render_callback). Эта функция получает данные атрибутов и возвращает HTML-код, который отображается в редакторе.

Примечание: Использование ServerSideRender не влияет на производительность сайта, так как рендеринг происходит только в редакторе. На фронтенде HTML-код блока генерируется функцией render_callback, как описано в предыдущем разделе.

Теперь, когда мы добавили ServerSideRender, любой пользователь, добавляющий блок в редакторе, сразу увидит последние записи, количество которых соответствует значению postsToShow, а также короткое описание (если displayExcerpt установлен в true).

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

Использование встроенных параметров стилей для кастомизации блока

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

Что такое встроенные параметры стилей?

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

Пример настройки стилей для динамического блока

Чтобы добавить эти параметры, нам нужно указать их в массиве supports при регистрации блока. Рассмотрим, как добавить поддержку цветов, отступов и границ.

registerBlockType( 'my-plugin/my-dynamic-block', {
    apiVersion: 2,
    title: 'My Customizable Dynamic Block',
    icon: 'megaphone',
    category: 'widgets',
    attributes: {
        postsToShow: {
            type: 'number',
            default: 5,
        },
        displayExcerpt: {
            type: 'boolean',
            default: false,
        },
    },
    supports: {
        color: {
            background: true,
            text: true,
        },
        spacing: {
            margin: true,
            padding: true,
        },
        border: {
            color: true,
            radius: true,
            style: true,
            width: true,
        },
    },
    edit: (props) => {
        const blockProps = useBlockProps();

        return (
            <div { ...blockProps }>
                <ServerSideRender
                    block="my-plugin/my-dynamic-block"
                    attributes={ props.attributes }
                />
            </div>
        );
    },
    save: () => {
        return null;
    },
} );

Объяснение параметров

1. Цвета (Color): Параметр color позволяет пользователям изменять фон и цвет текста блока. В данном примере мы включили опции background и text, что дает доступ к этим настройкам в редакторе.
2. Отступы (Spacing): Параметр spacing включает в себя настройки для margin и padding. Это позволяет пользователям управлять внутренними и внешними отступами блока.
3. Границы (Border): Параметры border добавляют возможность изменять цвет границы, радиус, стиль и ширину. Такие настройки позволяют пользователю гибко управлять внешним видом блока.

Как это работает в редакторе?

Когда поддержка настроек включена, пользователь увидит дополнительные параметры в боковой панели редактора Gutenberg при выборе блока. Например, с помощью цветовой панели можно выбрать цвет фона и текста, а ползунки для padding и margin помогут настроить отступы. Все изменения автоматически применяются и визуализируются в режиме реального времени.

Примечание: Включение параметров supports автоматически добавляет нужные классы CSS, такие как .has-background или .has-text-color, а также стили, соответствующие выбранным пользователем цветам и отступам. Это снижает необходимость в кастомной стилизации блока.

Пример использования пользовательских настроек

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

Управление версиями и тестирование динамического блока

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

Поддержка версии API

В Gutenberg можно указать версию API, которая поддерживается блоком. Это особенно важно, так как новая версия API может изменить поведение компонентов или синтаксис, влияя на работу блока. Указание версии API помогает сохранить совместимость блока с обновлениями WordPress.

В примере ниже мы используем свойство apiVersion, чтобы указать, что наш блок разработан для API версии 2:

registerBlockType( 'my-plugin/my-dynamic-block', {
    apiVersion: 2,
    title: 'My Customizable Dynamic Block',
    icon: 'megaphone',
    category: 'widgets',
    // Другие параметры блока...
} );

Совет: Старайтесь отслеживать изменения в API, чтобы обновлять блок в соответствии с новыми функциями и возможностями. Это не только улучшит функциональность, но и обеспечит блок стабильной работой в новых версиях WordPress.

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

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

1. Тестирование в редакторе: Включите и настройте ваш блок в редакторе. Убедитесь, что все атрибуты и стили корректно отображаются и работают так, как ожидается. Проверьте, что значения атрибутов корректно обновляются.
2. Тестирование на фронтенде: Опубликуйте блок на сайте и проверьте, как он отображается на фронтенде. Все ли стили и данные корректно выводятся? Работает ли блок в соответствии с дизайном?
3. Кроссбраузерное тестирование: Убедитесь, что ваш блок одинаково отображается в разных браузерах, так как могут возникнуть различия в поддержке CSS и JavaScript.
4. Тестирование с разными темами: Проверяйте блок с различными темами WordPress, чтобы убедиться в отсутствии конфликтов со сторонними стилями и функциональностью.
5. Тестирование с плагинами: Убедитесь, что ваш блок работает корректно при включении популярных плагинов, которые могут добавлять свои стили или скрипты, чтобы исключить потенциальные конфликты.
6. Юнит-тесты: WordPress предоставляет юнит-тестирование с помощью библиотеки PHPUnit. Это позволяет тестировать функцию рендеринга блока и его настройки, что повышает стабильность кода.

Пример юнит-теста для функции рендеринга блока

Рассмотрим простой пример юнит-теста для функции gutenberg_examples_dynamic_render_callback. Предположим, что эта функция выводит заголовок последнего поста.

Создайте тестовый класс, чтобы проверить вывод функции:

class MyDynamicBlockTest extends WP_UnitTestCase {

    public function test_block_renders_latest_post_title() {
        // Создаем тестовый пост
        $post_id = $this->factory->post->create( array(
            'post_title' => 'Тестовый заголовок',
            'post_status' => 'publish',
        ) );

        // Ожидаемый результат рендеринга
        $expected = sprintf(
            '<a class="wp-block-my-plugin-latest-post" href="%s">%s</a>',
            esc_url( get_permalink( $post_id ) ),
            esc_html( get_the_title( $post_id ) )
        );

        // Проверяем, что функция возвращает ожидаемый результат
        $this->assertEquals(
            $expected,
            gutenberg_examples_dynamic_render_callback( array(), '' )
        );
    }
}

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

Примечание: Юнит-тесты можно также настроить в CI/CD-процессах (например, с использованием GitHub Actions), чтобы автоматически проверять блок при каждом изменении в репозитории.

Заключение

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