Щоб розробити блок 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 назвою, описом та посиланням", "supports": { "html": false }, "attributes": { "title": { "type": "string", "default": "" }, "description": { "type": "string", "default": "" }, "url": { "type" : } "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 &#039;@wordpress/block-editor&#039;; export default function Edit({ attributes, setAttributes }) { const { title, description } = attributes; return (
    <div {...useblockprops()}>
      <richtext
        tagname="h3"
        value="{title}"
        placeholder="Название услуги"
        onchange="{(value)" > setAttributes({ title: value })} /&gt;
      <richtext
        tagname="p"
        value="{description}"
        placeholder="Краткое описание"
        onchange="{(value)" > setAttributes({ description: value })} /&gt;
    </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, теми чи залежних плагінів. Впроваджуйте блок на робочий сайт лише після резервного копіювання та з планом швидкого відкату.

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