У цьому дописі детально описано, як додати налаштування кольору до вашого спеціального блоку Gutenberg WordPress. Ми дізнаємося, як додати той самий компонент налаштувань кольору, який має можливість вибору кольорів палітри та користувацьких кольорів, які використовують багато стандартних блоків WordPress.
Ось що ми додамо до нашого спеціального блоку:
Використовуючи компоненти Гутенберга, ми можемо дуже легко застосувати цю палітру/розділ кольору до нашого власного спеціального блоку. Ви можете визначити параметри кольору, щоб впливати на будь-який потрібний колір; фон, колір тексту, колір рамки чи будь-який інший. Ви також можете додати скільки завгодно налаштувань кольору на цю панель.
Перш ніж ми заглибимося в код, є деякі речі, про які вам потрібно знати. Не переходьте до коду, оскільки в наступному розділі буде багато пояснень, чому код повинен робити це так, як він.
Що потрібно знати в першу чергу
Компоненти для реалізації налаштувань палітри/кольору є PanelColorSettings
в withColors
пакеті wp.blockEditor
. Компонент withColors
є так званим компонентом вищого порядку, і його потрібно реалізувати дещо інакше, ніж просто виводити звичайний компонент. Пізніше я розповім трохи більше. Але спочатку нам потрібно знати основи того, як Гутенберг обробляє налаштування кольорів блоку.
Як блоки Гутенберга обробляють налаштування кольорів
Існують певні правила того, як Гутенберг обробляє параметри кольору в блоках. Якщо ви коли-небудь створювали тему з підтримкою Gutenberg, ви, ймовірно, уже знайомі з цими правилами. Тим не менш, ми швидко їх переглянемо, тому що ми повинні вирішити це в нашому блоковому коді.
- Коли вибрано колір палітри, елемент блоку вузла отримає клас певного шаблону. Клас починається з «
has-
», а потім іде слаг палітри. Кінцівка залежить від того, на який елемент має впливати колір. Для кольору тексту він закінчується на «-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
. Обидва мають бути типу string.
Наші атрибути готові для збереження налаштування кольору тексту блоку. Тепер настав час реалізувати 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
об’єкті, функція набору буде названа 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
ми можемо надати назву для розділу (заголовок у вікні, що згортається, в Inspector). Важливим тут є проп, 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
". Це повідомляє функції, що вона має повертати ім’я класу «has-something-color», а не «has-something-background-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
компоненті я надаю інший об’єкт масиву prop colorSettings
. Ось так:
Завдяки цьому ви маєте отримати два окремих налаштування кольорів у вікні інспектора для налаштувань кольорів.
Останнім кроком є створення відповідних назв класів і стилів в обох edit
і save
. Це досить простий крок, оскільки він просто створює правильний об’єкт рядка або стилю. Пам’ятайте, що назва вашого класу має підтримувати кілька класів кольорів (наприклад, якщо вибрано і колір тексту, і колір фону). Просто додайте пробіл між назвами кожного класу.
PS: якщо вам потрібно обробляти багато імен класів для вашого блоку, вам може бути корисно встановити classnames
пакет. Практично всі компоненти Gutenberg використовують цю бібліотеку, щоб легше комбінувати імена класів.
Висновок і повний код
Тепер ви повинні навчитися впроваджувати параметри кольору у вашому спеціальному блоці. Сподіваюся, це було вам у пригоді! Мені довелося додати цю функцію до свого проекту, але я справді не міг знайти жодної інформації чи хорошої документації. Отже, це результат консолідації всього, що я дізнався про цю тему, після багатьох спроб і помилок.
Ось остаточний код у цілому для прикладу спеціального блоку з налаштуванням кольору тексту: