Редактор Gutenberg полностью изменил подход к созданию контента в WordPress. Вместо коротких кодов, HTML-вставок и большого количества пользовательских полей теперь можно создавать собственные блоки, которые полностью интегрируются в редактор и позволяют пользователям работать с контентом в визуальном режиме. Создание собственного блока — это современный способ разработки тем и плагинов WordPress. Такие блоки могут содержать текст, изображения, формы, кнопки, карточки товаров, таблицы цен, слайдеры, отзывы и любые другие элементы сайта. В этой статье подробно рассмотрим процесс создания собственного блока Gutenberg с использованием block.json, JavaScript, React, PHP и CSS.

Что такое пользовательский блок Gutenberg

Пользовательский блок — это самостоятельный компонент редактора, который имеет собственные:
  • настройки;
  • атрибуты;
  • интерфейс;
  • стили;
  • JavaScript;
  • PHP (для динамических блоков).

Преимущества собственных блоков

  • удобный визуальный редактор;
  • отсутствие шорткодов;
  • гибкая настройка параметров;
  • автоматическая интеграция с Gutenberg;
  • поддержка Full Site Editing;
  • простое сопровождение проекта.

Структура проекта

my-block/ ├── block.json ├── index.js ├── edit.js ├── save.js ├── style.css ├── editor.css ├── render.php └── index.asset.php

Файл block.json

Современная разработка блоков начинается именно с него. 
{ "$schema":"https://schemas.wp.org/trunk/block.json", "apiVersion":3, "name":"mytheme/card", "title":"Карточка", "category":"widgets", "icon":"admin-post", "description":"Карточка товара", "editorScript":"file:./index.js", "editorStyle":"file:./editor.css", "style":"file:./style.css" }

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

В файле functions.php или основном файле плагина: 
add_action('init', function () { register_block_type( __DIR__ . '/blocks/card' ); });
WordPress автоматически зарегистрирует все файлы, указанные в block.json.

Создание JavaScript

Файл index.js регистрирует блок. 
import { registerBlockType } from '@wordpress/blocks'; import Edit from './edit'; import Save from './save'; registerBlockType('mytheme/card',{ edit:Edit, save:Save });

Редактор блока

Файл edit.js отвечает за отображение блока в Gutenberg. 
export default function Edit(){ return( <div> Мой первый блок </div> ); }

Вывод блока

Файл save.js определяет HTML, который будет сохранен в записи. 
export default function Save(){ return( <div> Мой первый блок </div> ); }

Добавление атрибутов

registerBlockType('mytheme/card',{ attributes:{ title:{ type:'string', default:'' } } });

Использование RichText

import { RichText } from '@wordpress/block-editor'; export default function Edit({attributes,setAttributes}){ return( <RichText value={attributes.title} onChange={(value)=> setAttributes({ title:value }) } /> ); }

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

export default function Save({attributes}){ return( <RichText.Content tagName="h2" value={attributes.title} /> ); }

Добавление панели настроек

import { InspectorControls } from '@wordpress/block-editor'; import { PanelBody, TextControl } from '@wordpress/components';
Пример: 
<InspectorControls> <PanelBody title="Настройки"> <TextControl label="Заголовок" /> </PanelBody> </InspectorControls>

Добавление CSS

Файл style.css 
.wp-block-mytheme-card{ padding:30px; background:#fff; border-radius:12px; box-shadow:0 5px 20px rgba(0,0,0,.08); }

Стили редактора

Файл editor.css 
.wp-block-mytheme-card{ outline:2px dashed #0073aa; }

Добавление изображения

import { MediaUpload } from '@wordpress/block-editor';
Использование: 
<MediaUpload onSelect={ (image)=> setAttributes({ image:image.url }) } />

Создание динамического блока

В block.json: 
{ "render":"file:./render.php" }

Файл render.php

<?php return sprintf( '<div class="card">%s</div>', esc_html( $attributes['title'] ) );

Подключение JavaScript только для фронтенда

{ "viewScript":"file:./view.js" }

Добавление собственного значка

{ "icon":"smiley" }
Можно использовать любую Dashicons-иконку.

Добавление категории

{ "category":"widgets" }
Или собственную категорию: 
wp.blocks.updateCategory( 'mytheme', { title:'Мои блоки' } );

Использование InnerBlocks

Если блок должен содержать другие блоки: 
import { InnerBlocks } from '@wordpress/block-editor';
Вывод: 
<InnerBlocks />

Сборка проекта

Для разработки рекомендуется использовать пакет @wordpress/scripts. Установка: 
npm install @wordpress/scripts --save-dev
Сборка проекта: 
npm run build
Разработка: 
npm start

Типичные ошибки

  • не зарегистрирован block.json;
  • не подключен index.asset.php;
  • не совпадает имя блока в registerBlockType() и block.json;
  • неправильно настроены атрибуты;
  • используется устаревший API Gutenberg;
  • отсутствуют editor.css или style.css;
  • не очищен кэш после сборки проекта.

Итог

  • используйте block.json как основной файл конфигурации;
  • разделяйте стили редактора и фронтенда;
  • используйте React-компоненты WordPress вместо собственного HTML там, где это возможно;
  • для сложных блоков применяйте динамический рендеринг через PHP;
  • используйте @wordpress/scripts для автоматической сборки;
  • храните каждый блок в отдельной директории;
  • используйте семантическую HTML-разметку и валидируйте атрибуты перед выводом.
Создание собственного блока Gutenberg — современный и рекомендуемый способ расширения возможностей WordPress. Использование файла block.json, компонентов React, функций register_block_type() и динамического рендеринга через PHP позволяет создавать удобные, быстрые и полностью интегрированные с редактором блоки. Такой подход делает разработку тем и плагинов более структурированной, упрощает сопровождение кода и обеспечивает совместимость с последними версиями WordPress и Full Site Editing.

Метки: ,