В этой части мы напишем Javascript для регистрации и настройки нашего пользовательского блока. В конце мы зарегистрируем скрипт в PHP и напишем необходимый PHP-код, чтобы WordPress распознал его как новый блок.
Сначала краткое примечание о том, как получить доступ к функциям и компонентам WordPress Gutenberg.
Глобальный wpпакет и деструктуризация
Когда мы находимся в файле Javascript, поставленном в очередь в редакторе Gutenberg, у нас есть доступ к глобальному объекту/пакету: wp. Это очень большой объект Javascript, содержащий множество полезных компонентов и функций, которые мы будем использовать для создания блоков. При написании Javascript для пользовательских блоков вы будете ссылаться на wpдовольно много.
Поэтому как в современном Javascript, так и в React принято деструктурировать то, что мы хотим использовать. По сути, это просто означает, что мы определяем локальные переменные из частей более крупной структуры. Например, первая функция, которую мы будем использовать registerBlockType(), существует внутри wp.blocks. Мы могли бы вызвать функцию следующим образом:
wp.blocks.registerBlockType();Но проще деструктурировать так:
const { registerBlockType } = wp.blocks;
registerBlockType();Теперь вы можете обращаться к функции напрямую, не добавляя к ней префикс ее структуры. Это становится намного полезнее, когда мы ссылаемся на функции или компоненты, которые мы будем часто повторять.
В этой серии мы проведем реструктуризацию, и по мере продвижения в руководстве мы увидим, насколько читабельнее и короче становится наш код.
Регистрация нового блока
registerBlockType()В пакете доступна функция регистрации нового пользовательского блока wp.blocks. Он принимает два параметра; сначала строка с пространством имен и именем блока, а затем объект с полной конфигурацией блока.
Гутенберг ожидает, что все блоки будут иметь пространство имен и имя, определяемое косой чертой между ними. Пространство имен гарантирует, что имя вашего блока не будет конфликтовать с любыми другими блоками, которые могут использовать то же имя. Все блоки в WordPress используют пространство имен core. Например, стандартный блок абзаца в WordPress имеет имя core/paragraph. Если вы выберете другое пространство имен, вы также можете создать блок с именем абзаца без каких-либо проблем.
Выберите уникальное для вас пространство имен slug-version. В этой серии я буду использовать пространство имен awp(сокращенная версия A White Pixel).
Откройте исходный файл, который мы создали на последнем шаге; src/block-awhitepixel-myfirstblock.js, в редакторе. Сначала позвоним registerBlockTypeиз деструктурированного wp.blocks, с именем awp/firstblock. Настройте свое имя и пространство имен по ходу дела.
const { registerBlockType } = wp.blocks;
registerBlockType('awp/firstblock', {
// Your block configuration and code here
});Во втором параметре, объекте конфигурации блока, нам нужно определить несколько свойств, чтобы он был успешно зарегистрирован. Помните, что конфигурация блока — это объект, а это значит, что вам нужно писать все в виде пар ключ + значение, разделенных запятой. Существует довольно много возможных свойств конфигурации, поэтому давайте рассмотрим их, и в конце мы увидим окончательный код.
Требуется: название
Первым обязательным свойством является title. Это имя, которое будет отображаться при выборе между блоками. Задайте для этого свойства любое имя в строке.
Мы добавим следующее в качестве заголовка:
title: 'My first block',PS: Мы вернемся к тому, как мы записываем все строки в нашем блоке, чтобы убедиться, что они могут быть переведены в части 8. Но пока мы не будем усложнять и будем писать просто строки.
Требуется: категория
Свойство categoryопределяет, в какой категории блоков появится ваш блок, когда вы выбираете блоки для вставки в редакторе. Возможные значения: common, formatting, layout, widgets, embed.
Поместим его в commonкатегорию первого блока.
category: 'common',Дополнительно: значок
Если вы использовали Gutenberg, вы, вероятно, заметили, что все блоки имеют значки. Вы можете добавить значок в свой блок либо с помощью строки, которая ссылается на любой из Dashicons WordPress, либо вы можете предоставить собственный svgэлемент.
Я просто выберу один из дашиконов WordPress, смайлик, но вы можете выбрать любой, какой захотите. Обратите внимание, что вы пропускаете включение «dashicons-» в имя класса значков.
icon: 'smiley',Дополнительно: описание
Вы можете предоставить описание, которое будет отображаться на боковой панели настроек (справа), когда блок активен.
Я просто добавлю быстрый текст в качестве примера:
description: 'Learning in progress',Необязательно: ключевые слова
Gutenberg поддерживает функцию поиска при выборе типов блоков. Вы можете предоставить массив возможных совпадений в свойстве keywords. Без keywordsнего вы бы нашли свой блок, только выполнив поиск по его имени.
Я добавлю exampleи test, чтобы мы могли легко найти наш пользовательский блок, когда начинаем вводить одно из этих ключевых слов.
keywords: ['example', 'test'],Необязательно: атрибуты
Свойство attributes— очень важное свойство, к которому мы будем часто возвращаться в этой серии руководств. Здесь вы храните свои структурированные данные и информацию, введенную пользователем для вашего блока. Вы можете представить это как переменные. Мы не будем добавлять его сейчас, но мы обязательно вернемся к этому довольно скоро.
(Вид) обязательно: изменить и необязательно: сохранить
В свойствах editи saveна самом деле вы добавите весь свой код как для вывода редактора, так и для внешнего рендеринга. Оба этих свойства ожидают функцию, которая должна возвращать некоторый результат.
Свойство editописывает структуру вашего блока в редакторе. Собственность saveв основном обрабатывает две вещи; вывод вашего блока во внешнем интерфейсе, а также структуру того, как ваш блок сохраняется в базе данных. Вы будете работать в основном edit, так как именно здесь вы добавляете входные данные для ввода или выбора вещей и обновления данных блока. Функция saveне должна каким-либо образом обновлять или редактировать данные, она должна просто выводить.
Гутенберг должен иметь возможность реконструировать ваш блок со всеми его настройками в редакторе из того, что выводится saveфункцией (и атрибутами). Если Гутенберг когда-либо откроет сообщение, в котором ранее сохраненный вывод блока отличается (хотя бы немного) от того, что определено в сохранении, ваш блок станет недействительным.
Я могу гарантировать вам, что вы будете часто сталкиваться с этим при разработке пользовательских блоков. Когда это произойдет, вам нужно удалить блок (из точек на панели инструментов) и снова добавить его. Также рекомендую обновить браузер (F5 или CTRL+R).
В WordPress есть специальная страница документации для функций редактирования и сохранения блока, если вы хотите узнать больше.
Что касается нашего первого блока, давайте выведем что-нибудь базовое. Мы вернем одно и то же для обоих editи save; «:)», завернутый в <div>. Иконка блока все-таки смайлик.
Другие свойства
Есть дополнительные необязательные свойства для registerBlockType; parent, supports, transforms, exampleи styles. Мы пока пропустим их, так как большинство из них предназначены для более продвинутого или индивидуального построения блоков. Если вам интересно узнать об этом больше, взгляните на документацию WordPress.
Окончательный код блока регистра
Наш код теперь выглядит примерно так.
Этого достаточно, чтобы наш блок был успешно зарегистрирован как пользовательский блок. Давайте посмотрим на это на практике в редакторе Gutenberg.
Вы не забыли скомпилировать свой Javascript? На предыдущем шаге мы узнали, что не можем загрузить этот файл Javascript в Гутенберг; нам нужна скомпилированная версия. Обычно вы разрабатываете с npm run startзапуском в фоновом режиме, или вы можете просто запустить npm run buildодин раз. Это должно скомпилировать наш исходный Javascript и поместить его туда, где вы определили его размещение и имя в вашем файле webpack.config.js.
PHP-часть регистрации блока
Для каждого блока вам необходимо зарегистрировать файл Javascript, и это точно так же, как вы бы зарегистрировали любые другие скрипты в WordPress — с помощью [wp_register_script](https://developer.wordpress.org/reference/functions/wp_register_script/)(). Обратите внимание, что мы регистрируем скрипт, а не ставим его в очередь. Это связано с тем, что нам также необходимо вызвать функцию PHP для регистрации каждого пользовательского блока, и эта функция отвечает за постановку скрипта в очередь, когда это необходимо.
Я предпочитаю хранить код, связанный с Гутенбергом, в отдельном файле в своих темах. Но вы можете, и мы сделаем это в этом уроке, просто напишите весь PHP-код непосредственно внутри темы functions.phpдля простоты.
Я рекомендую использовать initхук для вашей функции, а не enqueue_block_assets. Мы можем совместить как регистрацию скрипта, так и регистрацию блока.
Функция PHP, которую мы будем использовать для регистрации нового блока, называется [register_block_type](https://developer.wordpress.org/reference/functions/register_block_type/)(). Как и в Javascript, registerBlockType()он принимает два параметра; пространство имен и имя блока, а также массив с аргументами. Убедитесь, что вы указали то же пространство имен и имя в PHP, что и в Javascript.
Во втором аргументе есть несколько возможных аргументов (некоторые из которых мы вернемся позже в этой серии). Но наиболее важным является то, editor_scriptгде вы указываете дескриптор (первый параметр wp_register_script()) зарегистрированного скрипта.
Вот и все!
Наш блок в редакторе Gutenberg
Теперь, когда вы обновляете свой редактор в каком-либо сообщении, вы должны найти наш блок — либо открыв категорию «Общие», либо выполнив поиск по любому из указанных вами ключевых слов или имени.
Наш блок отображает простой «:)» как в редакторе, так и во внешнем интерфейсе. На данный момент вы не можете ничего редактировать в блоке, но это то, чему мы научимся на следующих шагах!