Разработка кастомных блоков Gutenberg для WordPress

Разработка кастомных блоков Gutenberg для WordPress

Gutenberg заменил TinyMCE как основной редактор WordPress в версии 5.0. Кастомные блоки — это React-компоненты, которые отображаются и в редакторе, и на фронтенде. Они дают редактору визуальный контроль над структурированным контентом без необходимости знать HTML. Разработка одного блока средней сложности занимает 2–4 дня.

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

Современный подход — block.json + JavaScript/PHP:

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "my-plugin/project-card",
  "version": "1.0.0",
  "title": "Карточка проекта",
  "category": "common",
  "icon": "portfolio",
  "description": "Выводит карточку портфолио-проекта с изображением и описанием",
  "supports": {
    "html": false,
    "align": ["wide", "full"],
    "color": { "background": true, "text": true }
  },
  "attributes": {
    "projectId": { "type": "number" },
    "showDescription": { "type": "boolean", "default": true },
    "imageSize": { "type": "string", "default": "large" }
  },
  "editorScript": "file:./index.js",
  "editorStyle": "file:./editor.css",
  "style": "file:./style.css"
}

Регистрация в PHP:

add_action('init', function () {
    register_block_type(__DIR__ . '/blocks/project-card');
});

JavaScript: edit и save

import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps, InspectorControls, MediaUpload } from '@wordpress/block-editor';
import { PanelBody, ToggleControl, SelectControl, Button } from '@wordpress/components';
import { useSelect } from '@wordpress/data';

registerBlockType('my-plugin/project-card', {
  edit: ({ attributes, setAttributes }) => {
    const { projectId, showDescription, imageSize } = attributes;
    const blockProps = useBlockProps({ className: 'project-card-editor' });

    const projects = useSelect(select =>
      select('core').getEntityRecords('postType', 'project', { per_page: 50 })
    );

    const projectOptions = projects
      ? [{ label: '— выберите проект —', value: 0 }, ...projects.map(p => ({ label: p.title.rendered, value: p.id }))]
      : [{ label: 'Загрузка...', value: 0 }];

    return (
      <>
        <InspectorControls>
          <PanelBody title="Настройки блока">
            <SelectControl
              label="Проект"
              value={projectId}
              options={projectOptions}
              onChange={v => setAttributes({ projectId: Number(v) })}
            />
            <ToggleControl
              label="Показывать описание"
              checked={showDescription}
              onChange={v => setAttributes({ showDescription: v })}
            />
            <SelectControl
              label="Размер изображения"
              value={imageSize}
              options={[
                { label: 'Thumbnail', value: 'thumbnail' },
                { label: 'Medium', value: 'medium' },
                { label: 'Large', value: 'large' },
              ]}
              onChange={v => setAttributes({ imageSize: v })}
            />
          </PanelBody>
        </InspectorControls>
        <div {...blockProps}>
          {projectId
            ? <ProjectCardPreview projectId={projectId} showDescription={showDescription} />
            : <p>Выберите проект в панели справа</p>
          }
        </div>
      </>
    );
  },

  save: () => null, // динамический блок — рендер через PHP
});

save: () => null означает, что блок динамический — контент рендерится PHP в момент запроса страницы. Это предпочтительно для блоков, данные которых меняются (записи из БД).

PHP-рендеринг динамического блока

register_block_type(__DIR__ . '/blocks/project-card', [
    'render_callback' => 'my_plugin_render_project_card',
]);

function my_plugin_render_project_card(array $attributes): string {
    $project_id      = absint($attributes['projectId'] ?? 0);
    $show_desc       = (bool) ($attributes['showDescription'] ?? true);
    $image_size      = sanitize_key($attributes['imageSize'] ?? 'large');

    if (!$project_id) return '';

    $project = get_post($project_id);
    if (!$project || $project->post_status !== 'publish') return '';

    $thumbnail = get_the_post_thumbnail($project_id, $image_size, ['class' => 'project-card__image']);
    $title     = esc_html($project->post_title);
    $permalink = esc_url(get_permalink($project_id));
    $excerpt   = $show_desc ? '<p class="project-card__desc">' . esc_html(get_the_excerpt($project)) . '</p>' : '';

    $wrapper_attributes = get_block_wrapper_attributes(['class' => 'project-card']);

    return "<article {$wrapper_attributes}>
        {$thumbnail}
        <h3 class=\"project-card__title\"><a href=\"{$permalink}\">{$title}</a></h3>
        {$excerpt}
    </article>";
}

get_block_wrapper_attributes() добавляет классы из supports.color и другие атрибуты, которые Gutenberg генерирует автоматически.

Блок с innerBlocks

Блоки-контейнеры принимают дочерние блоки через InnerBlocks:

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

const ALLOWED_BLOCKS = ['core/paragraph', 'core/heading', 'my-plugin/cta-button'];
const TEMPLATE = [
  ['core/heading', { level: 3, placeholder: 'Заголовок секции' }],
  ['core/paragraph', { placeholder: 'Описание...' }],
  ['my-plugin/cta-button', {}],
];

// В edit:
<InnerBlocks allowedBlocks={ALLOWED_BLOCKS} template={TEMPLATE} templateLock={false} />

// В save:
<InnerBlocks.Content />

Сборка

Блоки собираются через @wordpress/scripts:

{
  "scripts": {
    "build": "wp-scripts build",
    "start": "wp-scripts start",
    "lint:js": "wp-scripts lint-js"
  },
  "devDependencies": {
    "@wordpress/scripts": "^27.0.0"
  }
}

wp-scripts настроен под WordPress по умолчанию: знает о @wordpress/* как о внешних зависимостях, генерирует asset.php с хешем версии для корректной инвалидации кеша.

Расширение существующих блоков через filters

Не всегда нужен новый блок — иногда достаточно добавить атрибут или панель к существующему:

import { addFilter } from '@wordpress/hooks';
import { createHigherOrderComponent } from '@wordpress/compose';

// Добавляем атрибут "data-section" к любому блоку
addFilter('blocks.registerBlockType', 'my-plugin/add-section-id', (settings) => {
  settings.attributes = {
    ...settings.attributes,
    sectionId: { type: 'string', default: '' },
  };
  return settings;
});

// Добавляем поле в InspectorControls
const withSectionIdControl = createHigherOrderComponent(BlockEdit => {
  return (props) => {
    const { attributes, setAttributes } = props;
    return (
      <>
        <BlockEdit {...props} />
        <InspectorControls>
          <PanelBody title="Якорная ссылка">
            <TextControl
              label="ID секции"
              value={attributes.sectionId}
              onChange={v => setAttributes({ sectionId: v })}
            />
          </PanelBody>
        </InspectorControls>
      </>
    );
  };
}, 'withSectionIdControl');

addFilter('editor.BlockEdit', 'my-plugin/section-id-control', withSectionIdControl);

Типовые сроки

Простой статический блок с 2–3 атрибутами — 4–8 часов. Динамический блок с PHP-рендером и панелью настроек — 1–2 дня. Блок-контейнер с innerBlocks, собственным стилем и server-side рендером — 2–4 дня. Набор из 5–10 связанных блоков для дизайн-системы — от 2 недель.