WordPress Gutenberg Block API: создание пользовательских блоков

Russian (Pусский) translation by Anna Goorikova (you can also view the original English article)

Новый редактор WordPress (под кодовым названием Gutenberg) должен быть выпущен в версии 5.0. Сейчас самое время разобраться с этим, прежде чем он попадет в ядро WordPress. В этой серии я покажу вам, как работать с Block API и создавать свои собственные блоки контента, которые вы можете использовать для создания своих постов и страниц.

В предыдущем посте мы увидели, как использовать набор инструментов create-guten-block для создания плагина, содержащего образец блока, с которым мы можем работать. Мы можем легко расширить это по мере необходимости, но это хорошая идея, чтобы знать, как создать блок с нуля, чтобы полностью понять все аспекты разработки блока Гутенберга.

WordPress

WordPress Gutenberg Block API: Block Look and Feel

David Gwyer

В этом посте мы создадим второй блок в нашем плагине my-custom-block для отображения случайного изображения из веб-службы PlaceIMG. Вы также сможете настроить блок, выбрав категорию изображения в раскрывающемся списке выбора.

Но сначала мы узнаем, как блочные сценарии и стили ставятся в очередь, прежде чем перейти к крайне важной функции registerBlockType(), которая является фундаментальной для создания блоков в Гутенберге.

Добавление в очередь блок-скриптов и стилей

Чтобы добавить JavaScript и CSS, необходимые для наших блоков, мы можем использовать два новых хука WordPress, предоставленных Гутенбергом:

enqueue_block_editor_assets
enqueue_block_assets

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

Хук enqueue_block_editor_assets добавляет скрипты и стили только в редактор администратора. Это делает его идеальным для постановки в очередь JavaScript для регистрации блоков и CSS для стилизации элементов пользовательского интерфейса для настроек блоков.

Тем не менее, для вывода блоков вам нужно, чтобы ваши блоки отображались в редакторе так же, как и во внешнем интерфейсе. Использование enqueue_block_assets делает это простым, поскольку стили автоматически добавляются как в редактор, так и в интерфейс. Вы также можете использовать этот хук для загрузки JavaScript, если это необходимо.

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

add_action( 'enqueue_block_assets', 'load_front_end scripts' );
function load_front_end scripts() {
    if( !is_admin() {
        // enqueue front end only scripts and styles here
    }
}

Чтобы поставить в очередь скрипты и стили с помощью этих двух новых хуков, вы можете использовать стандартные функции wp_enqueue_style() и wp_enqueue_scripts(), как обычно.

Однако вы должны убедиться, что вы используете правильные зависимости скрипта. Для постановки сценариев в редакторе вы можете использовать следующие зависимости:

скрипты: array( 'wp-blocks', 'wp-i18n', 'wp-element', 'wp-components' )
стили: array( 'wp-edit-blocks' )

И когда вы ставите в очередь стили как для редактора, так и для внешнего интерфейса, вы можете использовать эту зависимость:

array( 'wp-blocks' )

Здесь стоит упомянуть, что настоящие файлы, поставленные в очередь нашим плагином my-custom-block, представляют собой скомпилированные версии JavaScript и CSS, а не файлы, содержащие исходный код JSX и Sass.

Об этом следует помнить, когда файлы ставятся в очередь вручную. Если вы попытаетесь поставить в очередь необработанный исходный код, включающий React, ES6+ или Sass, то вы столкнетесь с многочисленными ошибками.

Вот почему полезно использовать инструментарий, такой как create-guten-block, поскольку он обрабатывает и ставит в очередь скрипты для вас автоматически!

Регистрация блоков Гутенберга

Чтобы создать новый блок, нам нужно зарегистрировать его в Gutenberg, вызвав registerBlockType() и передав имя блока плюс объект конфигурации. Этот объект имеет довольно много свойств, которые требуют правильного объяснения.

Во-первых, давайте посмотрим на имя блока. Это первый параметр, представляющий собой строку, состоящую из двух частей: пространства имен и имени самого блока, разделенных символом слеш.

Например:

registerBlockType(
    'block-namespace/block-name',
    {
        // configuration object
    }
);

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

Второй параметр registerBlockType() является объектом настроек и требует указания ряда свойств:

title (строка): отображается в редакторе как метка блока с возможностью поиска
description (необязательная строка): описывает назначение блока
icon (необязательный элемент Dashicon или JSX): значок, связанный с блоком
category (строка): где блок появляется в диалоговом окне Add blocks
keywords (необязательный массив): до трех ключевых слов, используемых при поиске блоков
attributes (необязательный объект): обрабатывает данные динамического блока
edit (функция): функция, которая возвращает разметку для отображения в редакторе
save (function): функция, которая возвращает разметку, которая будет отображаться на внешнем интерфейсе
useOnce (необязательный логический): запретить добавление блока более одного раза
support (необязательный объект): определяет поддерживаемые блоком функции

Предполагая, что мы используем JSX для разработки блоков, вот как может выглядеть пример вызова registerBlockType() для очень простого блока:

registerBlockType(
    'my-unique-namespace/ultimate-block',
    {
        title: __( 'The Best Block Ever', 'domain' ),
        icon: 'wordpress',
        category: 'common',
        keywords: [ __( 'sample', 'domain' ), __( 'Gutenberg', 'domain' ), __( 'block', 'domain' ) ],
        edit: () => <h2>Welcome to the Gutenberg Editor!</h2>,
        save: () => <h2>How am I looking on the front end?</h2>
    }
);

Обратите внимание, что мы не включили запись для description, attributes, useOnce и supports свойств. Любые поля, которые являются необязательными (и не относятся к вашему блоку), могут быть безопасно пропущены. Например, поскольку в этом блоке не было динамических данных, нам не нужно беспокоиться об указании каких-либо атрибутов.

Давайте теперь рассмотрим свойства объекта конфигурации registerBlockType() более подробно одно за другим.

Title и Description

При вставке или поиске блока в редакторе заголовок будет отображаться в списке доступных блоков.

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

Block title and description

Поля заголовка и описания в идеале должны быть заключены в функции i18n, чтобы обеспечить возможность перевода на другие языки.

Icon

По умолчанию вашему блоку назначен Dashicon, но вы можете переопределить его, указав пользовательский Dashicon в поле icon.

Dashicons

Каждый Dashicon имеет префикс dashicons-, за которым следует уникальная строка. Например, значок шестеренки имеет название dashicons-admin-generic. Чтобы использовать его как значок блока, просто удалите префикс dashicons-, чтобы он был распознан, например, icon: 'admin-generic'.

Тем не менее, вы не ограничены использованием Dashicons в качестве свойства icon. Функция также принимает элемент JSX, что означает, что вы можете использовать любое изображение или элемент SVG в качестве значка вашего блока.

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

Keywords

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

keywords: [
    __( 'search', 'domain' ),
    __( 'for', 'domain' ),
    __( 'me', 'domain' ),
]

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

Хотя добавление ключевых слов не является обязательным, это отличный способ облегчить пользователям поиск ваших блоков.

Attributes

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

Однако, если ваш блок имеет дело с данными, которые могут измениться (например, с содержимым редактируемой текстовой области) или вам необходимо сохранить настройки блока, то использование атрибутов - это то, что вам нужно.

Атрибуты работают путем хранения данных динамического блока либо в содержимом поста, сохраненном в базе данных, либо в мета данных поста. В этом уроке мы будем использовать только атрибуты, которые хранят данные вместе с содержимым поста.

Чтобы извлечь данные атрибута, хранящиеся в содержимом поста, нам нужно указать, где он находится в разметке. Мы можем сделать это, указав селектор CSS, который указывает на данные атрибута.

Например, если наш блок содержал тег anchor, мы можем использовать его поле title в качестве нашего атрибута следующим образом:

attributes: {
    linktitle: {
        source: 'attribute',
        selector: 'a',
        attribute: 'title'
    }
}

Здесь имя атрибута - linktitle, который является произвольной строкой и может быть любым, что вам нравится.

Например, мы могли бы использовать этот атрибут, чтобы сохранить заголовок ссылки <a title="some title">, который был введен через текстовое поле в настройках блока. Это неожиданно делает поле заголовка динамическим и позволяет изменить его значение в редакторе.

Когда запись сохранена, значение атрибута вставляется в поле ссылки title. Аналогичным образом, когда загружается редактор, значение тега title извлекается из содержимого и вставляется в атрибут linktitle.

Есть и другие способы использования source для определения того, как содержимое блока хранится или извлекается с помощью атрибутов. Например, вы можете использовать источник 'text' для извлечения внутреннего текста из элемента абзаца.

attributes: {
    paragraph: {
    source: 'text',
    selector: 'p'
    }
}

Вы также можете использовать дочерний source, чтобы извлечь все дочерние узлы элемента в массив и сохранить его в атрибуте.

attributes: {
    editablecontent: {
        source: 'children',
        selector: '.parent'
    }
}

Это выбирает элемент с классом .parent и сохраняет все дочерние узлы в атрибуте editablecontent.

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

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

Привыкание к атрибутам может занять какое-то время, поэтому не беспокойтесь, если вы не до конца их поняли. Я бы порекомендовал взглянуть на раздел атрибутов справочника Гутенберга для более подробной информации и примеров.

Edit

Функция edit контролирует, как ваш блок появляется в интерфейсе редактора. Динамические данные передаются в каждый блок как props, включая любые пользовательские атрибуты, которые были определены.

Обычной практикой является добавление className={props.className} к элементу основного блока, чтобы вывести класс CSS, специфичный для вашего блока. WordPress не добавляет это для вас в редакторе, поэтому его нужно добавлять вручную для каждого блока, если вы хотите включить его.

Использование props.className является стандартной практикой и рекомендуется, так как она предоставляет способ настройки стилей CSS для каждого отдельного блока. Формат сгенерированного класса CSS: .wp-block-{namespace}-{name}. Как видите, это основано на пространстве имен/именах блоков и делает его идеальным для использования в качестве уникального идентификатора блока.

Функция редактирования требует, чтобы вы возвращали действительную разметку с помощью метода render(), который затем используется для визуализации вашего блока в редакторе.

Save

Подобно функции edit, команда save отображает визуальное представление вашего блока, но на передней панели. Он также получает данные динамического блока (если определены) через props.

Одно из главных отличий заключается в том, что props.className недоступен внутри save, но это не проблема, поскольку он автоматически вставляется Гутенбергом.

Supports

Свойство supports принимает объект с логическими значениями, чтобы определить, поддерживает ли ваш блок определенные основные функции.

Доступны следующие свойства объекта:

anchor (по умолчанию false): позволяет напрямую связываться с конкретным блоком
customClassName (true): добавляет поле в инспекторе блоков, чтобы определить имя пользовательского класса className для блока
className (true): добавляет className к корневому элементу блока на основе имени блока
html (true): позволяет редактировать разметку блока напрямую

Свойство `useOnce`

Это полезное свойство, которое позволяет ограничить добавление блока на страницу более одного раза. Примером этого является встроенный блок More, который нельзя добавить на страницу, если он уже есть.

useOnce property

Как видите, после добавления блока More значок блока становится серым и не может быть выбран. По умолчанию для свойства useOnce установлено значение false.

Давайте проявим креативность!

Настало время использовать знания, которые мы получили до настоящего времени, для реализации надежного рабочего примера блока, который делает что-то более интересное, чем просто вывод статического содержимого.

Мы будем строить блок для вывода случайного изображения, полученного с помощью внешнего запроса на сайт PlaceIMG, который возвращает случайное изображение. Кроме того, вы сможете выбрать категорию возвращаемого изображения с помощью выпадающего списка.

Our random image block

Для удобства мы добавим наш новый блок в тот же плагин my-custom-block, а не создадим новый плагин. Код для блока по умолчанию находится в папке /src/block, поэтому добавьте еще одну папку в /src под названием random-image и добавьте три новых файла:

index.js: регистрирует наш новый блок
editor.scss: для стилей редактора
style.scss: стили для редактора и внешнего интерфейса

Кроме того, вы можете скопировать папку /src/block и переименовать ее, если вы не хотите печатать все вручную. Убедитесь, что переименовали block.js в index.js внутри новой папки блоков.

Мы используем index.js для имени файла основного блока, поскольку это позволяет нам упростить оператор импорта внутри blocks.js. Вместо того, чтобы включать путь и полное имя файла блока, мы можем просто указать путь к папке блока, и import автоматически найдет файл index.js.

Откройте файл /src/blocks.js и добавьте ссылку на наш новый блок в верхней части файла, прямо под существующим оператором импорта.

1	import './random-image';

Внутри /src/random-image/index.js добавьте следующий код, чтобы запустить наш новый блок.

//  Import CSS.
import './style.scss';
import './editor.scss';

const { __ } = wp.i18n;
const { registerBlockType, query } = wp.blocks;

registerBlockType( 'cgb/block-random-image', {
    title: __( 'Random Image' ),
    icon: 'format-image',
    category: 'common',
    keywords: [
        __( 'random' ),
        __( 'image' )
    ],
    edit: function( props ) {
        return (
            <div className={ props.className }>
                <h3>Random image block (editor)</h3>
            </div>
        );
    },
    save: function( props ) {
        return (
            <div>
                <h3>Random image block (front end)</h3>
            </div>
        );
    }
} );

Это устанавливает структуру нашего блока и он очень похож на стандартный блочный код, сгенерированный инструментарием create-guten-block.

Мы начнем с импорта редактора и внешних таблиц стилей, а затем извлечем некоторые часто используемые функции из wp.i18n и wp.blocks в локальные переменные.

Внутри registerBlockType() были введены значения для свойств title, icon, category и keywords, в то время как функции edit и save в настоящее время просто выводят статическое содержимое.

Добавьте блок случайных изображений на новую страницу, чтобы увидеть сгенерированный результат.

Bare bones block output

Убедитесь, что вы по-прежнему просматриваете файлы на предмет изменений, чтобы любой исходный код блока (JSX, ES6+, Sass и т.д.) транслировался в действительный JavaScript и CSS. Если вы не просматриваете файлы на предмет изменений, откройте окно командной строки в корневой папке плагина my-custom-block и введите npm start.

Вы можете быть удивлены, почему нам не нужно было добавлять PHP-код для постановки дополнительных блочных сценариев. Сценарии блоков для блока my-custom-block ставятся в очередь через init.php, но нам не нужно ставить сценарии в очередь специально для нашего нового блока, так как об этом позаботился наш create-guten-block.

Пока мы импортируем наш основной файл блока в src/blocks.js (как мы это делали выше), нам не нужно делать никакой дополнительной работы. Весь код JSX, ES6+ и Sass будет автоматически скомпилирован в следующие файлы:

dist/blocks.style.build.css: стили для редактора и внешнего интерфейса
dist/blocks.build.js: JavaScript только для редактора
dist/blocks.editor.build.css: стили только для редактора

Эти файлы содержат JavaScript и CSS для всех блоков, поэтому нужно ставить в очередь только один набор файлов, независимо от количества созданных блоков!

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

attributes: {
    category: {
        type: 'string',
        default: 'nature'
    }
}

Это создает атрибут под названием category, который хранит строку со значением по умолчанию 'nature'. Мы не указали место в разметке для хранения и получения значения атрибута, поэтому вместо него будут использоваться специальные комментарии HTML. Это поведение по умолчанию, если вы пропустите источник атрибута.

Нам нужен какой-то способ изменения категории изображений, который мы можем сделать с помощью выпадающего списка. Обновите функцию edit следующим образом:

edit: function( props ) {
    const { attributes: { category }, setAttributes } = props;
    function setCategory( event ) {
        const selected = event.target.querySelector( 'option:checked' );
        setAttributes( { category: selected.value } );
        event.preventDefault();
    }
    return (
        <div className={ props.className }>
            Current category is: {category}
            <form onSubmit={ setCategory }>
                <select value={ category } onChange={ setCategory }>
                    <option value="animals">Animals</option>
                    <option value="arch">Architecture</option>
                    <option value="nature">Nature</option>
                    <option value="people">People</option>
                    <option value="tech">Tech</option>
                </select>
            </form>
        </div>
    );
}

Вот как это будет выглядеть:

Это сильно отличается от предыдущей статической функции edit, поэтому давайте рассмотрим изменения.

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

PlaceIMG image categories

Когда значение раскрывающегося списка изменяется, вызывается функция setCategory, которая находит текущую выбранную категорию, а затем, в свою очередь, вызывает функцию setAttributes. Это основная функция Гутенберга, которая корректно обновляет значение атрибута. Рекомендуется обновлять атрибут только с помощью этой функции.

Теперь, когда выбирается новая категория, значение атрибута обновляется и передается обратно в функцию edit, которая обновляет выдаваемое сообщение.

Image category updated

Мы должны выполнить последний шаг, чтобы получить случайное изображение для отображения. Нам нужно создать простой компонент, который будет принимать текущую категорию и выводить тег <img> со случайным изображением, полученным с сайта PlaceIMG.

Запрос, который мы должны сделать для PlaceIMG, имеет вид: https://placeimg.com/[width]/[height]/[category]

Мы пока сохраним ширину и высоту, поэтому нам нужно только добавить текущую категорию в конец URL-адреса запроса. Например, если категория 'nature', то полный URL-адрес запроса будет: https://placeimg.com/320/220/nature.

Добавьте компонент RandomImage перед registerBlockType():

1	function RandomImage( { category } ) {
2	const src = 'https://placeimg.com/320/220/' + category;
3	return <img src={ src } alt={ category } />;
4	}

Чтобы использовать его, просто добавьте его в функцию edit и удалите статическое выходное сообщение. Пока мы на этом, сделаем то же самое для функции save.

Полный файл index.js теперь должен выглядеть так:

//  Import CSS.
import './style.scss';
import './editor.scss';

const { __ } = wp.i18n;
const { registerBlockType, query } = wp.blocks;

function RandomImage( { category } ) {
    const src = 'https://placeimg.com/320/220/' + category;
    return <img src={ src } alt={ category } />;
}

registerBlockType( 'cgb/block-random-image', {
    title: __( 'Random Image' ),
    icon: 'format-image',
    category: 'common',
    keywords: [
        __( 'random' ),
        __( 'image' )
    ],
    attributes: {
        category: {
            type: 'string',
            default: 'nature'
        }
    },
    edit: function( props ) {
        const { attributes: { category }, setAttributes } = props;
        function setCategory( event ) {
            const selected = event.target.querySelector( 'option:checked' );
            setAttributes( { category: selected.value } );
            event.preventDefault();
        }

        return (
            <div className={ props.className }>
                <RandomImage category={ category } />
                <form onSubmit={ setCategory }>
                    <select value={ category } onChange={ setCategory }>
                        <option value="animals">Animals</option>
                        <option value="arch">Architecture</option>
                        <option value="nature">Nature</option>
                        <option value="people">People</option>
                        <option value="tech">Tech</option>
                    </select>
                </form>
            </div>
        );
    },
    save: function( props ) {
        const { attributes: { category } } = props;
        return (
            <div>
                <RandomImage category={ category } />
            </div>
        );
    }
} );

Наконец (пока) добавьте следующие стили в editor.scss, чтобы добавить цветную рамку вокруг изображения.

.wp-block-cgb-block-random-image  {
    select {
        padding: 2px;
        margin: 7px 0 5px 2px;
        border-radius: 3px;
    }
}

Вам также понадобятся некоторые стили в style.css.

 .wp-block-cgb-block-random-image  {
    background: #f3e88e;
    color: #fff;
    border: 2px solid #ead9a6;
    border-radius: 10px;
    padding: 5px;
    width: -webkit-fit-content;
    width: -moz-fit-content;
    width: fit-content;

    img {
        border-radius: inherit;
        border: 1px dotted #caac69;
        display: grid;
    }
}

Всякий раз, когда страница обновляется в редакторе или на внешнем интерфейсе, отображается новое случайное изображение.

Если вы видите одно и то же изображение, отображаемое снова и снова, вы можете выполнить жесткое обновление, чтобы предотвратить отображение изображения из кэша браузера.

Заключение

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

Попутно мы узнали, как ставить в очередь блочные сценарии и стили, и подробно рассмотрели функцию registerBlockType().

Вслед за этим мы применили теорию на практике и создали собственный блок с нуля для отображения случайного изображения из определенной категории с помощью веб-службы PlaceIMG.

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

Если вы следовали этому руководству и просто хотите поэкспериментировать с кодом, не вводя ничего, вы сможете загрузить последний плагин my-custom-block в следующем руководстве.