Чтобы разработать блок Gutenberg для WordPress, подготовьте тестовую среду, создайте каркас через @wordpress/create-block, опишите настройки в block.json и реализуйте редактирование в edit.js. Для статического блока разметка сохраняется в контенте записи, а для динамического формируется на сервере, например через render.php.

Содержание

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

Место блоков среди других способов расширения сайта показано в руководстве по кастомной разработке WordPress. Ниже — шаги для собственного блока.

Когда нужен собственный блок

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

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

Готовый блок, паттерн или новый блок

Сначала определите, чего именно не хватает редактору. Не всякая нестандартная секция требует программирования:

Готовый блок подходит, если задачу можно решить стандартными средствами Gutenberg без нарушения структуры и дизайна.
Паттерн удобен для повторного использования композиции из нескольких блоков. Он задаёт начальную раскладку, но пользователь обычно может менять её элементы независимо.
Кастомный блок нужен, когда вы хотите ограничить набор полей, закрепить разметку, добавить специальное поведение или получать актуальные данные из системы.

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

Оцените альтернативы. Например, ACF в WordPress подходит для структурированных полей. Архитектуру выбирайте с учётом редакторского сценария, зависимости от плагинов и компетенций команды. Совместимость проверяйте на используемых версиях WordPress, темы и расширений.

Статический и динамический вывод

Главное архитектурное решение — где формируется разметка: при сохранении материала или при каждом открытии страницы. От этого зависит, как блок реагирует на изменение данных и насколько сложным будет его сопровождение.

Критерий	Статический блок	Динамический блок
Формирование вывода	Разметка сохраняется вместе с содержимым записи	Разметка создаётся на сервере при выводе страницы
Когда использовать	Контент меняется только через редактор блока	Результат зависит от записей, настроек или других актуальных данных
Подходящий сценарий	Карточка услуги с вручную заполненными полями	Список последних записей выбранной категории
Основное ограничение	Изменение структуры может потребовать учёта ранее сохранённой разметки	Вывод зависит от серверной логики и требует тщательной проверки данных

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

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

Подготовьте среду разработки

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

Тестовый WordPress

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

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

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

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

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

Для диагностики на тестовом сайте можно включить журналирование ошибок WordPress. Не выводите технические сообщения посетителям и не оставляйте режим отладки включённым на публичном сайте: журналы способны раскрывать пути к файлам и другие служебные сведения.

Инструменты сборки

Современные кастомные блоки Gutenberg обычно используют JavaScript, JSX и пакеты WordPress, поэтому вам понадобятся Node.js и npm. Выбирайте поддерживаемую версию Node.js и сверяйте её с требованиями используемых пакетов, а не устанавливайте произвольную старую сборку.

Официальный пакет @wordpress/create-block помогает подготовить структуру плагина и настроенную систему сборки. Перед запуском проверьте Node.js командой node --version, а npm — командой npm --version. Сам генератор можно вызвать через npx @wordpress/create-block; параметры проекта вы зададите на следующем этапе.

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

Если команда работает на разных операционных системах, зафиксируйте версии Node.js, менеджера пакетов и команды запуска в документации проекта. Это снижает риск ситуации, когда сборка работает у одного разработчика, но не воспроизводится у другого. До внедрения на рабочий сайт выполняйте установку зависимостей и сборку только в контролируемой среде, а полученный результат дополнительно проверяйте на staging.

Создайте основу блока

Состав пользовательского блока: метаданные, редактор и вывод

Метаданные block.json

Основу блока удобнее описывать в файле block.json. WordPress использует его как единый источник метаданных: имени блока, категории, подключаемых скриптов и стилей, поддерживаемых возможностей и структуры данных. Проект, созданный через @wordpress/create-block, уже содержит такой файл и базовую точку регистрации.

Для сценария «карточка услуги» минимальная конфигурация может выглядеть так:

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "project/service-card",
  "version": "0.1.0",
  "title": "Карточка услуги",
  "category": "widgets",
  "icon": "index-card",
  "description": "Карточка с названием, описанием и ссылкой",
  "supports": {
    "html": false
  },
  "attributes": {
    "title": {
      "type": "string",
      "default": ""
    },
    "description": {
      "type": "string",
      "default": ""
    },
    "url": {
      "type": "string",
      "default": ""
    }
  },
  "editorScript": "file:./index.js",
  "editorStyle": "file:./index.css",
  "style": "file:./style-index.css"
}

Поле name должно содержать пространство имён и уникальное название, например project/service-card. После публикации блока менять его без миграции нежелательно: WordPress использует это имя для распознавания сохранённой разметки.

editorScript указывает на JavaScript редактора, editorStyle — на стили только для административной части, а style — на общие стили блока. После сборки проверьте подключение файлов, версию WordPress и ограничения инфраструктуры.

Редакторская часть и атрибуты

Файл edit.js отвечает за интерфейс, который вы видите в Gutenberg. Данные следует хранить в атрибутах блока, если они должны сохраняться вместе с публикацией. Функция setAttributes обновляет эти значения при вводе.

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

export default function Edit({ attributes, setAttributes }) {
  const { title, description } = attributes;

  return (
    <div {...useBlockProps()}>
      <RichText
        tagName="h3"
        value={title}
        placeholder="Название услуги"
        onChange={(value) => setAttributes({ title: value })}
      />
      <RichText
        tagName="p"
        value={description}
        placeholder="Краткое описание"
        onChange={(value) => setAttributes({ description: value })}
      />
    </div>
  );
}

useBlockProps() добавляет обязательные свойства обёртки, благодаря которым редактор может выделять, перемещать и настраивать блок. Компонент RichText подходит для форматируемого текста. Для URL, чисел или переключателей лучше выбирать специализированные элементы управления и отдельно ограничивать допустимые значения.

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

Настройте вывод и данные

Передача данных блока от настроек редактора к отображению

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

Вариант	Когда использовать	Ограничения
Статический блок	Карточка услуги, предупреждение, оформленный текст с изображением	Изменение сохранённой структуры может потребовать миграции старого содержимого
Динамический блок	Список записей, данные из настроек или результат запроса	Вывод зависит от PHP-кода и создаёт серверную нагрузку при формировании страницы

Статическое сохранение

Для карточки услуги определите атрибуты блока в block.json: например, title, description и url. В edit.js вы получаете их через attributes, а изменения передаёте через setAttributes. Проверяйте тип каждого значения: строка не должна неожиданно превращаться в массив или логическое значение.

Функция save возвращает разметку, которая будет записана в содержимое страницы. Она должна зависеть только от атрибутов блока и вложенного контента, а не от внешнего API или текущей даты. Иначе сохранённая разметка перестанет совпадать с ожидаемой схемой.

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

Динамический рендеринг

Для динамического списка записей укажите в block.json файл рендеринга, например "render": "file:./render.php". Редактор сохраняет настройки блока — число элементов, выбранную рубрику и порядок, — а render.php получает атрибуты и формирует актуальный HTML на сервере.

В динамическом блоке функция save обычно возвращает null, если сохранять резервную разметку не требуется. В render.php нормализуйте входные параметры до запроса: количество записей преобразуйте в целое число и ограничьте допустимым диапазоном, идентификатор рубрики проверьте как положительное число, а направление сортировки выбирайте только из заранее заданного списка.

При выводе экранируйте данные по контексту: текст — через esc_html(), URL — через esc_url(), значения HTML-атрибутов — через esc_attr(). Если блок работает с закрытыми материалами или административными действиями, отдельно проверяйте права пользователя и nonce. Не передавайте параметры блока напрямую в SQL или HTML.

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

Проверьте блок перед внедрением

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

Редактор и фронтенд

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

Сравните представление в редакторе с опубликованной страницей. Для статического блока важно, чтобы сохранённая разметка соответствовала текущей реализации. Для динамического блока проверьте результат, формируемый на сервере через render.php: вывод не должен раскрывать закрытые записи или данные, недоступные текущему пользователю.

Все данные необходимо валидировать перед сохранением и экранировать при выводе. Для текста применяйте подходящие функции WordPress, а не универсальную обработку «на всякий случай»: обычный текст, URL и разрешённый HTML требуют разных способов экранирования. Если блок выполняет защищённое действие, проверьте права пользователя и nonce. Само наличие блока в редакторе не должно давать дополнительных полномочий.

Используйте следующий чек-лист:

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

Мобильный экран и обновления

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

Затем протестируйте обновление самого блока. Изменение структуры атрибутов или сохранённой разметки способно сделать ранее добавленные экземпляры недействительными. Откройте старые записи на staging, проверьте их в редакторе и на сайте. При изменении статической разметки предусмотрите устаревшие версии блока и миграцию данных; динамический вывод обычно обновляется централизованно, но также требует проверки шаблона и запросов.

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

Официальная документация: руководство по созданию блока.