В этом посте подробно рассказывается, как добавить настройки цвета в ваш собственный блок WordPress Gutenberg. Мы узнаем, как добавить тот же компонент настроек цвета, который позволяет выбирать цвета из палитры и собственный цвет, который используется во многих блоках WordPress по умолчанию.
Вот что мы добавим в наш пользовательский блок:
Используя компоненты Гутенберга, мы можем очень легко реализовать эту палитру/цветовую секцию в нашем собственном пользовательском блоке. Вы можете определить настройки цвета, чтобы воздействовать на любой желаемый цвет; фон, цвет текста, цвет границы или что-то еще. Вы также можете добавить столько цветовых настроек, сколько хотите, внутри этой панели.
Прежде чем мы углубимся в код, вам нужно знать некоторые вещи. Не переходите сразу к коду, так как в следующем разделе многое объясняется, почему код должен делать это именно так.
Что нужно знать в первую очередь
Компоненты для реализации настроек палитры/цвета есть PanelColorSettingsи withColorsиз wp.blockEditorпакета. Компонент withColorsявляется так называемым компонентом более высокого порядка и должен быть реализован немного иначе, чем просто вывод обычного компонента. Позже я расскажу немного подробнее. Но сначала нам нужно знать основы того, как Гутенберг обрабатывает настройки цвета блока.
Как блоки Гутенберга обрабатывают настройки цвета
Существуют определенные правила того, как Гутенберг обрабатывает настройки цвета в блоках. Если вы когда-либо создавали тему, поддерживаемую Gutenberg, вы, вероятно, уже знакомы с этими правилами. Тем не менее, мы быстро пройдемся по ним, потому что мы должны обрабатывать это в нашем блочном коде.
- Когда выбран цвет палитры, элемент узла узла получает класс определенного шаблона. Класс начинается с "
has-", а затем идет ярлык палитры. Окончание зависит от того, на какой элемент должен воздействовать цвет. Для цвета текста он заканчивается на "-color". Для background-color он заканчивается на "-background-color". Например, блок с красным цветом палитры, выбранным в качестве цвета фона, получит класс "has-red-background-color". - Когда выбран пользовательский цвет (из палитры), элемент узла узла получит встроенный стиль с шестнадцатеричным кодом. Например, пользовательский цвет #DD0000, выбранный для цвета фона, получит атрибут "
style="background-color: #DD0000;".
Когда мы реализуем настройки цвета для нашего блока, нам нужно будет реализовать правильный класс и встроенный стиль. Мы сделаем это в конце этого урока.
Как работать сwithColors
Как упоминалось ранее withColors, это компонент более высокого порядка. В основном это означает, что компонент принимает компонент и возвращает новый компонент. В возвращаемом компоненте мы получаем полезные реквизиты из компонента более высокого порядка. Проще говоря, мы будем использовать withColorsдля возврата нашего собственного компонента для нашего пользовательского блока. Наш блочный компонент получает необходимые реквизиты для работы с цветами из файлов withColors.
Компонент withColorsобрабатывает состояние и множество функций для работы с цветами. И мы получаем много автоматизации в этом процессе. Это очень удобно для выяснения, является ли выбранный цвет цветом палитры (нам нужно добавить класс) или пользовательским цветом (нам нужно добавить встроенный стиль). withColorsупростить процесс сохранения выбранного цвета, каким бы он ни был, в атрибутах нашего блока. Кстати об атрибутах..
Атрибуты иwithColors
Очевидно, что вашему блоку нужны атрибуты для хранения выбранного цвета. Чтобы извлечь выгоду из автоматизации withColor для сохранения правильного цвета, вам действительно нужно определить два атрибута для каждой настройки цвета. Один для хранения слага цвета палитры, а другой для хранения шестнадцатеричного кода. Хотя есть некоторые правила.
Предположим, вы хотите добавить настройку цвета для цвета текста блока, поэтому вы решили определить атрибут с метким названием " textColor". Затем вам нужно будет определить другой атрибут в шаблоне " customYourOriginalAttribute". В этом примере второй атрибут должен быть назван " customTextColor". Обратите внимание на camelCase (заглавные буквы). Следование этому шаблону withColorsавтоматически:
- Если был выбран цвет палитры, атрибут «
textColor» будет содержать ярлык палитры. - Если был выбран пользовательский цвет, «
customTextColor» будет заполнен шестнадцатеричным кодом.
Эти двое работают в тандеме. Если выбран пользовательский цвет, textColorавтоматически будет undefined, и наоборот.
И, наконец, последнее, что нужно помнить: вам не нужно будет использовать setAttributes()для обновления атрибутов цвета! Предоставленные реквизиты withColorsвключают функцию, которая автоматически обновляет ваши атрибуты для вас. Все, что вам нужно сделать, это передать эту функцию onChangeсобытия PanelColorSettingsкомпоненту, и ваши атрибуты будут автоматически обновлены.
Хорошо, пришло время увидеть все это на практике!
Реализация настроек цвета в пользовательском блоке
Для начала у меня есть довольно бесполезный пользовательский блок, который не делает ничего, кроме отображения жестко запрограммированного текста. Это просто упрощает выделение того, что нам нужно в коде для добавления настроек цвета. У меня есть серия руководств по созданию собственных пользовательских блоков, если вы хотите узнать больше.
Примечание: я пишу весь код в ES6/ESNext. Сюда входят стрелочные функции, которые требуют особого внимания при настройке Babel/webpack. Если вы получаете ошибки в каком-то из приведенных ниже кодов, следуйте моему руководству по настройке Webpack и Babel для ES6/ESNext или настройте код так, чтобы он не использовал «экспериментальный синтаксис».
Это мой основной пользовательский блок, прежде чем делать что-либо с настройками цвета:
Это довольно просто. Обратите внимание, что editфункция просто ссылается на отдельный компонент BlockWithColorSettingsвместо того, чтобы записывать его как встроенный. Это облегчает реализацию в withColorsдальнейшем.
Ладно, пора применить настройки цвета к нашему блоку! В качестве примера я хочу настроить цвет текста.
Добавление атрибутов
Как упоминалось ранее, нам нужно определить два атрибута для каждой настройки цвета. И нам нужно проявлять особую осторожность в их именах. Я хочу добавить атрибут цвета текста, поэтому я называю атрибут textColor. Это означает, что я также добавлю атрибут customTextColor. Оба должны быть строкового типа.
Наши атрибуты готовы для хранения настроек цвета текста блока. Теперь пришло время реализовать withColorsи PanelColorSettings.
РеализацияwithColors
Как упоминалось ранее withColors, это компонент более высокого порядка, который должен возвращать компонент. Мы, очевидно, хотим, чтобы он возвращал наш компонент редактирования, BlockWithColorSettings. Но в качестве параметра withColorsмы предоставляем объект.
В переданном объекте withColorsнам нужно указать, withColorsкакой атрибут мы хотим использовать для хранения цвета и какой элемент он будет окрашивать (в нашем случае цвет текста, что означает правило CSS «цвет»). Информирование о правиле CSS гарантирует, что возвращаемые имена классов верны. Поскольку это цвет текста, нам нужны имена классов, например, «has–color».
Сначала некоторая деструктуризация наверху. withColorsнаходится в wp.blockEditorупаковке.
const { withColors } = wp.blockEditor;Мы изменим editфункцию на:
С этим кодом наш компонент BlockWithColorSettingsполучит дополнительные реквизиты:
props.textColor: объект, содержащий всю информацию о выбранном цвете. Если был выбран цвет палитры, в нем будут храниться свойства для шестнадцатеричного кода, ярлыка палитры, имени класса и т. д. Если был выбран пользовательский цвет, объект будет содержать шестнадцатеричный код. Шестнадцатеричный код всегда находится в свойствеcolor. А имя класса, (только если был выбран цвет палитры) будет задано в свойствеclass.props.setTextColor: Функция, которая будет обновлять наши атрибуты для нас. Мы предоставляем это для события настройки цвета,onChangeкак мы увидим позже. Функция обновит оба атрибутаtextColorи.customTextColorПоскольку мы следовали правилам именования, оно будет автоматически обновлятьсяcustomTextColor, даже если мы никогда не указывали это имя атрибута.
Обратите внимание, что функция «set», предоставленная как реквизит, будет следовать правилу: «setYourAttributeName». Поскольку мы указали textColor, функция называется setTextColor. Если бы вместо этого мы назвали наш атрибут awesomeColorи предоставили его в withColorsобъекте, функция set была бы названа setAwesomeColor().
РеализацияPanelColorSettings
Следующим шагом является реализация фактического раздела Inspector. Для этого мы добавляем PanelColorSettingsвнутри InspectorControlsкомпонент. Поскольку React требует, чтобы все было внутри одного корневого узла, мы также используем Fragment(from wp.elements), чтобы обернуть все внутри.
Сначала некоторая деструктуризация в верхней части файла:
const { Fragment } = wp.element;
const { InspectorControls, PanelColorSettings, withColors } = wp.blockEditor;И мы обновляем наш BlockWithColorSettingsкомпонент примерно так:
Как видите, в строке #2мы деструктурируем пропсы, полученные от withColors, textColorи setTextColor. Имейте в виду, что props.textColorэто объект, полученный от withColors, и props.attributes.textColorатрибут. Однако нам не нужно ссылаться на атрибут.
В качестве реквизита компонента PanelColorSettingsмы можем указать заголовок для раздела (заголовок в раскрывающемся поле в Инспекторе). Важным моментом здесь является реквизит, в colorSettingsкотором нам нужно предоставить массив объектов настройки цвета. Для каждой настройки цвета (в настоящее время у нас есть только одна) нам нужно предоставить некоторые свойства. Свойство valueожидает текущий выбранный шестнадцатеричный код (даже если был выбран цвет палитры). Это предусмотрено для нас в textColorреквизите внутри свойства color. Для onChangeсвойства мы просто предоставляем функцию «set», предоставляемую withColors, setTextColor. И, наконец, мы должны указать, labelчтобы пользователь знал, на какой элемент будет влиять этот цвет. Он появится прямо над областью выбора цвета.
Вот как наш компонент сейчас выглядит в редакторе Gutenberg:
Теперь он успешно обновляет наши атрибуты при выборе цветов. Вы можете видеть, что он запоминает ваш выбор цвета при сохранении поста.
Однако визуально ничего не происходит, когда вы меняете цвета. Выбор цвета сохраняется в атрибутах, но ни в редакторе, ни при предварительном просмотре сообщения изменение цвета не происходит. Это потому, что нам нужно добавить код для классов и стилей блока. Нам нужно сделать это как для editфункции (для редактора), так и для saveфункции (внешнего интерфейса). Это следующий шаг.
Обработка классов и встроенных стилей вedit
Нам нужно построить класс узла блока и атрибуты стиля в соответствии с выбранной настройкой цвета. К счастью, у withColorsнас есть некоторая автоматизация в этом. Помните, что props.textColorэто объект, который содержит всю необходимую нам информацию, включая имя класса.
Мы могли бы сделать что-то вроде этого:
В строке #20мы применяем критический класс и встроенный стиль к корневому узлу нашего блока. Перед этим мы создаем атрибут класса и встроенного стиля, проверяя props.textColorобъект.
После этого изменения ваш пользовательский блок теперь должен быть полностью функциональным в редакторе. Всякий раз, когда вы переключаете цвет, блок меняет цвет текста. Потрясающий! Последний шаг — сделать это и для saveфункции, чтобы мы также получили эти классы и стили во внешнем интерфейсе.
Обработка классов и встроенных стилей вsave
Концепция создания класса и встроенных стилей и их применения к корневому узлу такая же save, как и в edit. Но есть принципиальная разница. У saveнас нет реквизита, предоставленного withColors. И мы не можем добавлять в функцию компоненты более высокого порядка save. Таким образом, в saveфункции вся информация, которую мы имеем, — это атрибуты.
Хорошее эмпирическое правило — избегать жесткого кодирования имен классов «имеет-». Что, если WordPress решит изменить это правило в будущем? К счастью, у нас есть функция, которая может помочь нам сгенерировать правильные имена классов: getColorClassName().
Прежде чем мы забудем, давайте деструктурируем его. Он тоже есть в wp.blockEditorупаковке.
const { InspectorControls, PanelColorSettings, withColors, getColorClassName } = wp.blockEditor;Для использования getColorClassName()функции требуются два параметра. Сначала строка для правила CSS. Поскольку наша настройка цвета предназначена для цвета текста, мы предоставляем ‘ color‘. Это сообщает функции, что она должна возвращать имя класса «имеет-что-то-цвет», а не, например, «имеет-что-то-цвет фона». В качестве второго параметра нам нужно указать значение атрибута.
Атрибут стиля просто создается путем установки «цвета» в значение атрибута customTextColor, если он определен.
И, конечно же, не забудьте применить класс и стиль к корневому узлу вашего блока; как в очереди #12.
PS: если вы тестируете свой блок в редакторе при написании этого кода, вы получите ошибку блока. Это происходит потому, что теперь мы изменили вывод saveфункции, и все, что вы сохранили ранее, конфликтует. Вам придется удалить блок и снова добавить его.
После этого изменения ваш блок теперь должен правильно применять выбранный цвет текста и во внешнем интерфейсе.
Вот и все! Теперь вы успешно внедрили настройки цвета в свой блок. Если вы заинтересованы в добавлении нескольких настроек цвета (не только цвета текста), читайте дальше.
Примечание о нескольких настройках цвета
К настоящему времени вы должны быть в состоянии реализовать несколько настроек цвета. Вы можете добавить настройки для цвета фона, цвета текста, цвета границы или чего-то еще для своего блока. В этом разделе я сделаю краткий обзор того, что нам нужно сделать, чтобы реализовать несколько настроек цвета.
Предположим, что я также хочу добавить цвет фона в свой блок.
Сначала мне нужно определить новый атрибут с творческим именем backgroundColor. Я также определяю еще один атрибут customBackgroundColor.
В editфункции я изменяю объект, предоставленный withColorsкак таковой:
withColors({textColor: 'color', backgroundColor: 'background-color'})Это говорит о том withColors, что мой textColorатрибут относится к правилу CSS «color» (для цвета текста), а атрибут backgroundColor— к правилу CSS «background-color«. withColorsтакже автоматически распознает и обновит атрибуты и customTextColor.customBackgroundColor
В PanelColorSettingsкомпоненте я передаю другой объект массиву в реквизит colorSettings. Вот так:
При этом вы должны получить две отдельные настройки цвета внутри окна Инспектора для настроек цвета.
Последним шагом является создание подходящих имен классов и стилей как в, так editи в save. Это довольно простой шаг, так как он просто правильно создает строку или объект стиля. Помните, что имя вашего класса должно поддерживать несколько цветовых классов (например, если были выбраны и цвет текста, и цвет фона). Просто добавьте пробел между каждым именем класса.
PS: Если вам нужно обрабатывать много имен классов для вашего блока, вам может быть полезна установка classnamesпакета. Почти все компоненты в Гутенберге используют эту библиотеку, чтобы упростить объединение имен классов.
Заключение и полный код
Теперь вы должны были узнать, как реализовать настройки цвета в своем пользовательском блоке. Я надеюсь, что это было полезно для вас! Мне пришлось добавить эту функцию в свой проект, и я действительно не мог найти никакой информации или хорошей документации. Итак, это результат объединения всего, что я узнал по этой теме после множества проб и ошибок.
Вот окончательный код всего примера пользовательского блока с настройкой цвета текста: