Обзор
Начиная с ACF 6.0, мы рекомендуем регистрировать блоки с помощью нового синтаксиса block.json вместо устаревшей
acf_register_block_type(), описанной здесь.Функциональность, описанная в этой документации, может не работать в современных версиях WordPress.
Описание
Регистрирует пользовательский тип блока в редакторе Gutenberg.
Блоки — это базовый элемент редактора Gutenberg. WordPress предоставляет множество стандартных типов блоков, таких как абзац, заголовок и изображение. Функцию acf_register_block_type() можно использовать для добавления новых типов блоков через PHP.
После регистрации ваш блок появится в правилах расположения «Block» при редактировании группы полей. Это позволяет сопоставлять поля с вашим блоком и задавать его содержимое.
Чтобы отрисовать блок, создайте PHP-шаблон (или callback-функцию) для вывода HTML блока с использованием функций PHP, таких как get_field() и the_field().
Примечание: регистрировать тип блока следует внутри действия acf/init. Это не обязательно, но такой подход гарантирует, что ACF будет полностью инициализирован.
Типы блоков могут поддерживать любое количество встроенных возможностей ядра, таких как name, icon, description, category и многое другое. См. аргумент $settings для полного списка поддерживаемых возможностей.
Кроме того, можно использовать все свойства из API поддержки блоков WordPress.
Параметры
acf_register_block_type( $settings );
$settings
(array) (Required) Массив аргументов для регистрации типа блока. Также можно использовать любой аргумент из JavaScript-функции registerBlockType().
name (String) Уникальное имя, которое идентифицирует блок (без namespace). Например, ‘testimonial’. Примечание: имя блока может содержать только строчные буквенно-цифровые символы и дефисы и должно начинаться с буквы.
'name' => 'testimonial',title
(String) Отображаемое название вашего блока. Например, ‘Отзыв’.'title' => __('Отзыв'),description
(String) (Optional) Краткое описание вашего блока.'description' => __('Мой блок отзыва.'),category
(String) Блоки группируются по категориям, чтобы пользователям было проще просматривать и находить их. Встроенные категории ядра: [ common | formatting | layout | widgets | embed ]. Плагины и темы также могут регистрировать пользовательские категории блоков.'category' => 'embed',icon
(String|Array) (Optional) Можно указать свойство icon, чтобы блок было проще идентифицировать. Это могут быть WordPress Dashicons или собственный элемент svg.// Указание dashicon для блока 'icon' => 'book-alt', // Указание пользовательского HTML svg для блока 'icon' => '<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path fill="none" d="M0 0h24v24H0V0z" /><path d="M19 13H5v-2h14v2z" /></svg>', // Указание цветов 'icon' => array( // Указание цвета фона, который будет отображаться вместе со значком, например в инсертере. 'background' => '#7e70af', // Указание цвета значка (необязательно: если не задан, будет автоматически подобран читаемый цвет) 'foreground' => '#fff', // Указание dashicon для блока 'src' => 'book-alt', ),keywords
(Array) (Optional) Массив поисковых запросов, который помогает пользователю находить блок при поиске.'keywords' => array('quote', 'mention', 'cite'),post_types
(Array) (Optional) Массив типов записей, для которых следует ограничить этот тип блока.'post_types' => array('post', 'page'),mode
(String) (Optional) Режим отображения вашего блока. Доступные значения: «auto», «preview» и «edit». По умолчанию используется «preview». auto: по умолчанию отображается предпросмотр, но при выборе блока он переключается на форму редактирования. preview: всегда отображается предпросмотр. Форма редактирования появляется в боковой панели при выборе блока. edit: всегда отображается форма редактирования.Примечание. В режимах «preview» или «edit» в панели инструментов блока появится значок для переключения между режимами.
'mode' => 'auto',align
(String) (Optional) Выравнивание блока по умолчанию. Доступные значения: «left», «center», «right», «wide» и «full». По умолчанию — пустая строка.'align' => 'full',align_text
(String) (Optional) Выравнивание текста блока по умолчанию (см. настройки supports для подробностей). Доступные значения: «left», «center» и «right». По умолчанию используется выравнивание текста текущего языка.'align_text' => 'center',align_content
(String) (Optional) Выравнивание содержимого блока по умолчанию (см. настройки supports для подробностей). Доступные значения: «top», «center» и «bottom». При использовании типа управления «Matrix» доступны дополнительные настройки, позволяющие указать все 9 позиций от «top left» до «bottom right». По умолчанию — «top».'align_content' => 'center',render_template
(String) Путь к файлу шаблона, который используется для отрисовки HTML блока. Это может быть как относительный путь к файлу внутри активной темы, так и полный путь к любому файлу.// Указание относительного пути внутри активной темы 'render_template' => 'template-parts/blocks/testimonial/testimonial.php', // Указание абсолютного пути 'render_template' => plugin_dir_path( __FILE__ ) . 'template-parts/blocks/testimonial/testimonial.php',render_callback
(Callable) (Optional) Вместо render_template можно указать имя callback-функции, которая будет выводить HTML блока.// Указание функции 'render_callback' => 'my_acf_block_render_callback', // Указание метода класса 'render_callback' => array($this, 'block_render_callback'),enqueue_style
(String) (Optional) URL к .css-файлу, который будет подключаться каждый раз, когда отображается ваш блок (на фронтенде и в админке). Начиная с WordPress 5.8, скрипты и стили могут некорректно загружаться в шаблонах блоков, стилях и iframe-превью. Чтобы решить эту проблему, вам нужно использовать новый форматblock.jsonс ключамиscriptиstyle.'enqueue_style' => get_template_directory_uri() . '/template-parts/blocks/testimonial/testimonial.css',enqueue_script
(String) (Optional) URL к .js-файлу, который будет подключаться каждый раз, когда отображается ваш блок (на фронтенде и в админке). Начиная с WordPress 5.8, скрипты и стили могут некорректно загружаться в шаблонах блоков, стилях и iframe-превью. Чтобы решить эту проблему, вам нужно использовать новый форматblock.jsonс ключамиscriptиstyle.'enqueue_script' => get_template_directory_uri() . '/template-parts/blocks/testimonial/testimonial.js',enqueue_assets
(Callable) (Optional) Callback-функция, которая запускается каждый раз, когда отображается ваш блок (на фронтенде и в админке), и подключает скрипты и/или стили.// Указание имени функции 'enqueue_assets' => 'my_acf_block_enqueue_assets', // Указание метода класса 'enqueue_assets' => array($this, 'block_enqueue_assets'), // Указание анонимной функции 'enqueue_assets' => function(){ wp_enqueue_style( 'block-testimonial', get_template_directory_uri() . '/template-parts/blocks/testimonial/testimonial.css' ); wp_enqueue_script( 'block-testimonial', get_template_directory_uri() . '/template-parts/blocks/testimonial/testimonial.js', array('jquery'), '', true ); },supports
(Array) (Optional) Массив возможностей, которые поддерживаются. Можно использовать все свойства из JavaScript-документации block supports. Поддерживаются следующие опции:'supports' => array( /* ... */ ),- align
Этот параметр добавляет кнопку на панели инструментов для управления выравниванием блока. По умолчанию —true. Установитеfalse, чтобы скрыть кнопку выравнивания. Можно задать массив конкретных значений выравнивания, чтобы настроить панель инструментов.// Отключение панели выравнивания 'align' => false, // Настройка панели выравнивания 'align' => array( 'left', 'right', 'full' ),
- align_text
Этот параметр добавляет кнопку на панели инструментов для управления выравниванием текста блока. По умолчанию —false. Установитеtrue, чтобы показать кнопку выравнивания.
Текущее выбранное значение выравнивания будет доступно в render callback/template через$block['align_text'].
// Показать кнопку выравнивания текста. 'align_text' => true,- align_content
Этот параметр добавляет кнопку на панели инструментов для управления выравниванием внутреннего содержимого блока. По умолчанию —false. Установитеtrue, чтобы показать кнопку выравнивания, или задайте'matrix', чтобы включить полную матрицу выравнивания в панели инструментов.
Текущее выбранное значение выравнивания будет доступно в render callback/template через$block['align_content'].
// Показать панель выравнивания содержимого. 'align_content' => true, // Показать полную матрицу выравнивания в панели инструментов. 'align_content' => 'matrix',- full_height
Этот параметр включает кнопку полной высоты на панели инструментов блока и добавляет свойство$block[‘full_height’]внутрь render template/callback.$block[‘full_height’]будет true только если для блока в редакторе включена кнопка полной высоты. По умолчанию —false.
// Включить full_height 'full_height' => true,- mode
Этот параметр позволяет пользователю переключаться между режимами edit и preview с помощью кнопки. По умолчанию —true.
// Отключить переключатель preview/edit 'mode' => false,- multiple
Этот параметр позволяет добавлять блок несколько раз. По умолчанию —true.
'multiple' => false,- align
example
(Array) (Optional) Массив структурированных данных, который используется для создания предпросмотра внутри инсертора блоков. Все значения, введённые в массив атрибутов «data», станут доступны в шаблоне/ callback-функции рендера блока через$block['data']илиget_field().'example' => array( 'attributes' => array( 'mode' => 'preview', 'data' => array( 'testimonial' => "Ваш отзыв здесь", 'author' => "Джон Смит" ) ) )acf_block_version
(Integer) (Optional) Это свойство можно использовать для переключения между различными версиями блоков ACF (1, 2 или 3). По умолчанию —2.// Переключение на ACF Blocks v3. 'acf_block_version' => 3,
Возвращаемое значение
(array) Проверенные и зарегистрированные настройки блока.
Журнал изменений
- Добавлено в версии 5.8.0
- Добавлены настройки «align_text» в версии 5.9.0.
- Добавлены настройки «align_content» в версии 5.9.0.
Примеры
Регистрация блока с шаблоном
Этот пример показывает, как зарегистрировать блок с использованием настройки render_template.
functions.php
add_action('acf/init', 'my_acf_blocks_init');
function my_acf_blocks_init() {
// Проверяем, существует ли функция.
if( function_exists('acf_register_block_type') ) {
// Регистрируем блок отзыва.
acf_register_block_type(array(
'name' => 'testimonial',
'title' => __('Отзыв'),
'description' => __('Пользовательский блок отзыва.'),
'render_template' => 'template-parts/blocks/testimonial/testimonial.php',
'category' => 'formatting',
));
}
}
template-parts/blocks/testimonial/testimonial.php
<?php
/**
* Шаблон блока отзыва.
*
* @param array $block Параметры и атрибуты блока.
* @param string $content Внутренний HTML блока (пусто).
* @param bool $is_preview Истина во время AJAX-превью.
* @param (int|string) $post_id ID записи, в которой сохранён этот блок.
*/
// Создаём атрибут id, позволяющий использовать пользовательское значение "anchor".
$id = 'testimonial-' . $block['id'];
if( !empty($block['anchor']) ) {
$id = $block['anchor'];
}
// Создаём атрибут class, позволяющий использовать пользовательские значения "className" и "align".
$className = 'testimonial';
if( !empty($block['className']) ) {
$className .= ' ' . $block['className'];
}
if( !empty($block['align']) ) {
$className .= ' align' . $block['align'];
}
// Загружаем значения и обрабатываем значения по умолчанию.
$text = get_field('testimonial') ?: 'Ваш отзыв здесь...';
$author = get_field('author') ?: 'Имя автора';
$role = get_field('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>
Регистрация блока с callback
Этот пример показывает, как зарегистрировать блок с использованием настройки render_callback.
functions.php
<?php
add_action('acf/init', 'my_register_blocks');
function my_register_blocks() {
// Проверяем, существует ли функция.
if( function_exists('acf_register_block_type') ) {
// Регистрируем блок отзыва.
acf_register_block_type(array(
'name' => 'testimonial',
'title' => __('Отзыв'),
'description' => __('Пользовательский блок отзыва.'),
'render_callback' => 'my_acf_block_render_callback',
'category' => 'formatting',
));
}
}
/**
* Callback-функция блока отзыва.
*
* @param array $block Параметры и атрибуты блока.
* @param string $content Внутренний HTML блока (пусто).
* @param bool $is_preview Истина во время AJAX-превью.
* @param (int|string) $post_id ID записи, в которой сохранён этот блок.
*/
function my_acf_block_render_callback( $block, $content = '', $is_preview = false, $post_id = 0, $wp_block = false, $context = false ) {
// Создаём атрибут id, позволяющий использовать пользовательское значение "anchor".
$id = 'testimonial-' . $block['id'];
if( !empty($block['anchor']) ) {
$id = $block['anchor'];
}
// Создаём атрибут class, позволяющий использовать пользовательские значения "className" и "align".
$className = 'testimonial';
if( !empty($block['className']) ) {
$className .= ' ' . $block['className'];
}
if( !empty($block['align']) ) {
$className .= ' align' . $block['align'];
}
// Загружаем значения и обрабатываем значения по умолчанию.
$text = get_field('testimonial') ?: 'Ваш отзыв здесь...';
$author = get_field('author') ?: 'Имя автора';
$role = get_field('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
}
Добавление стилей блока 🎨
Начиная с WordPress 5.8, скрипты и стили могут некорректно загружаться в шаблонах блоков, стилях и iframe-превью. Чтобы решить эту проблему, вам нужно использовать новый block.json с ключами
scriptиstyle.
Чтобы ваш блок корректно оформлялся и в редакторе, и на фронтенде, мы рекомендуем использовать либо настройки enqueue_style, либо enqueue_assets, например так:
functions.php
acf_register_block_type(array(
'name' => 'testimonial',
'title' => __('Отзыв'),
'description' => __('Пользовательский блок отзыва.'),
'render_template' => get_template_directory() . '/template-parts/blocks/testimonial/testimonial.php',
'enqueue_style' => get_template_directory_uri() . '/template-parts/blocks/testimonial/testimonial.css',
));
testimonial.php
<blockquote class="testimonial">
...
</blockquote>
testimonial.css
.testimonial {
background: #00e4ba;
color: #fff;
}
Примечание: Если создание отдельных таблиц стилей — не ваш любимый способ работы, обратите внимание на действия enqueue_block_assets и enqueue_block_editor_assets, которые WordPress предоставляет для подключения ваших стилей.
Добавление скриптов блока ⚡️
Начиная с WordPress 5.8, скрипты и стили могут некорректно загружаться в шаблонах блоков, стилях и iframe-превью. Чтобы решить эту проблему, вам нужно использовать новый block.json с ключами
scriptиstyle.
Как и в случае со стилями, мы рекомендуем использовать либо настройки enqueue_script, либо enqueue_assets, чтобы корректно подключать JavaScript для вашего блока.
Чтобы JavaScript работал так, как задумано, и в редакторе, и на фронтенде, важно понимать жизненный цикл блока при редактировании записи.
В зависимости от того, показывается ли предпросмотр блока и были ли внесены изменения, ваш блок может быть отрисован несколько раз за одну загрузку страницы. В этом случае термин «отрисован» означает, что HTML блока был обновлён/заменён через AJAX-вызов к вашему PHP-шаблону или callback-функции.
Каждый раз при отрисовке блока предыдущий HTML удаляется, а отображается новый HTML. В результате любые изменения JavaScript в предыдущих DOM-элементах тоже будут потеряны.
Чтобы решить эту проблему, просто подпишитесь на наше JS-действие “render_block_preview/type={$type}” и применяйте свою JavaScript-логику так, как будто блок был только что нарисован.
В этом примере показано, как подключить скрипт с поддержкой как фронтенд-, так и бэкенд-состояний блока.
functions.php
acf_register_block_type(array(
'name' => 'testimonial',
'title' => __('Отзыв'),
'description' => __('Пользовательский блок отзыва.'),
'render_template' => get_template_directory() . '/template-parts/blocks/testimonial/testimonial.php',
'enqueue_script' => get_template_directory_uri() . '/template-parts/blocks/testimonial/testimonial.js',
));
testimonial.php
<blockquote class="testimonial">
<img src="..." />
...
</blockquote>
testimonial.js
(function($){
/**
* initializeBlock
*
* Добавляет пользовательский JavaScript к HTML блока.
*
* @date 15/4/19
* @since 1.0.0
*
* @param object $block Элемент jQuery блока.
* @param object attributes Атрибуты блока (доступны только при редактировании).
* @return void
*/
var initializeBlock = function( $block ) {
$block.find('img').doSomething();
}
// Инициализируем каждый блок при загрузке страницы (фронтенд).
$(document).ready(function(){
$('.testimonial').each(function(){
initializeBlock( $(this) );
});
});
// Инициализируем динамический предпросмотр блока (редактор).
if( window.acf ) {
window.acf.addAction( 'render_block_preview/type=testimonial', initializeBlock );
}
})(jQuery);
Добавление предпросмотров блоков 🌄
Предпросмотры блоков — это элегантное решение для идентификации и различения различных типов блоков, отображаемых в панели инсертора.
Чтобы добавить поддержку предпросмотров блоков, используйте настройку «example», чтобы определить массив атрибутов, который WordPress будет использовать для построения предпросмотра, как показано в следующем примере.
functions.php
acf_register_block_type(array(
'name' => 'testimonial',
'title' => __('Отзыв'),
'description' => __('Пользовательский блок отзыва.'),
'example' => array(
'attributes' => array(
'mode' => 'preview',
'data' => array(
'testimonial' => "Блоки...",
'author' => "Джейн Смит",
'role' => "Автор",
'is_preview' => true
)
)
)
));
Все значения, определённые в массиве атрибутов «data», станут доступны в шаблоне/ callback-функции рендера блока через $block['data'] или get_field().
В примере выше определены три значения, соответствующие именам трёх существующих пользовательских полей (‘testimonial’, ‘author’ & ‘role’). Дополнительно определено значение, не относящееся к пользовательским полям (‘is_preview’), которое можно использовать внутри renderer для вывода альтернативной разметки.
👨💻 Поскольку предпросмотры предназначены для передачи визуального дизайна, мы рекомендуем использовать режим «preview», однако можно также установить «edit», чтобы отображались пользовательские поля, связанные с этим блоком.
Добавление внутренних блоков 👩👧👦
Термин «Inner Blocks» означает возможность включать вложенный контент — блоки внутри блоков. Это короткое видео показывает, как внутренние блоки можно использовать для создания блока с ограничением по дате, используя только базовый PHP.
Чтобы добавить поддержку внутренних блоков, используйте компонент <InnerBlocks /> внутри вашего render template/callback, чтобы определить редактируемую область. Этот специальный элемент будет отображаться как нативная «область вставки блоков» при редактировании контента и как сохранённый «контент внутренних блоков» при просмотре контента.
Обратите внимание, что на один блок можно использовать только один компонент <InnerBlocks />.
Чтобы компонент <InnerBlocks /> работал внутри редактора блоков на React, HTML вашего блока сначала должен быть распознан как JSX. Это легко сделать, добавив поддержку свойства jsx.
Следующий пример показывает, как создать упомянутый ранее блок контента «Restricted».
functions.php
add_action('acf/init', 'my_acf_init_blocks');
function my_acf_init_blocks() {
// Проверяем, существует ли функция.
if( function_exists('acf_register_block_type') ) {
// Регистрируем ограниченный блок.
acf_register_block_type(array(
'name' => 'restricted',
'title' => 'Restricted',
'description' => 'Блок контента с ограничением.',
'category' => 'formatting',
'mode' => 'preview',
'supports' => array(
'align' => true,
'mode' => false,
'jsx' => true
),
'render_template' => 'template-parts/blocks/restricted/restricted.php',
));
}
}
template-parts/blocks/restricted/restricted.php
<?php
/**
* Шаблон ограниченного блока.
*
* @param array $block Параметры и атрибуты блока.
* @param string $content Внутренний HTML блока (пусто).
* @param bool $is_preview Истина во время AJAX-превью.
* @param (int|string) $post_id ID записи, в которой сохранён этот блок.
*/
// Создаём атрибут class, позволяющий использовать пользовательские значения "className" и "align".
$classes = '';
if( !empty($block['className']) ) {
$classes .= sprintf( ' %s', $block['className'] );
}
if( !empty($block['align']) ) {
$classes .= sprintf( ' align%s', $block['align'] );
}
// Загружаем значения пользовательских полей.
$start_date = get_field('start_date');
$end_date = get_field('end_date');
// Ограничиваем вывод блока (только фронтенд).
if( !$is_preview ) {
$now = time();
if( $start_date && strtotime($start_date) > $now ) {
echo sprintf( '<p>Контент ограничен до %s. Пожалуйста, вернитесь позже.</p>', $start_date );
return;
}
if( $end_date && strtotime($end_date) < $now ) {
echo sprintf( '<p>Срок действия контента истёк %s.</p>', $end_date );
return;
}
}
// Определяем сообщение уведомления, которое показывается при редактировании.
if( $start_date && $end_date ) {
$notification = sprintf( 'Контент виден с %s по %s.', $start_date, $end_date );
} elseif( $start_date ) {
$notification = sprintf( 'Контент виден с %s.', $start_date );
} elseif( $end_date ) {
$notification = sprintf( 'Контент виден до %s.', $end_date );
} else {
$notification = 'Контент не ограничен.';
}
?>
<div class="restricted-block <?php echo esc_attr($classes); ?>">
<span class="restricted-block-notification"><?php echo esc_html( $notification ); ?></span>
<InnerBlocks />
</div>
Компонент <InnerBlocks /> также можно настраивать с помощью следующих атрибутов, как описано в Руководстве по компоненту InnerBlocks.
allowedBlocks
(Array) Массив имён блоков, который ограничивает типы контента, доступные для вставки.$allowed_blocks = array( 'core/image', 'core/paragraph' ); echo '<InnerBlocks allowedBlocks="' . esc_attr( wp_json_encode( $allowed_blocks ) ) . '" />';template
(Array) Структурированный массив содержимого блока, как описано в руководстве по шаблонам блоков CPT. Дополнительный атрибут с именем templateLock можно использовать вместе с ним, чтобы заблокировать содержимое шаблона.$template = array( array( 'core/paragraph', array( 'placeholder' => 'Добавьте абзац верхнего уровня', ) ), array( 'core/columns', array(), array( array( 'core/column', array(), array( array( 'core/image', array() ), ) ), array( 'core/column', array(), array( array( 'core/paragraph', array( 'placeholder' => 'Добавьте вложенный абзац' ) ), ) ), ) ) ); echo '<InnerBlocks template="' . esc_attr( wp_json_encode( $template ) ) . '" templateLock="all" />';templateLock
(String) Блокирует содержимое шаблона. Доступные значения: «all» или «insert». См. компонент InnerBlocks для получения дополнительной информации.
Обновлено: 02.06.2026