render_block_(name) │ хук-фильтр │ WP 5.7.0

Позволяет изменить HTML указанного блока после его рендеринга.

Вместо (name) указывается полное имя блока с пространством имён:

• render_block_core/paragraph - абзац.
• render_block_core/image - изображение.
• render_block_core/group - группа.
• render_block_my-plugin/example - пользовательский блок.

Фильтр вызывается в WP_Block::render() после общего фильтра render_block. Работает для статических и динамических блоков, включая вложенные. Изменяет вывод, но не сохранённый контент записи.

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

add_filter( 'render_block_(name)', 'wp_kama_render_block_name_filter', 10, 3 );

/**
 * Function for `render_block_(name)` filter-hook.
 * 
 * @param string   $block_content The block content.
 * @param array    $block         The full block, including name and attributes.
 * @param WP_Block $instance      The block instance.
 *
 * @return string
 */
function wp_kama_render_block_name_filter( $block_content, $block, $instance ){
	// filter...
	return $block_content;
}

$block_content(строка)

HTML блока после рендеринга и обработки предыдущими фильтрами.

Верните изменённый HTML или исходное значение. Пустая строка '' уберёт блок из вывода, но сам рендеринг к этому моменту уже выполнен.

$block(массив)

Данные блока.

• blockName(строка)
  Полное имя блока, например core/image.

• attrs(массив)
  Атрибуты блока из его HTML-комментария. Атрибуты, извлекаемые из HTML, могут отсутствовать.

• innerBlocks(массив массивов)
  Вложенные блоки с такой же структурой данных.

• innerHTML(строка)
  Исходный HTML блока без HTML вложенных блоков. Не равнозначен готовому $block_content.

• innerContent(массив)
  Фрагменты HTML и значения null на местах вложенных блоков.

$instance(WP_Block)

Текущий объект WP_Block{}.

Примеры

#1 Добавить CSS-класс всем блокам «Абзац»

Используем WP_HTML_Tag_Processor{}, чтобы добавить класс к тегу <p>, сохранив остальные атрибуты.

add_filter( 'render_block_core/paragraph', 'my_add_paragraph_class' );

function my_add_paragraph_class( $block_content ) {

	$processor = new WP_HTML_Tag_Processor( $block_content );

	if ( $processor->next_tag( 'P' ) ) {
		$processor->add_class( 'custom-paragraph' );
	}

	return $processor->get_updated_html();
}

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

Проверим атрибут sizeSlug и обернём изображения размера large в дополнительный контейнер.

add_filter( 'render_block_core/image', 'my_wrap_large_image', 20, 2 );

function my_wrap_large_image( $block_content, $block ) {

	if ( '' === trim( $block_content ) ) {
		return $block_content;
	}

	if ( 'large' !== ( $block['attrs']['sizeSlug'] ?? '' ) ) {
		return $block_content;
	}

	return '<div class="large-image-wrapper">' . $block_content . '</div>';
}

Проверять $block['blockName'] здесь не нужно: обработчик вызывается только для core/image.