acf_register_block_type() │ ACF 5.8.0

Регистрирует кастомный блок для редактора блоков Gutenberg через PHP (ACF).

Позволяет добавить блок c собственными ACF полями и шаблоном рендера прямо из PHP.

После регистрации блок можно указывать в ACF параметре location ("Block") — это позволяет привязать к нему поля:

'location' => [
	[
		[
			'param'    => 'block',
			'operator' => '==',
			'value'    => 'acf/hero-block',
		],
	],
],

Вывод блока осуществляется через PHP-шаблон или callback с использованием get_field() и the_field().

Офф. дока: https://www.advancedcustomfields.com/resources/acf_register_block_type/

Регистрация должна прохоидть на хуке acf/init.

С версии ACF 6.0 рекомендуется регистрировать блоки с помощью нового синтаксиса block.json + register_block_type().

Функциональность, описанная в этой документации, может не работать с современными версиями WordPress.

Заметки

  • Для динамического рендера можно использовать render_callback, особенно если нужен PHP-код с логикой.

  • Можно включить превью блоков, смотрите ниже.

  • Можно использовать вложенные блоки (innerBlocks), смотрите ниже
Хуки из функции

Возвращает

(Массив|false). Массив проверенных настроек зарегистрированного блока.

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

acf_register_block_type( $block );
$block(массив) (обязательный)

Аргументы регистрации блока (соответствуют параметрам registerBlockType() в JS).

  • name (String): уникальный идентификатор блока, например testimonial.
  • title (String): отображаемое название в редакторе.
  • description (String): краткое описание.
  • category (String): категория (common, formatting, layout, widgets, embed).
  • icon (String|Array): Dashicon или SVG, можно задать цвет фона/переднего плана.
  • keywords (Array): дополнительные поисковые слова.
  • post_types (Array): ограничение по типам записей.
  • mode (String): auto, preview, edit — поведение интерфейса.
  • align, align_text, align_content (String): дефолтное выравнивание.
  • render_template (String): путь к PHP-шаблону для рендера.
  • render_callback (Callable): функция/метод для рендера блока.
  • enqueue_style, enqueue_script (String): пути к файлам стилей/скриптов.
  • enqueue_assets (Callable): функция для динамической регистрации ресурсов.
  • supports (Array): опции поддержки (align, mode, multiple, full_height, jsx и др.).
  • example (Array): шаблон для превью в панели вставки block-inserter.

Inner Blocks

<InnerBlocks /> — это возможность вложенного контента (блоки внутри блоков).

Используйте компонент <InnerBlocks /> в шаблоне блока. Он создаёт область для вставки вложенных блоков в редакторе.

Важно:

  • Допускается только один <InnerBlocks /> на блок.
  • Блок должен быть зарегистрирован с поддержкой JSX - 'jsx' => true, иначе компонент не сработает.

Параметры <InnerBlocks />

allowedBlocks(array)

Ограничивает допустимые блоки:

<?php
$allowed_blocks = [ 'core/image', 'core/paragraph' ];
?>
<InnerBlocks allowedBlocks="<?= esc_attr( wp_json_encode( $allowed_blocks ) ) ?>" />
template(array)

Создают структуру вложенных блоков:

<?php
$template = [
	[ 'core/paragraph', [ 'placeholder' => 'Add a root-level paragraph' ] ],
	[ 'core/columns', [], [
		[ 'core/column', [], [
			[ 'core/image', [] ],
		] ],
		[ 'core/column', [], [
			[ 'core/paragraph', [ 'placeholder' => 'Add a inner paragraph' ] ],
		] ],
	] ],
];
?>

<InnerBlocks template="<?= esc_attr( wp_json_encode( $template ) ) ?>" templateLock="all" />
templateLock(string)

Блокирует содержимое шаблона. Доступные настройки:

  • all — нельзя изменять структуру.
  • insert — запрещает удаление, но позволяет добавление новых блоков.

См. компонент InnerBlocks для получения дополнительной информации.

Пример регистрации блока

add_action( 'acf/init', 'my_acf_init_blocks' );
function my_acf_init_blocks() {
	acf_register_block_type( [
		'name'            => 'restricted',
		'title'           => 'Restricted',
		'description'     => 'A restricted content block.',
		'category'        => 'formatting',
		'mode'            => 'preview',
		'render_template' => 'template-parts/blocks/restricted/restricted.php',
		'supports'        => [
			'align' => true,
			'mode'  => false,
			'jsx'   => true,
		],
	] );
}

Пример шаблона restricted.php:

<?php
$classes = trim(
	( $block['className'] ?? '' ) .
	( ! empty( $block['align'] ) ? ' align' . $block['align'] : '' )
);

$start_date = get_field( 'start_date' );
$end_date   = get_field( 'end_date' );

$start_ts = $start_date ? strtotime( $start_date ) : false;
$end_ts   = $end_date ? strtotime( $end_date ) : false;

$notification = 'Content unrestricted.';
if ( $start_date || $end_date ) {
	$notification  = 'Content visible';
	$notification .= $start_date ? " from $start_date" : '';
	$notification .= $end_date ? " until $end_date" : '';
	$notification .= '.';
}
?>

<div class="restricted-block <?= esc_attr( $classes ) ?>">
	<span class="restricted-block-notification"><?= esc_html( $notification ) ?></span>
	<InnerBlocks />
</div>

Предпросмотр блоков

Скриншот панели вставки, показывающий предварительный просмотр блока.

Для отображения превью в панели вставки блоков добавьте параметр example при регистрации блока:

acf_register_block_type( [
	'name'        => 'testimonial',
	'title'       => __( 'Testimonial' ),
	'description' => __( 'A custom testimonial block.' ),
	'example'     => [
		'attributes' => [
			'mode' => 'preview',
			'data' => [
				'testimonial' => 'Blocks are...',
				'author'      => 'Jane Smith',
				'role'        => 'Person',
				'is_preview'  => true,
			],
		],
	],
] );

Все значения, указанные в массиве data, будут доступны в шаблоне/обработчике блока через $block['data'] или get_field().

  • data — содержит значения, доступные через $block['data'] или get_field().
  • is_preview — не связано с блоком и может использоваться для отображения альтернативной разметки.
  • preview — режим визуального представления блока, но можно использовать и edit — тогда будут отображаться связанные с блоком поля.

Примеры

0

#1 Регистрация блока с шаблоном 

add_action('acf/init', 'my_acf_blocks_init');
function my_acf_blocks_init() {

	// Register a testimonial block.
	acf_register_block_type(array(
		'name'              => 'testimonial',
		'title'             => __('Testimonial'),
		'description'       => __('A custom testimonial block.'),
		'render_template'   => 'template-parts/blocks/testimonial/testimonial.php',
		'category'          => 'formatting',
	));

}

testimonials.php

<?php

/**
 * Testimonial Block Template.
 *
 * @param   array $block The block settings and attributes.
 * @param   string $content The block inner HTML (empty).
 * @param   bool $is_preview True during AJAX preview.
 * @param   (int|string) $post_id The post ID this block is saved to.
 */

// Create id attribute allowing for custom "anchor" value.
$id = 'testimonial-' . $block['id'];
if( !empty($block['anchor']) ) {
	$id = $block['anchor'];
}

// Create class attribute allowing for custom "className" and "align" values.
$className = 'testimonial';
if( !empty($block['className']) ) {
	$className .= ' ' . $block['className'];
}
if( !empty($block['align']) ) {
	$className .= ' align' . $block['align'];
}

// Load values and handle defaults.
$text = get_field('testimonial') ?: 'Your testimonial here...';
$author = get_field('author') ?: 'Author name';
$role = get_field('role') ?: 'Author role';
$image = get_field('image') ?: 295;
$background_color = get_field('background_color');
$text_color = get_field('text_color');

?>
<div id="<?php echo esc_attr($id); ?>" class="<?php echo esc_attr($className); ?>">
	<blockquote class="testimonial-blockquote">
		<span class="testimonial-text"><?php echo $text; ?></span>
		<span class="testimonial-author"><?php echo $author; ?></span>
		<span class="testimonial-role"><?php echo $role; ?></span>
	</blockquote>
	<div class="testimonial-image">
		<?php echo wp_get_attachment_image( $image, 'full' ); ?>
	</div>
	<style type="text/css">
		#<?php echo $id; ?> {
			background: <?php echo $background_color; ?>;
			color: <?php echo $text_color; ?>;
		}
	</style>
</div>
0

#2 Регистрация блока с callback

Этот пример показывает как зарегистрированть блок с использованием параметра render_callback.

<?php

add_action('acf/init', 'my_register_blocks');
function my_register_blocks() {

	acf_register_block_type(array(
		'name'              => 'testimonial',
		'title'             => __('Testimonial'),
		'description'       => __('A custom testimonial block.'),
		'render_callback'   => 'my_acf_block_render_callback',
		'category'          => 'formatting',
	));

}

/**
 * Testimonial Block Callback Function.
 *
 * @param   array $block The block settings and attributes.
 * @param   string $content The block inner HTML (empty).
 * @param   bool $is_preview True during AJAX preview.
 * @param   (int|string) $post_id The post ID this block is saved to.
 */
function my_acf_block_render_callback( $block, $content = '', $is_preview = false, $post_id = 0, $wp_block = false, $context = false ) {

	// Create id attribute allowing for custom "anchor" value.
	$id = 'testimonial-' . $block['id'];
	if( !empty($block['anchor']) ) {
		$id = $block['anchor'];
	}

	// Create class attribute allowing for custom "className" and "align" values.
	$className = 'testimonial';
	if( !empty($block['className']) ) {
		$className .= ' ' . $block['className'];
	}
	if( !empty($block['align']) ) {
		$className .= ' align' . $block['align'];
	}

	// Load values and handle defaults.
	$text = get_field('testimonial') ?: 'Your testimonial here...';
	$author = get_field('author') ?: 'Author name';
	$role = get_field('role') ?: 'Author role';
	$image = get_field('image') ?: 295;
	$background_color = get_field('background_color');
	$text_color = get_field('text_color');

	?>
	<div id="<?php echo esc_attr($id); ?>" class="<?php echo esc_attr($className); ?>">
		<blockquote class="testimonial-blockquote">
			<span class="testimonial-text"><?php echo $text; ?></span>
			<span class="testimonial-author"><?php echo $author; ?></span>
			<span class="testimonial-role"><?php echo $role; ?></span>
		</blockquote>
		<div class="testimonial-image">
			<?php echo wp_get_attachment_image( $image, 'full' ); ?>
		</div>
		<style type="text/css">
			#<?php echo $id; ?> {
				background: <?php echo $background_color; ?>;
				color: <?php echo $text_color; ?>;
			}
		</style>
	</div>
	<?php
}

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

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

Код acf_register_block_type() ACF 6.4.2

acf/pro/blocks.php 
function acf_register_block_type( $block ) {
	// Validate block type settings.
	$block = acf_validate_block_type( $block );

	/**
	 * Filters the arguments for registering a block type.
	 *
	 * @since   5.8.9
	 *
	 * @param   array $block The array of arguments for registering a block type.
	 */
	$block = apply_filters( 'acf/register_block_type_args', $block );

	// Require name.
	if ( ! $block['name'] ) {
		$message = __( 'Block type name is required.', 'acf' );
		_doing_it_wrong( __FUNCTION__, $message, '5.8.0' ); //phpcs:ignore -- escape not required.
		return false;
	}

	// Bail early if already exists.
	if ( acf_has_block_type( $block['name'] ) ) {
		/* translators: The name of the block type */
		$message = sprintf( __( 'Block type "%s" is already registered.', 'acf' ), $block['name'] );
		_doing_it_wrong( __FUNCTION__, $message, '5.8.0' ); //phpcs:ignore -- escape not required.
		return false;
	}

	// Set ACF required attributes.
	$block['attributes'] = acf_get_block_type_default_attributes( $block );
	if ( ! isset( $block['api_version'] ) ) {
		$block['api_version'] = 2;
	}
	if ( ! isset( $block['acf_block_version'] ) ) {
		$block['acf_block_version'] = 1;
	}

	// Add to storage.
	acf_get_store( 'block-types' )->set( $block['name'], $block );

	// Overwrite callback for WordPress registration.
	$block['render_callback'] = 'acf_render_block_callback';

	// Register block type in WP.
	if ( function_exists( 'register_block_type' ) ) {
		register_block_type(
			$block['name'],
			$block
		);
	}

	// Register action.
	add_action( 'enqueue_block_editor_assets', 'acf_enqueue_block_assets' );

	// Return block.
	return $block;
}

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

ACF