Функция register_block_style() в WordPress с примерами

Функция register_block_style() позволяет зарегистрировать новый стиль для существующего блока в редакторе блоков WordPress (Gutenberg). Это позволяет разработчикам добавлять новые визуальные варианты для блоков без необходимости их дублирования, просто определяя новый CSS-стиль.

register_block_style( string|string[] $block_name, array $style_properties ): bool

Параметры

• $block_name (string|array, обязательный) — Название блока, к которому будет применяться стиль, включая пространство имен. Например, 'core/quote'. Можно передать массив с несколькими именами блоков.
• $style_properties(array, обязательный) — Ассоциативный массив свойств стиля. Основные свойства:
  • name (string, обязательный) — Идентификатор стиля, который будет использоваться в классе CSS.
  • label (string, обязательный) — Человеко-читаемая метка для стиля, которая будет отображаться в редакторе блоков.
  • inline_style (string, необязательный) — Строка с CSS-кодом для применения стиля.
  • style_handle (string, необязательный) — Имя заранее зарегистрированного стиля, который должен быть подключен там, где используется этот стиль блока.
  • is_default (bool, необязательный) — Указывает, является ли этот стиль стилем по умолчанию для блока.

Возвращаемое значение

• bool — Возвращает true, если стиль блока успешно зарегистрирован, и false, если произошла ошибка.

Примечания

• Минимальные обязательные свойства — это name и label. Они определяют идентификатор CSS-класса и название стиля, которое будет отображаться в редакторе.
• Можно использовать свойство inline_style для быстрого добавления CSS в заголовок страницы или style_handle для подключения ранее зарегистрированных стилей.
• Если вы не знаете точное название блока, его можно найти с помощью консольной команды: wp.blocks.getBlockTypes().

Пример 1: Регистрация стиля для блока цитаты (core/quote)

Добавим новый стиль под названием «Blue Quote» для блока цитаты.

if ( function_exists( 'register_block_style' ) ) {
    register_block_style(
        'core/quote',
        array(
            'name'         => 'blue-quote',
            'label'        => __( 'Blue Quote', 'textdomain' ),
            'inline_style' => '.wp-block-quote.is-style-blue-quote { color: blue; font-style: italic; }',
        )
    );
}

В этом примере:

• 'blue-quote' — это идентификатор стиля, который будет добавлен к блоку как класс is-style-blue-quote.
• 'Blue Quote' — это метка, которая будет видна пользователям в редакторе.
• CSS-код задает синий цвет текста и курсив для цитаты.

Пример 2: Стиль для блока заголовка (core/heading) с подключением файла стилей

Добавим стиль для блока заголовка, который будет подключать ранее зарегистрированный CSS-файл.

if ( function_exists( 'register_block_style' ) ) {
    register_block_style(
        'core/heading',
        array(
            'name'        => 'custom-heading',
            'label'       => __( 'Custom Heading', 'textdomain' ),
            'style_handle'=> 'custom-heading-css', // Регистрируем стиль через style_handle
        )
    );
}

Здесь:

• 'custom-heading' — идентификатор стиля.
• 'custom-heading-css' — это зарегистрированный стиль, который можно подключить с помощью функции wp_enqueue_style().

Пример 3: Регистрация стиля для нескольких блоков

Зарегистрируем один стиль для нескольких блоков одновременно.

if ( function_exists( 'register_block_style' ) ) {
    register_block_style(
        array( 'core/paragraph', 'core/heading' ),
        array(
            'name'         => 'highlighted-text',
            'label'        => __( 'Highlighted Text', 'textdomain' ),
            'inline_style' => '.wp-block-paragraph.is-style-highlighted-text, .wp-block-heading.is-style-highlighted-text { background-color: yellow; padding: 5px; }',
        )
    );
}

В этом примере:

• Стиль 'highlighted-text' применяется одновременно к блокам параграфа и заголовка.
• CSS код добавляет желтый фон для текста с небольшим отступом.

Полезные советы

• Для регистрации стиля блока следует использовать хуки, такие как init или enqueue_block_assets, чтобы стили были подключены в нужный момент.
• Чтобы добавить уникальные стили для разных блоков, используйте точные названия блоков, которые можно получить в консоли браузера через wp.blocks.getBlockTypes().

Связанные функции

• unregister_block_style() — Удаляет ранее зарегистрированный стиль блока.
• register_block_type() — Регистрирует новый тип блока.
• wp_enqueue_style() — Подключает CSS-файлы на сайт.

Заключение

Функция register_block_style() — это отличный способ расширить возможности редактора блоков WordPress, добавляя новые стили для существующих блоков. Она упрощает процесс стилизации блоков, позволяя разработчикам создавать кастомные визуальные решения, не изменяя существующую структуру блоков.