Створення спеціального блоку Гутенберга – Частина 3: Реквізити та компоненти WordPress

У попередньому кроці цієї серії посібників було описано, як зареєструвати спеціальний блок у Javascript і PHP. На цьому кроці ми дізнаємося, як використовувати компоненти WordPress для додавання різних типів полів і налаштувань.

Для того, щоб використовувати компоненти WordPress у нашому блоці, нам потрібно спочатку знати про реквизити.

Реквізит

Props є основною функцією 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, я виявив, що є кілька пакетів, які містять найпоширеніші функції, що використовуються для створення користувацьких блоків. Я включаю їх нижче.

Для більш повного огляду доступних компонентів я рекомендую завантажити мою безкоштовну електронну книгу, яка описує доступні компоненти в Gutenberg! Він містить найпоширеніші та корисні компоненти з документацією про властивості та приклади коду:

Короткий огляд найпоширеніших пакетів, які ви використовуватимете для блоків

Очевидно, що є набагато більше доступних, але нижче наведено те, що є найпоширенішим для розробки блоків. Ми використаємо більшість, якщо не всі з них у цій серії посібників. Щоразу, коли ви хочете використовувати компонент, вам потрібно знати, в якому пакеті він знаходиться.

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.element

Всередині 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, headings тощо. Просто не забувайте дотримуватися вказівок React щодо атрибутів. Наприклад class, це зарезервоване ключове слово в React (для створення компонентів на основі класу), тому, якщо ви хочете додати клас до елемента HTML, вам потрібно використовувати className.

Примітка: під час розробки не забудьте розпочати npm run startкомпіляцію коду.

Як простий приклад, давайте спробуємо кілька компонентів, щоб побачити, як вони виглядають. Ми деструктуруємо їх із відповідних пакетів і використовуємо їх у нашій editфункції.

Це, наприклад, призведе до того, що наш блок виглядатиме так у редакторі.

Ви помітите, що ви отримуватимете повідомлення про помилки в консолі, коли ви вводите їх, і що вона не збереже те, що ви вводите після оновлення публікації (і оновлення). Це тому, що нам не вистачає реквізитів для компонентів, тобто з’єднання з атрибутами, де зберігаються всі наші блокові дані. Реквізити відповідають за передачу збережених значень і функцій, відповідальних за оновлення наших атрибутів, коли щось змінюється в наших вхідних даних. Це те, що ми зробимо на наступному кроці, де ми нарешті почнемо писати код по-справжньому.