Кастомные блоки в Gutenberg (блоковый редактор WordPress)

Gutenberg (блоковый редактор WordPress) предоставляет мощный API для создания кастомных блоков. Это позволяет разработчикам создавать собственные блоки с уникальной функциональностью и дизайном, которые можно использовать в редакторе наравне со стандартными блоками.

Основные компоненты API для создания кастомных блоков

1. Регистрация блока:
   Для создания кастомного блока используется функция registerBlockType. Она регистрирует блок и определяет его поведение.
2. Атрибуты блока:
   Атрибуты — это данные, которые хранятся в блоке (например, текст, изображения, настройки).
3. Редактор (Edit):
   Компонент, который отображает блок в редакторе Gutenberg.
4. Фронтенд (Save):
   Компонент, который определяет, как блок будет отображаться на фронтенде (на сайте).
5. Дополнительные настройки:
   Поддержка иконок, категорий, стилей и других параметров.

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

1. Создание структуры плагина

Создайте папку для плагина в wp-content/plugins/, например, my-custom-block. Внутри создайте файл my-custom-block.php и папку src/ для JavaScript-кода.

2. Регистрация плагина

В файле my-custom-block.php добавьте следующий код:

<?php
/*
Plugin Name: Мой кастомный блок
Description: Пример создания кастомного блока для Gutenberg.
Version: 1.0
Author: Ваше имя
*/

function my_custom_block_init() {
    wp_register_script(
        'my-custom-block-editor', // Хэндл скрипта
        plugins_url('build/index.js', __FILE__), // Путь к JS-файлу
        array('wp-blocks', 'wp-element', 'wp-editor'), // Зависимости
        filemtime(plugin_dir_path(__FILE__) . 'build/index.js') // Версия
    );

    register_block_type('my-plugin/my-custom-block', array(
        'editor_script' => 'my-custom-block-editor', // Скрипт для редактора
    ));
}
add_action('init', 'my_custom_block_init');

3. Создание блока на JavaScript

В папке src/ создайте файл index.js:

import { registerBlockType } from '@wordpress/blocks';
import { TextControl } from '@wordpress/components';
import { useBlockProps } from '@wordpress/block-editor';

registerBlockType('my-plugin/my-custom-block', {
    title: 'Мой кастомный блок', // Название блока
    icon: 'smiley', // Иконка блока
    category: 'widgets', // Категория блока
    attributes: {
        content: {
            type: 'string',
            default: 'Привет, мир!', // Значение по умолчанию
        },
    },
    edit: (props) => {
        const blockProps = useBlockProps();
        const { attributes, setAttributes } = props;
        const { content } = attributes;

        return (
            <div {...blockProps}>
                <TextControl
                    label="Введите текст"
                    value={content}
                    onChange={(value) => setAttributes({ content: value })}
                />
            </div>
        );
    },
    save: (props) => {
        const blockProps = useBlockProps.save();
        const { attributes } = props;
        const { content } = attributes;

        return <div {...blockProps}>{content}</div>;
    },
});

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

Для сборки JavaScript-кода используйте @wordpress/scripts. Установите зависимости:

npm init -y
npm install @wordpress/scripts --save-dev

Добавьте скрипты в package.json:

"scripts": {
    "build": "wp-scripts build",
    "start": "wp-scripts start"
}

Запустите сборку:

npm run build

5. Активация плагина

• Перейдите в админку WordPress.
• Активируйте плагин «Мой кастомный блок».
• Откройте редактор Gutenberg и найдите блок «Мой кастомный блок».

Основные компоненты блока

1. Атрибуты:
   Атрибуты — это данные, которые хранятся в блоке. В примере выше это content.
2. Редактор (Edit):
   Компонент edit определяет, как блок выглядит в редакторе. В примере используется TextControl для ввода текста.
3. Фронтенд (Save):
   Компонент save определяет, как блок будет отображаться на сайте. В примере текст выводится внутри div.
4. Иконка и категория:

• icon: Иконка блока (можно использовать Dashicons или SVG).
• category: Категория блока (например, common, widgets, formatting).

Расширенные возможности

1. Стили для блока

Вы можете добавить стили для блока в редакторе и на фронтенде:

registerBlockType('my-plugin/my-custom-block', {
    // ...
    style: 'my-custom-block-style', // Стили для фронтенда
    editor_style: 'my-custom-block-editor-style', // Стили для редактора
});

Затем подключите стили в PHP:

wp_register_style(
    'my-custom-block-style',
    plugins_url('style.css', __FILE__)
);
wp_register_style(
    'my-custom-block-editor-style',
    plugins_url('editor.css', __FILE__)
);

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

InnerBlocks позволяет создавать блоки с вложенными блоками:

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

registerBlockType('my-plugin/my-custom-block', {
    // ...
    edit: () => {
        return (
            <div>
                <InnerBlocks />
            </div>
        );
    },
    save: () => {
        return (
            <div>
                <InnerBlocks.Content />
            </div>
        );
    },
});

3. Поддержка переводов

Для поддержки переводов используйте @wordpress/i18n:

import { __ } from '@wordpress/i18n';

registerBlockType('my-plugin/my-custom-block', {
    title: __('Мой кастомный блок', 'my-plugin'),
    // ...
});

Заключение

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