Як додати спеціальні стилі блоків до блоків WordPress Gutenberg

Дещо менш відома функція Gutenberg — це можливість налаштовувати різні стилі для блоків. Ви можете зареєструвати стільки різних стилів для будь-якого типу блоку, щоб надати одному блоку різні дизайни. Можливі стилі для блоків відображаються як розділ у правій частині редактора. Кожен стиль отримує власний попередній перегляд. Якщо ви правильно обробляєте стилі, перемикання між стилями повинно негайно оновити дизайн як у редакторі, так і в інтерфейсі.

Документація WordPress щодо цієї функції наразі не така повна та інформативна, як могла б бути. Тож у цій публікації ми детально розглянемо, як ви можете додавати власні стилі блоків і як ви повинні обробляти їх стилі.

Ця функція працює так: щоразу, коли Gutenberg виявляє, що тип блоку зареєстровано як мінімум один стиль, вікно «Стилі» автоматично з’являється праворуч у редакторі. У ньому редактор може вибрати стиль за замовчуванням або будь-який стиль блоку, який було додано.

У попередніх версіях (принаймні до WordPress 5.3) для реєстрації спеціального стилю потрібно було також зареєструвати стиль за замовчуванням («без стилю»). На щастя, це було виправлено в останніх версіях WordPress, тому тепер вам потрібно лише зареєструвати власні стилі, і WordPress автоматично додасть стиль за замовчуванням.

Ви можете зареєструвати власні стилі блоків двома способами; з PHP або з Javascript. Ми розглянемо обидва. Але спочатку трохи «а-ха» щодо обробки ваших стилів.

Примітка про стилі постановки в чергу для Gutenberg

Може виникнути деяка плутанина щодо того, як і куди додати свої стилі (файли CSS); лише для редактора, для інтерфейсу або однієї таблиці стилів для обох. Одна з головних цілей редактора Gutenberg — переконатися, що ви можете належним чином переглянути, як виглядатиме вміст вашої публікації в редакторі. Тому рекомендуємо переконатися, що ваші власні стилі застосовуються як у редакторі, так і в інтерфейсі.

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

Іншим рішенням є використання, наприклад, SCSS або LESS і налаштування @importsтаким чином, що вам потрібно буде написати стилі блоку лише один раз, і це буде застосовано як до редактора, так і до інтерфейсу. Як ви побачите нижче, коли використовуєте PHP для реєстрації власних стилів блоків, у вас є ще один варіант; щоб додати вбудовані стилі. Ці стилі будуть застосовані як у редакторі, так і в інтерфейсі. У інтерфейсі вони будуть додані WordPress як настроювані вбудовані елементи <style type="text/css">...</style>всередині заголовка.

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

Як застосувати стиль до власних стилів блоку

Спеціальні стилі блоку будуть додані як клас певного шаблону до крайнього тегу HTML для блоку.

Клас CSS для стилів блоків додано у формі «is-style-<stylename>». Якщо ви, наприклад, назвете свій стиль " outline", блок отримає клас " is-style-outline".

Однак ви можете зіткнутися з тим, що редактор Gutenberg у деяких випадках замінить ваш стиль. Я рекомендую додати до стилю редактора селектор editor-styles-wrapper, щоб ваші стилі «виграли». Майте на увазі, що цей клас не існує у інтерфейсі, тому для безпеки вам може знадобитися додати два селектори, наприклад (якщо ви використовуєте ту саму таблицю стилів і для редактора, і для інтерфейсу):

.is-style-colored-bottom-border, 
.editor-styles-wrapper .is-style-colored-bottom-border { 
    border-bottom: 2px solid purple;
}

Додавання спеціальних стилів блоків за допомогою PHP

Для додавання спеціального типу блоку за допомогою PHP ми використовуємо функцію [register_block_style](https://developer.wordpress.org/reference/functions/register_block_style/)(). У документації, на жаль, бракує інформації про те, який хук слід використовувати, але мені пощастило з хуком init.

Вам потрібно знати назву простору імен Gutenberg для вашого типу блоку, щоб додати до нього власний стиль. Усі стандартні блоки WordPress мають простір імен ” core", за яким іде a /та версія їхньої назви. Наприклад, ім’я Гутенберга для стандартного блоку абзацу – core/paragraph.

Реєстрація спеціального стилю блоку виконується в найпростішій формі так:

Наведений вище код додає спеціальний стиль блоку до типу блоку Heading, що призведе до створення класу is-style-colored-bottom-borderдля будь-якого Heading, який вибрав цей стиль.

Ця функція надає вам два способи додавання вашого CSS (якщо ви не додали його іншим способом); або надаючи вбудований CSS у вигляді рядка, або надаючи зареєстрований дескриптор таблиці стилів, який WordPress поставить у чергу для вас, якщо це необхідно.

Якщо ви бажаєте додати вбудований стиль (пам’ятайте, це вплине як на редактор, так і на інтерфейс), додайте елемент «inline_style» до виклику функції та запишіть повний CSS у вигляді рядка як його значення:

Якщо ви бажаєте поставити функцію в чергу таблиці стилів, надайте її дескриптор елементу «style_handle».

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

Додавання власних стилів блоків за допомогою Javascript

Якщо ви віддаєте перевагу додаванню стилів блоків за допомогою Javascript, це так само просто, як і з PHP.

Вам потрібно буде поставити в чергу файл Javascript лише на хук редактора: enqueue_block_editor_assets. Можливо, ваш сценарій не потребуватиме жодних залежностей, але я вважаю за краще додати принаймні «wp-blocks» як залежність.

add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script(
        'myguten-script', 
        get_template_directory_uri(). '/assets/js/myguten.js', 
        ['wp-blocks']
    );
});

Налаштуйте назву та розташування файлу відповідно до свого проекту.

У вашому файлі Javascript ви використовуєте функцію registerBlockStyle()в wp.blocksоб’єкті для реєстрації власних стилів блоку. Додавання того самого стилю блоку, що ми зробили в PHP вище, виглядатиме так:

wp.blocks.registerBlockStyle('core/heading', {
    name: 'colored-bottom-border',
    label: 'Colored bottom border'
});

І це все! Простенька.

Скасування реєстрації стилів блоку

Так само, як ви можете зареєструвати стиль блоку, стиль блоку також можна скасувати. Можливо, ви хочете видалити деякі стандартні стилі блоків WordPress? Як і у випадку реєстрації стилів блоків, ви також можете скасувати реєстрацію стилів блоків за допомогою PHP або Javascript. Але вибір між цими двома методами більше не є вибором переваги.

Ви не можете скасувати реєстрацію блоку в PHP, якщо його було зареєстровано в Javascript, і навпаки. Тож вам потрібно з’ясувати, як зареєстровано стиль, який ви хочете видалити, і зіставити його з PHP або Javascript. Я вважаю, що всі стилі блоків WordPress додаються за допомогою Javascript (не цитуйте мене на цьому!). Отже, якщо ви хочете видалити деякі з них, вам потрібно буде піти шляхом Javascript.

Скасування реєстрації стилю блоку в PHP виконується викликом функції unregister_block_style(), яка вказує тип блоку та назву стилю, який потрібно видалити. Наприклад, скасування реєстрації стилю, доданого вище в цьому дописі (припускаючи, що він був зареєстрований у PHP), виглядатиме так:

add_action('init', function() {
    unregister_block_style('core/heading', 'colored-bottom-border');
});

Скасування реєстрації стилю блоку в Javascript виконується подібно до функції unregisterBlockStyle()в wp.blocksоб’єкті. Однак у Javascript є питання про те, який сценарій запускається першим, і ви можете зіткнутися з проблемами, коли ваш сценарій запускається до реєстрації. Щоб вирішити цю проблему, ми використовуємо еквівалент Гутенберга «документ готовий» (jQuery(document).ready(function() { ... });) jQuery, а також додаємо ще одну залежність до вашого сценарію.

Давайте почнемо з додавання нової залежності сценарію до вашого файлу Javascript у чергу до «wp-edit-post»:

add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script(
        'myguten-script', 
        get_template_directory_uri(). '/assets/js/myguten.js', 
        ['wp-blocks', 'wp-edit-post']
    );
});

І всередині вашого файлу Javascript загорніть свій виклик функції unregister усередину wp.domReady(function() { ... }), ось так:

wp.domReady(function() {
    wp.blocks.unregisterBlockStyle('core/quote', 'large');
});

Як показано в коді вище, за допомогою Javascript тепер ми можемо видалити «Великий» стиль WordPress у блоці цитат. Якщо ви спробуєте зробити те саме з PHP, це не спрацює.

Додаткова примітка щодо скасування реєстрації стилів блоку

Ви можете помітити, що навіть якщо ви успішно видалили будь-які власні стилі блоку з блоку, поле «Стилі» в редакторі не зникне. Він залишається на місці лише з вибором "За замовчуванням" всередині нього. Якщо ви хочете повністю видалити поле «Стилі», щоб не плутати редакторів, ви також можете просто скасувати реєстрацію стандартного стилю (наприклад, wp.blocks.unregisterBlockStyle('core/quote', 'large')). Це повністю видалить поле «Стилі» з редактора Gutenberg.