register_block_pattern() │ WP 5.5.0

Регистрирует новый блок-паттерн для редактора блоков (Gutenberg).

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

Хуков нет.

Возвращает

true|false.

• true - если шаблон успешно зарегистрирован.
• false - в случае ошибки.

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

register_block_pattern( $pattern_name, $pattern_properties );

$pattern_name(string) (обязательный)

Уникальное имя паттерна, включая пространство имён (например, my-plugin/hero-section).

$pattern_properties(array) (обязательный)

Ассоциативный массив с параметрами шаблона:

• title (string) (обязательный) — Читаемое название шаблона.
• content (string) (обязательный) — HTML-код блоков, составляющих шаблон.
• description (string) — Описание шаблона для панели вставки.
• categories (array) — Массив категорий, к которым относится шаблон.
• keywords (array) — Ключевые слова для поиска шаблона.

• viewportWidth (int) — Ширина предпросмотра шаблона в пикселях.

• blockTypes (array) — Массив блоков, с которыми ассоциирован шаблон.
  Задаёт, с какими блоками связан паттерн, и ограничивает его отображение только в этих блоках. Например, если указать 'blockTypes' => [ 'core/columns' ], шаблон будет доступен только при добавлении блока «Колонки».

  Это удобно, когда шаблон логически относится к какому-то конкретному блоку и не должен использоваться отдельно. Это упрощает работу с редактором — пользователь видит только те шаблоны, которые подходят для текущего контекста.

• postTypes (array) — Массив типов записей, для которых доступен шаблон.

• templateTypes (array) — Массив типов шаблонов, в которых применяется шаблон.
  Параметр templateTypes указывает, в каких шаблонах сайта (например, page, single) будет доступен блок-паттерн. Это работает в редакторе шаблонов (Site Editor) и позволяет показывать блок-паттерн только в нужных контекстах, например, только для страниц или записей. Упрощает интерфейс и делает блок-паттерны более целевыми.

• inserter (bool) — Определяет, будет ли блок-паттерн отображаться в панели вставки редактора.

  false — шаблон не появится в списке доступных для вставки через интерфейс редактора. Это полезно, когда вы хотите использовать блок-паттерн только программно или автоматически (например, при создании записей или шаблонов), но не хотите, чтобы пользователь вставлял его вручную.
  true — (по умолчанию) шаблон будет доступен для вставки через интерфейс редактора.

• source (string) — Источник шаблона (plugin или theme).

Список всех параметров смотрите в WP_Block_Patterns_Registry::register().

Примеры

add_action( 'init', 'my_plugin_register_block_patterns' );

function my_plugin_register_block_patterns() {
	register_block_pattern(
		'my-plugin/two-buttons',
		array(
			'title'       => __( 'Две кнопки', 'my-plugin' ),
			'description' => _x( 'Две горизонтальные кнопки: левая залитая, правая с обводкой.', 'Block pattern description', 'my-plugin' ),
			'categories'  => array( 'buttons' ),
			'content'     => '<!-- wp:buttons {"align":"center"} -->
<div class="wp-block-buttons aligncenter">
	<!-- wp:button {"backgroundColor":"primary","borderRadius":0} -->
	<div class="wp-block-button"><a class="wp-block-button__link has-background has-primary-background-color no-border-radius">Кнопка 1</a></div>
	<!-- /wp:button -->

	<!-- wp:button {"textColor":"primary","borderRadius":0,"className":"is-style-outline"} -->
	<div class="wp-block-button is-style-outline"><a class="wp-block-button__link has-text-color has-primary-color no-border-radius">Кнопка 2</a></div>
	<!-- /wp:button -->
</div>
<!-- /wp:buttons -->',
		)
	);
}

add_action( 'init', 'my_plugin_register_external_pattern' );
function my_plugin_register_external_pattern() {
	ob_start();
	include plugin_dir_path( __FILE__ ) . 'patterns/hero-section.php';
	$pattern_content = ob_get_clean();

	register_block_pattern(
		'my-plugin/hero-section',
		array(
			'title'      => __( 'Hero секция', 'my-plugin' ),
			'categories' => array( 'hero' ),
			'content'    => $pattern_content,
		)
	);
}

Добавить свой пример