Как добавить пользовательские стили блоков в блоки WordPress Gutenberg

Менее известная функция Гутенберга — возможность устанавливать разные стили для блоков. Вы можете зарегистрировать столько разных стилей для любого типа блока, чтобы придать одному и тому же блоку разные рисунки. Возможные стили для блоков отображаются в виде раздела в правой части редактора. Каждый стиль получает свой предварительный просмотр. Если вы правильно обрабатываете стили, переключение между стилями должно немедленно обновить дизайн как внутри редактора, так и во внешнем интерфейсе.

Документация WordPress для этой функции в настоящее время не настолько полная и информативная, как могла бы быть. Итак, в этом посте мы подробно рассмотрим, как вы можете добавить свои собственные стили блоков и как вы должны обрабатывать их стили.

Эта функция работает следующим образом: всякий раз, когда Гутенберг обнаруживает, что тип блока зарегистрирован как минимум один стиль, в правой части редактора автоматически появляется поле «Стили». Внутри него редактор может выбирать между стилем по умолчанию или любым другим стилем. блочный стиль, который был добавлен.

В более ранних версиях (по крайней мере, до WordPress 5.3) для регистрации пользовательского стиля требовалось также зарегистрировать стиль по умолчанию («без стиля»). К счастью, это было исправлено в самых последних версиях WordPress, так что теперь вам нужно только зарегистрировать свои собственные стили, и WordPress автоматически добавит стиль по умолчанию.

Вы можете зарегистрировать пользовательские стили блоков двумя способами; с PHP или с Javascript. Мы рассмотрим оба. Но сначала несколько слов о том, как обращаться с вашими стилями.

Примечание о постановке стилей в очередь для Гутенберга

Может быть некоторая путаница в том, как и где добавлять ваши стили (файлы 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», за которым следует /буква и сокращенная версия их имени. Например, имя Гутенберга для стандартного блока абзаца — core/paragraph.

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

Приведенный выше код добавляет пользовательский стиль блока к типу блока «Заголовок», что приведет к тому, что класс is-style-colored-bottom-borderбудет привязан к любому заголовку, выбравшему этот стиль.

Эта функция предоставляет вам два метода добавления вашего 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 (jQuery(document).ready(function() { ... });), а также добавляем еще одну зависимость в ваш сценарий.

Давайте начнем с добавления новой зависимости скрипта от вашего файла 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 оберните вызов функции отмены регистрации внутри wp.domReady(function() { ... }), например:

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

Как видно из приведенного выше кода, с помощью Javascript мы теперь можем удалить «большой» стиль WordPress в блоке Quote. Если вы попытаетесь сделать то же самое с PHP, это не сработает.

Дополнительное примечание об отмене регистрации стилей блоков

Вы можете заметить, что даже если вы успешно удалили все пользовательские стили блоков в блоке, поле «Стили» в редакторе не исчезнет. Он остается на месте только с выбором «По умолчанию» внутри него. Если вы хотите полностью удалить поле «Стили», чтобы не путать редакторов, вы также можете просто отменить регистрацию стиля по умолчанию (например, wp.blocks.unregisterBlockStyle('core/quote', 'large')). Это полностью удалит поле «Стили» из редактора Гутенберга.