render_block │ хук-фильтр │ WP 5.0.0

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

Фильтр вызывается в WP_Block::render() для статических и динамических блоков, включая вложенные. У динамического блока к этому моменту уже выполнен render_callback.

После него вызывается фильтр render_block_(name) для конкретного типа блока. Изменения затрагивают вывод, но не сохранённый контент записи.

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

add_filter( 'render_block', 'wp_kama_render_block_filter', 10, 3 );

/**
 * Function for `render_block` 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_filter( $block_content, $block, $instance ){
	// filter...
	return $block_content;
}

$block_content(строка)

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

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

$block(массив)

Данные обрабатываемого блока.

• blockName(строка|null)
  Полное имя блока, например core/image. Для свободного HTML вне блоков может быть null.

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

• innerBlocks(массив массивов)
  Вложенные блоки. Каждый элемент имеет такую же структуру, как $block.

• innerHTML(строка)
  HTML из разобранной разметки блока без HTML вложенных блоков. Это не готовый результат рендеринга.

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

$instance(WP_Block)

Объект текущего блока WP_Block{}.

Примеры

#1 Добавить класс абзацам и заголовкам

Добавим класс article-text к первому HTML-тегу блоков core/paragraph и core/heading.

add_filter( 'render_block', 'my_add_text_block_class', 10, 2 );

function my_add_text_block_class( $block_content, $block ) {

	if ( ! in_array( $block['blockName'], [ 'core/paragraph', 'core/heading' ], true ) ) {
		return $block_content;
	}

	$processor = new WP_HTML_Tag_Processor( $block_content );

	if ( $processor->next_tag() ) {
		$processor->add_class( 'article-text' );
	}

	return $processor->get_updated_html();
}

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

В дополнительных настройках нужного блока укажем CSS-класс needs-wrapper. При выводе обернём такой блок в контейнер.

add_filter( 'render_block', 'my_wrap_marked_block', 10, 2 );

function my_wrap_marked_block( $block_content, $block ) {
	if ( ! $block_content ) {
		return $block_content;
	}

	$classes = preg_split( '/\s+/', $block['attrs']['className'] ?? '' );

	if ( ! in_array( 'needs-wrapper', $classes, true ) ) {
		return $block_content;
	}

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