get_block_wrapper_attributes() │ WP 5.6.0

Генерирует строку HTML-атрибутов для обёртки текущего блока, добавляя к ним все стили и возможности, объявленные через block supports.

Функция берёт атрибуты, которые WordPress сформировал для блока (классы выравнивания, цвета, отступы, пользовательские данные и т.д.), — и объединяет их с переданными вами значениями и возвращает готовую строку атрибутов тега блока.

Готовую строка уже очищена, поэтому её можно безопасно вставлять прямо в открывающий HTML тег обертки блока.

Метод уже экранирует каждое значение, поэтому не оборачивайте результат в esc_attr().

Контекст вызова

Функцию нужно вызывать только в месте, где фактически генерируется HTML блока — внутри функции-рендера блока или в PHP-шаблоне, который WordPress обрабатывает как блок-темплейт.

Другими словами, во время рендеринга конкретного экземпляра блока, когда движок уже:

  1. Проанализировал JSON-метаданные блока и узнал, какие «block supports» ему доступны.
  2. Слил атрибуты, проставленные редактором (цвета, выравнивание, кастомные классы и т.д.).
  3. Передал эти данные в ваш PHP-код.

Если вызвать её где-то вне этого контекста — например, в обычном хук-колбэке, который не связан с текущим блоком, — массив атрибутов ещё не будет сформирован, и функция вернёт пустую строку.

Функция работает на основе WP_Block_Supports::apply_block_supports(), которая зависит от правильно заполненной перменной WP_Block_Supports::$block_to_render, которая в свою очередь устанавливается перед вызовом render_callback функции в методе WP_Block::render():

WP_Block_Supports::$block_to_render = $this->parsed_block;

$block_content = (string) call_user_func( $this->block_type->render_callback, $this->attributes, $block_content, $this );
Работает на основе: WP_Block_Supports::apply_block_supports()

Хуков нет.

Возвращает

Строку.

  • Строка — готовых к вставке атрибутов.
  • Пустая строка — если итоговых атрибутов нет (ни от ядра, ни от вас).

Использование

get_block_wrapper_attributes( $extra_attributes );
$extra_attributes(array)

Дополнительные атрибуты для обёртки блока в виде массива строк. Например:

[
	'class'      => 'card card--highlight',
	'style'      => 'background:#f5f5f5',
	'data-id'    => 42,
	'aria-label' => __( 'Карточка', 'textdomain' ),
]

По умолчанию объединяются только style, class, id и aria-label. Любые другие ключи добавляются «как есть».

По умолчанию: []

Примеры

0

#1 Базовый вывод динамического блока

Добавляем атрибуты обёртки в рендер-функции блока.

function myplugin_render_dynamic_block( $attributes, $content ) {
	$wrapper_attributes = get_block_wrapper_attributes();

	return sprintf(
		'<div %1$s>%2$s</div>',
		$wrapper_attributes,
		$content
	);
}
0

#2 Дополнительные пользовательские атрибуты

Передаём собственный класс, inline-стиль и data-атрибут.

$wrapper_attributes = get_block_wrapper_attributes( [
	'class'      => 'card card--highlight',
	'style'      => 'background: #f5f5f5',
	'data-id'    => 42,
	'aria-label' => 'Карточка',
] );

echo sprintf( '<section %s>…</section>', $wrapper_attributes );

Список изменений

С версии 5.6.0 Введена.

Код get_block_wrapper_attributes() WP 7.0

wp-includes/class-wp-block-supports.php 
function get_block_wrapper_attributes( $extra_attributes = array() ) {
	$new_attributes = WP_Block_Supports::get_instance()->apply_block_supports();

	if ( empty( $new_attributes ) && empty( $extra_attributes ) ) {
		return '';
	}

	// Attribute values are concatenated or overridden depending on the attribute type.
	// This is hardcoded on purpose, as we only support a fixed list of attributes.
	$attribute_merge_callbacks = array(
		'style'      => static function ( $new_attribute, $extra_attribute ) {
			$styles = array_filter(
				array(
					rtrim( trim( $new_attribute ), ';' ),
					rtrim( trim( $extra_attribute ), ';' ),
				)
			);
			return safecss_filter_attr( implode( ';', array_filter( $styles ) ) );
		},
		'class'      => static function ( $new_attribute, $extra_attribute ) {
			$classes = array_merge(
				(array) preg_split( '/\s+/', $extra_attribute, -1, PREG_SPLIT_NO_EMPTY ),
				(array) preg_split( '/\s+/', $new_attribute, -1, PREG_SPLIT_NO_EMPTY )
			);
			$classes = array_unique( array_filter( $classes ) );
			return implode( ' ', $classes );
		},
		'id'         => static function ( $new_attribute, $extra_attribute ) {
			return '' !== $extra_attribute ? $extra_attribute : $new_attribute;
		},
		'aria-label' => static function ( $new_attribute, $extra_attribute ) {
			return '' !== $extra_attribute ? $extra_attribute : $new_attribute;
		},
	);

	$attributes = array();
	foreach ( $attribute_merge_callbacks as $attribute_name => $merge_callback ) {
		$new_attribute   = $new_attributes[ $attribute_name ] ?? '';
		$extra_attribute = $extra_attributes[ $attribute_name ] ?? '';
		$new_attribute   = is_string( $new_attribute ) ? $new_attribute : '';
		$extra_attribute = is_string( $extra_attribute ) ? $extra_attribute : '';

		if ( '' === $new_attribute && '' === $extra_attribute ) {
			continue;
		}

		$attributes[ $attribute_name ] = $merge_callback( $new_attribute, $extra_attribute );
	}

	foreach ( $extra_attributes as $attribute_name => $value ) {
		if ( ! isset( $attribute_merge_callbacks[ $attribute_name ] ) ) {
			$attributes[ $attribute_name ] = $value;
		}
	}

	if ( empty( $attributes ) ) {
		return '';
	}

	$normalized_attributes = array();
	foreach ( $attributes as $key => $value ) {
		$normalized_attributes[] = $key . '="' . esc_attr( $value ) . '"';
	}

	return implode( ' ', $normalized_attributes );
}

Редактор блоков (Gutenberg Гутенберг blocks)

Редактор Блоков (Гутенберг)