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

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

Почему стандартный List блок Gutenberg не всегда подходит

Стандартный блок списка в Gutenberg ограничен по возможностям кастомизации и логике взаимодействия. Например, нельзя удобно добавлять дополнительные поля к каждому элементу списка, например, описание, ссылку, изображения и т.д. Чтобы решить эту задачу, разработчикам приходится создавать кастомные блоки с собственным UI и логикой.

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

Основные технологии и подходы для реализации

Для создания такого блока будем использовать React (который лежит в основе Gutenberg), а именно хуки useState и useEffect, а также API WordPress для регистрации блока. Для хранения списка в блоке используем атрибуты блока, сериализуемые в разметку.

Код пишется с приставкой wpblock для функций, чтобы не было конфликтов с другими плагинами.

Регистрация блока и структура атрибутов

Для начала определим атрибуты блока, где список будет массивом объектов с полями title и description:

attributes: {
  items: {
    type: 'array',
    default: [],
    source: 'query',
    selector: '.wpblock-list-item',
    query: {
      title: { type: 'string', source: 'text', selector: '.wpblock-list-item-title' },
      description: { type: 'string', source: 'text', selector: '.wpblock-list-item-description' }
    }
  }
}

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

Редактирование и управление элементами списка в редакторе

В редакторе Gutenberg мы будем отображать список элементов с полями ввода для title и description, а также кнопки для добавления и удаления элементов.

Пример функции-обработчика изменения заголовка элемента:

function wpblockUpdateItemTitle(index, newTitle) {
  const newItems = [...attributes.items];
  newItems[index].title = newTitle;
  setAttributes({ items: newItems });
}

Добавление нового элемента:

function wpblockAddItem() {
  const newItems = [...attributes.items, { title: '', description: '' }];
  setAttributes({ items: newItems });
}

Удаление элемента по индексу:

function wpblockRemoveItem(index) {
  const newItems = attributes.items.filter((_, i) => i !== index);
  setAttributes({ items: newItems });
}

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

Ниже пример упрощённого редактора блока с динамическим списком:

import { __ } from '@wordpress/i18n';
import { useBlockProps, RichText, Button } from '@wordpress/block-editor';
import { Fragment } from '@wordpress/element';

export default function Edit({ attributes, setAttributes }) {
  const blockProps = useBlockProps();

  function wpblockUpdateItemTitle(index, value) {
    const newItems = [...attributes.items];
    newItems[index].title = value;
    setAttributes({ items: newItems });
  }

  function wpblockUpdateItemDescription(index, value) {
    const newItems = [...attributes.items];
    newItems[index].description = value;
    setAttributes({ items: newItems });
  }

  function wpblockAddItem() {
    const newItems = [...attributes.items, { title: '', description: '' }];
    setAttributes({ items: newItems });
  }

  function wpblockRemoveItem(index) {
    const newItems = attributes.items.filter((_, i) => i !== index);
    setAttributes({ items: newItems });
  }

  return (
    <div {...blockProps}>
      {attributes.items.length > 0 && attributes.items.map((item, index) => (
        <div className="wpblock-list-item" key={index} style={{ marginBottom: '20px', border: '1px solid #ccc', padding: '10px' }}>
          <RichText
            tagName="h4"
            placeholder={__('Заголовок элемента', 'wpblock')}
            value={item.title}
            onChange={(value) => wpblockUpdateItemTitle(index, value)}
            className="wpblock-list-item-title"
          />
          <RichText
            tagName="p"
            placeholder={__('Описание элемента', 'wpblock')}
            value={item.description}
            onChange={(value) => wpblockUpdateItemDescription(index, value)}
            className="wpblock-list-item-description"
          />
          <Button isDestructive onClick={() => wpblockRemoveItem(index)}>{__('Удалить', 'wpblock')}</Button>
        </div>
      ))}
      <Button isPrimary onClick={wpblockAddItem}>{__('Добавить элемент', 'wpblock')}</Button>
    </div>
  );
}

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

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

export default function Save({ attributes }) {
  const blockProps = useBlockProps.save();

  return (
    <div {...blockProps}>
      {attributes.items.length > 0 && attributes.items.map((item, index) => (
        <div className="wpblock-list-item" key={index}>
          <h4 className="wpblock-list-item-title">{item.title}</h4>
          <p className="wpblock-list-item-description">{item.description}</p>
        </div>
      ))}
    </div>
  );
}

Дополнительные советы и расширения

Добавление иконок и медиа

Если нужно расширить элементы списка изображениями или иконками, можно добавить в атрибуты поля mediaId и mediaUrl, использовать MediaUpload компонент для выбора и загрузки медиа.

Валидация и UX

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

Интеграция с плагинами

Если хотите добавить расширенную оптимизацию и контроль, можно использовать плагин Clearfy Pro (https://wpshop.ru/clearfy-pro?utm_source=wpblock.ru&utm_medium=article&utm_campaign=kak-otobrazhat-upravlyaemye-spiski-v-gutenberg) для улучшения производительности и безопасности, а также WPGPT (https://wpshop.ru/wpgpt?utm_source=wpblock.ru&utm_medium=article&utm_campaign=kak-otobrazhat-upravlyaemye-spiski-v-gutenberg) для генерации контента динамично.

Итог

Создание управляемого динамического списка в Gutenberg — частая задача для кастомных блоков. Используя React хуки и правильное определение атрибутов, можно создавать удобные и гибкие интерфейсы редактирования прямо в редакторе WordPress. Такой подход значительно расширяет возможности стандартного редактора и улучшает пользовательский опыт.