Создание пользовательского блока Гутенберга — Часть 3: Реквизит и компоненты WordPress
В предыдущем шаге этой серии руководств было описано, как зарегистрировать пользовательский блок как в Javascript, так и в PHP. На этом этапе мы узнаем, как использовать компоненты WordPress для добавления различных полей и настроек.
Чтобы использовать компоненты WordPress в нашем блоке, нам нужно сначала узнать о свойствах.
Реквизит
Реквизиты — это основная функция React, которая в основном представляет собой способ передачи переменных или функций другим компонентам. Если вы не знакомы с реквизитами React, вы можете прочитать официальное руководство React об этом.
WordPress предоставляет некоторые реквизиты для функций edit
и в файлах. Внутри этих свойств мы получаем доступ к важным вещам, таким как атрибуты и метод для обновления наших атрибутов. Мы подробно рассмотрим атрибуты на следующем шаге! save``registerBlockType()
До сих пор в нашем блоке мы писали функцию для edit
и save
так:
Вы должны привыкнуть добавлять параметр props
к обоим edit
и save
, например:
Теперь у вас есть полный доступ к переменной props
и всему, что в ней содержится, изнутри edit
и save
. Если вам интересно, вы можете добавить console.log(props);
в edit
функцию перед return
оператором. Вы должны увидеть, какие реквизиты доступны в отладчике консоли.
Использование компонентов WordPress
Как упоминалось ранее, у нас есть доступ к огромной библиотеке компонентов и полезных функций внутри глобального пакета wp
. Вы найдете готовые к использованию компоненты для любого типа компонентов, связанных с вводом данных, о которых вы только можете подумать. Примеры включают ввод текста, ввод форматированного текста, раскрывающиеся списки, переключатели, флажки, кнопки в разных стилях, загрузчик мультимедиа и средства выбора цвета. Есть также функции и компоненты для более расширенного функционала. Например, запрос контента WordPress (сообщений, категорий и т. д.) либо с помощью встроенных функций, либо с помощью REST API.
Это и проще, и рекомендуется использовать компоненты пользовательского интерфейса WordPress. Это делается для того, чтобы дизайн и функциональность были максимально оптимизированы, чтобы не смущать и не раздражать пользователей.
Но, к сожалению, на момент написания этого документа документации для Гутенберга очень мало. Я нашел лучший способ узнать о том, что находится внутри wp
пакета и как на самом деле работают компоненты, заглянув в их официальный репозиторий Gutenberg Github. Некоторые из пакетов (папок) имеют текст readme, который предлагает немного документации. Взгляните на readme для кнопки или переключателя, например.
Репозиторий Github должен соответствовать тому, что находится внутри wp
пакета (в зависимости от того, какая у вас версия и какую ветку вы просматриваете в Github). Это означает, что каждая папка, которую вы видите в корневом packages
каталоге Github, находится в глобальном wp
пакете. В качестве примера вспомните, что функция, которую мы использовали на предыдущем шаге, registerBlockType()
находилась внутри wp.blocks
, а это значит, что вы найдете исходный код этой функции, экспортированный внутри packages/blocks/
.
Поскольку я разработал несколько пользовательских блоков Gutenberg и немного покопался в репозитории Github, я обнаружил, что есть несколько пакетов, которые содержат наиболее распространенные функции, используемые для создания пользовательских блоков. Я включу их ниже.
Для более полного обзора доступных компонентов я рекомендую загрузить мою бесплатную электронную книгу, посвященную доступным компонентам в Гутенберге! Содержит самые распространенные и полезные компоненты с документацией по пропсам и примерами кода:
Краткий обзор наиболее распространенных пакетов, которые вы будете использовать для блоков
Очевидно, что доступно гораздо больше, но ниже показано то, что наиболее распространено для разработки блоков. Мы будем использовать большинство из них, если не все, в этой серии руководств. Всякий раз, когда вы хотите использовать компонент, вам нужно знать, в каком пакете он находится.
wp.components
Вы найдете большинство компонентов ввода пользовательского интерфейса внутри файлов wp.components
. Примерами являются различные вводы текста, выбор, флажки, переключатели, перетаскиваемые компоненты, кнопки, средство выбора цвета, средство выбора даты и т. д. Вы также найдете компоненты пользовательского интерфейса, которые можно использовать для панели инструментов блока и содержимого боковой панели настроек (называемой InspectorControls) в редакторе.
Проверьте папки в репозитории Github.
wp.blockEditor и wp.editor
В этих двух пакетах вы найдете полезные компоненты для форматированного текста, обработки изображений/загрузчика мультимедиа, а также компоненты для фактического добавления панелей инструментов или настраиваемых панелей инспектора (боковой панели).
В конце этой серии мы рассмотрим создание динамических блоков, в которых мы будем использовать PHP для рендеринга вывода блока, и для этого мы будем использовать компонент из wp.editor
.
Насколько я понимаю, большинство компонентов wp.editor
появилось в ранние дни Гутенберга, но особенно после WordPress 5.3 многие из них были перенесены в wp.blockEditor
. Если вы используете компонент wp.editor
, который WordPress планирует переместить, на wp.blockEditor
данный момент он не выйдет из строя, но в консольном отладчике вы получите предупреждения о том, что он устарел и что вы должны переключиться на него, wp.blockEditor
когда сможете. И наоборот, если вы следуете этой серии с более старой версией WordPress, по какой-то причине вы можете столкнуться с ошибками при вызове компонентов, которые еще не перемещены wp.blockEditor
.
wp.элемент
Внутри wp.element
вы найдете компоненты, соответствующие компонентам React. Например Component
(что соответствует React.Component
) и Fragment
( React.Fragment
). Мы будем использовать их, когда начнем разбивать наш код на отдельные компоненты.
wp.i18n
Как следует из названия, wp.i18n
пакет содержит функции для обработки перевода. Он содержит те же функции перевода, что и в PHP; например __()
и _e()
. Мы подробно рассмотрим это в <<<>>>>, когда узнаем, как переводить наш блок.
wp.data
Пакет wp.data
предназначен для запроса данных WordPress вне редактора. Существуют компоненты для отправки сообщений, withSelect
которые select
мы будем использовать позже в этой серии для запроса сообщений внутри нашего блока.
wp.compose
Предыдущий пакет и wp.compose
предназначены для более продвинутого построения блоков. Внутри этого пакета мы найдем компоненты и функции для создания так называемых компонентов более высокого порядка. Компоненты более высокого порядка — это метод шаблона в React для повторного использования компонентов и логики, и мы будем использовать его в сочетании с wp.data
для запроса сообщений.
Хватит разговоров – как вы используете некоторые из этих компонентов на практике?
Как упоминалось ранее; чтобы использовать компоненты WordPress, вам нужно знать, где они находятся. Надеюсь, мой обзор выше в сочетании с репозиторием Github даст вам некоторое представление о том, где их взять.
Не забывайте, что вы всегда можете добавить любые обычные теги HTML, такие как div, span, заголовки и так далее. Просто не забудьте следовать рекомендациям React по атрибутам. Например class
, это зарезервированное ключевое слово в React (для создания компонентов на основе классов), поэтому, если вы хотите добавить класс в элемент HTML, вам нужно использовать className
.
Примечание. При разработке не забудьте инициировать npm run start
компиляцию кода.
В качестве простого примера давайте попробуем несколько компонентов, чтобы увидеть, как они выглядят. Мы деструктурируем их из соответствующих пакетов и используем в нашей edit
функции.
Это, например, приведет к тому, что наш блок будет выглядеть так в редакторе.
Вы заметите, что вы будете получать сообщения об ошибках в консоли, когда вы их вводите, и что она не сохранит то, что вы вводите, при обновлении сообщения (и обновлении). Это потому, что нам не хватает реквизита компонентов, который является подключением к атрибутам, где хранятся все данные нашего блока. Реквизиты отвечают за передачу сохраненных значений и функций, ответственных за обновление наших атрибутов, когда что-то изменяется во входных данных. Это то, что мы сделаем на следующем шаге, где мы, наконец, начнем писать реальный код.