register_block_type() │ WP 5.0.0

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

register_block_type( 'alias/example', [] );

registerBlockType( 'alias/example', {} )

Хуков нет.

Возвращает

WP_Block_Type|false. Объект зарегистрированного блока в случае успеха или false в случае ошибки.

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

register_block_type( $block_type, $args );

$block_type(строка/WP_Block_Type) (обязательный)

Одно из:

• Имя блока с namespace.
• Путь к block.json.
• Путь к папке с block.json.
• Готовый объект WP_Block_Type. В этом случае, параметр $args игнорируется.

Пример указания пути:

register_block_type( __DIR__ . '/block.json' );

Или можно указать путь к папке где лежит файл block.json:

register_block_type( __DIR__ . '/my-block' );

$args(массив)

Массив аргументов блока. Принимает любое публичное свойство класса WP_Block_Type.

Возможные параметры смотрите в WP_Block_Type::__construct().

• api_version(int|string)
  Версия Block API. Обычно 2 или 3. Влияет на поведение блока в редакторе, подключение стилей, iframe editor и другие возможности API.

• title(string)
  Человеческое название блока. Показывается в inserter, списке блоков и интерфейсе редактора.

• category(string|null)
  Категория блока в inserter. Например: text, media, design, widgets, theme, embed.

• parent(string[]|null)
  Список блоков, внутри которых этот блок может быть вставлен напрямую. Например, core/column можно ограничить только родителем core/columns.

• ancestor(string[]|null)
  Список блоков-предков, внутри которых блок доступен на любой глубине вложенности. Отличается от parent тем, что предок не обязан быть прямым родителем.

• allowed_blocks(string[]|null)
  Список блоков, которые можно вставлять внутрь этого блока. Ограничивает дочерние блоки.

• icon(string|null)
  Иконка блока. Можно указать название dashicon без префикса dashicons-, например admin-links.

• description(string)
  Описание блока. Используется в интерфейсе редактора и помогает понять назначение блока.

• keywords(string[])
  Дополнительные слова для поиска блока в inserter.

• textdomain(string|null)
  Текстовый домен для переводов строк блока.

• styles(array[])
  Альтернативные стили блока. Каждый стиль обычно содержит name, label и опционально isDefault.

• variations(array[]|null)
  Вариации блока. Позволяют показывать один и тот же блок как несколько готовых вариантов с разными атрибутами, inner blocks или областью применения.

• variation_callback(callable|null)
  Callback, который возвращает массив вариаций. Удобно, когда вариации нужно собрать динамически.

• selectors(array)
  Пользовательские CSS-селекторы для генерации стилей из theme.json. Позволяет указать, к каким внутренним элементам блока применять стили.

• supports(array|null)
  Поддерживаемые возможности блока. Например: align, anchor, color, spacing, typography, layout, dimensions.

  • autoRegister(bool) (WP 7.0)
    Если true, блок регистрируется как PHP-only блок и автоматически становится доступен в редакторе без JS-регистрации. Требует render_callback.
    Смотите пример ниже.
    См. https://make.wordpress.org/core/2026/03/03/php-only-block-registration/

• example(array|null)
  Данные для preview блока в inserter. Обычно содержит пример attributes и innerBlocks.

• render_callback(callable|null)
  Функция рендера динамического блока. Принимает $attributes, $content, $block. Если указана, блок считается динамическим.

• attributes(array|null)
  Схемы атрибутов блока. Описывают тип, значение по умолчанию, источник данных и правила валидации.

  В WP 7.0 это PHP-only block registration через:

  'supports' => [
  	'autoRegister' => true,
  ],

  Блок должен иметь render_callback. Тогда WP сам регистрирует блок в редакторе и генерирует простые поля в Inspector Controls.

  Основные поля в attributes, которые влияют на авто-контрол:

  'attributes' => [
  	'title'   => [
  		'label'   => 'Title',
  		'type'    => 'string',
  		'default' => 'Hello World',
  	],
  	'count'   => [
  		'label'   => 'Count',
  		'type'    => 'integer',
  		'default' => 5,
  	],
  	'enabled' => [
  		'label'   => 'Enabled?',
  		'type'    => 'boolean',
  		'default' => true,
  	],
  	'size'    => [
  		'label'   => 'Size',
  		'type'    => 'string',
  		'enum'    => [ 'small', 'medium', 'large' ],
  		'default' => 'medium',
  	],
  ],

  Доступно для автогенерации:

  • label - название поля
  • type: string - текстовое поле
  • type: number / integer - числовое поле
  • type: boolean - toggle/checkbox
  • enum - select/dropdown
  • default - значение по умолчанию

  Контрол не будет создан, если:

  • есть source, потому что это HTML-derived атрибут
  • role => 'local'
  • тип не string, number, integer, boolean ([GitHub][2])

  То есть object, array, rich-text, query и сложные структуры для PHP-only auto controls не подходят. Для них нужен свой JS edit/InspectorControls.

• uses_context(string[])
  Контекст, который блок получает от родительских блоков. Например, postId, postType или собственные значения контекста.

• provides_context(string[]|null)
  Контекст, который блок передает вложенным блокам. Обычно связывает имя контекста с атрибутом блока.

• block_hooks(string[])
  Правила автоматической вставки блока рядом с другим блоком. Используется Block Hooks API.

• editor_script_handles(string[])
  Handles скриптов, которые подключаются только в редакторе.

• script_handles(string[])
  Handles скриптов, которые подключаются и в редакторе, и на front-end.

• view_script_handles(string[])
  Handles скриптов, которые подключаются только на front-end при наличии блока.

• view_script_module_ids(string[])
  IDs script modules, которые подключаются только на front-end.

• editor_style_handles(string[])
  Handles стилей, которые подключаются только в редакторе.

• style_handles(string[])
  Handles стилей, которые подключаются и в редакторе, и на front-end.

• view_style_handles(string[])
  Handles стилей, которые подключаются только на front-end при наличии блока.

• editor_script(string|string[]) (устарел)
  Устаревший вариант editor_script_handles. Оставлен для обратной совместимости.

• script(string|string[]) (устарел)
  Устаревший вариант script_handles. Оставлен для обратной совместимости.

• view_script(string|string[]) (устарел)
  Устаревший вариант view_script_handles. Оставлен для обратной совместимости.

• editor_style(string|string[]) (устарел)
  Устаревший вариант editor_style_handles. Оставлен для обратной совместимости.

• style(string|string[]) (устарел)
  Устаревший вариант style_handles. Оставлен для обратной совместимости.

По умолчанию: []

Примеры

#1 Использование WP Dashicon для блока

Для этого нужно в $args в параметре icon указать иконку без префикса dashicons-:

add_action( 'init', 'wpkama_register_block' );

function wpkama_register_block(){
	register_block_type(
		__DIR__ . '/block.json',
		[
			'icon' => 'admin-home', /* omit 'dashicons-' prefix */
		]
	);
}

Все имена Dashicons: https://developer.wordpress.org/resource/dashicons/

#2 Как написать плагин/тему с несколькими блоками

Создание папки src

1. Запустите команду:

   npx @wordpress/create-block@latest my-blocks --variant=dynamic
   cd my-blocks

   Подробнее смотрите мануал https://developer.wordpress.org/block-editor/getting-started/tutorial/

2. Переместите содержимое каталога src в подкаталог, например block-a: src/block-a.

3. Продублируйте подкаталог block-a, чтобы создать второй блок, и назовите его, например, block-b.

4. Обновите файлы block.json в каждом подкаталоге, чтобы они соответствовали требованиям блоков.

   Должна получится такая структура:

   my-blocks
   ├── package.json
   ├── package-lock.json
   └── src
   	├── block-a
   	│   ├── block.json
   	│   ├── edit.js
   	│   ├── editor.scss
   	│   ├── index.js
   	│   ├── render.php
   	│   ├── style.scss
   	│   └── view.js
   	└── block-b
   		├── block.json
   		├── edit.js
   		├── editor.scss
   		├── index.js
   		├── render.php
   		├── style.scss
   		└── view.js

   Пример содержимого block.json:

   {
   	"$schema": "https://schemas.wp.org/trunk/block.json",
   	"apiVersion": 3,
   	"name": "create-block/block-a",
   	"version": "0.1.0",
   	"title": "Block A",
   	"category": "widgets",
   	"icon": "smiley",
   	"description": "Example block scaffolded with Create Block tool.",
   	"example": {},
   	"supports": {
   		"html": false
   	},
   	"textdomain": "wpkama",
   	"render": "file:./render.php",
   	"editorScript": "file:./index.js",
   	"editorStyle": "file:./index.css",
   	"viewStyle": "file:./style-index.css",
   	"viewScript": "file:./view.js"
   }

5. Выполните команду npm run build в каталоге my-blocks. Будут созданы соответствующие директории в папке my-blocks/build.

Регистрация блоков

Теперь нужно зарегистрировать блоки в PHP, указав на соответствующую директорию в папке build:

add_action( 'init', 'wpdocs_create_blocks_mysite_block_init' );

function wpdocs_create_blocks_mysite_block_init() {

	register_block_type( __DIR__ . '/build/block-a' );
	register_block_type( __DIR__ . '/build/block-b' );
}

Перемещение папки блоков внутрь проекта

Если у вас папка npm пакетов node_modules находится где-то выше, а блоки должны находится внутри, например в папке темы, то можно указать пути где лежат исходники и куда выкладывать билды.

Для этого добавьте опции в скрипты build и start в файле package.json:

"scripts": {
	"build": "wp-scripts build --webpack-src-dir=path/to/my-blocks/src/ --output-path=path/to/my-blocks/build/ --webpack-copy-php",
	"start": "wp-scripts start --webpack-src-dir=path/to/my-blocks/src/ --output-path=path/to/my-blocks/build/ --webpack-copy-php",
	...
}

Теперь npm run build можно запускать из папки где лежит package.json, и блоки будут билдиться в во внутренней папке (там где вы указали).

#3 Регистрация блока на PHP в WP 7.0 (PHP-only)

Минимальный пример, который показывает все автополя PHP-only блока в WP 7.0:

add_action( 'init', 'my_register_php_only_block' );

function my_register_php_only_block() {
	register_block_type(
		'my/test-php-block',
		[
			'title'       => __( 'PHP Test Block', 'my-textdomain' ),
			'description' => __( 'PHP-only block with auto controls.', 'my-textdomain' ),
			'category'    => 'widgets',
			'icon'        => 'admin-generic',
			'keywords'    => [ 'test', 'php' ],

			'attributes' => [
				'title' => [
					'label'   => __( 'Title', 'my-textdomain' ),
					'type'    => 'string',
					'default' => 'Hello World',
				],

				'count' => [
					'label'   => __( 'Count', 'my-textdomain' ),
					'type'    => 'integer',
					'default' => 5,
				],

				'price' => [
					'label'   => __( 'Price', 'my-textdomain' ),
					'type'    => 'number',
					'default' => 9.99,
				],

				'enabled' => [
					'label'   => __( 'Enabled', 'my-textdomain' ),
					'type'    => 'boolean',
					'default' => true,
				],

				'size' => [
					'label'   => __( 'Size', 'my-textdomain' ),
					'type'    => 'string',
					'enum'    => [ 'small', 'medium', 'large' ],
					'default' => 'medium',
				],
			],

			'supports' => [
				'autoRegister' => true,
				'align'        => true,
				'anchor'       => true,
				'className'    => true,
				'color'        => [
					'text'       => true,
					'background' => true,
					'gradients'  => true,
				],
				'spacing'      => [
					'margin'  => true,
					'padding' => true,
				],
				'typography'   => [
					'fontSize'   => true,
					'lineHeight' => true,
				],
			],

			'render_callback' => 'my_render_php_only_block',
		]
	);
}

function my_render_php_only_block( $attributes, $content, $block ) {
	$title   = $attributes['title'] ?? '';
	$count   = $attributes['count'] ?? 0;
	$price   = $attributes['price'] ?? 0;
	$enabled = ! empty( $attributes['enabled'] );
	$size    = $attributes['size'] ?? 'medium';

	$wrapper_attributes = get_block_wrapper_attributes(
		[
			'class' => 'my-test-php-block is-size-' . sanitize_html_class( $size ),
		]
	);

	ob_start();
	?>
	<div <?php echo $wrapper_attributes; ?>>
		<h2><?php echo esc_html( $title ); ?></h2>

		<p><?php echo esc_html( $count ); ?></p>
		<p><?php echo esc_html( $price ); ?></p>
		<p><?php echo $enabled ? 'Enabled' : 'Disabled'; ?></p>
	</div>
	<?php
	return ob_get_clean();
}

Автоконтролы сейчас реально покрывают:

• string - текстовое поле
• integer - числовое поле
• number - числовое поле
• boolean - toggle
• enum - select

textarea, object, array, rich text, media, color picker как attribute-контролы так не создать. Для этого уже нужен JS edit.

supported настройки типа color, spacing, typography, align, anchor, className работают как обычные block supports, отдельно от attributes.

PHP-only блоки появляются в редакторе через supports.autoRegister и требуют render_callback.

#4 Зарегистрируем новый тип блока без дополнительных параметров

add_action( 'init', 'gutenberg_block_register_block' );
add_action( 'enqueue_block_editor_assets', 'gutenberg_block_editor_scripts' );

// Регистрируем новый тип бока
function gutenberg_block_register_block() {
	register_block_type( 'gutenberg-block/example', [] );
}

// Регистрируем основной скрипт для блока
function gutenberg_block_editor_scripts() {
	wp_register_script(
		'example',
		plugins_url( 'build/index.js', __FILE__ ),
		['wp-blocks']
	);

	wp_enqueue_script( 'example' );
}

#5 Зарегистрируем новый тип блока с дополнительными параметрами

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

new Gutenberg_Block_Example(); // инициализация

class Gutenberg_Block_Example {

	public function __construct() {
		add_action( 'init', [ $this, 'gutenberg_block_register_block' ] );
		add_action( 'enqueue_block_editor_assets', [ $this, 'gutenberg_block_editor_scripts' ] );
	}

	public function gutenberg_block_register_block() {

		register_block_type( 'gutenberg-block/example', [
			'render_callback' => [ $this, 'gutenberg_block_render_callback' ],
			'attributes'      => [
				'posts_per_page' => [
					'type'    => 'number',
					'default' => 3,
				],
				'order'        => [
					'type'    => 'string',
					'default' => 'desc',
				],
			],

		] );
	}

	public function gutenberg_block_editor_scripts() {

		wp_register_script(
			'example',
			plugins_url( 'build/index.js', __FILE__ ),
			['wp-blocks']
		);

		wp_enqueue_script( 'example' );

	}

	public function gutenberg_block_render_callback( $attributes, $content ) {

		$args = [
			'posts_per_page' => $attributes['postsPerPage'],
			'post_status'    => 'publish',
			'order'          => $attributes['order'],
		];

		$posts = get_posts( $args );

		$html = '<div>';

		if ( $posts ) {
			$html .= '<ul>';

			foreach ( $posts as $item ) {
				$html .= '<li><a href="' . get_the_permalink( $item->ID ) . '">' . $item->post_title . '</a></li>';
			}

			$html .= '</ul>';
		} else {
			$html .= '<h3>' . __( 'No posts!', 'gutenberg-blocks' ) . '</h3>';
		}

		$html .= '</div>';

		return $html;

	}

}

#6 Передача произвольных атрибутов в $attributes

Вы можете передать свои атрибуты $attributes, которые могут быть использованы как в редакторе, так и на фронт-энде в render_callback:

register_block_type( 'my_namespace/my_block', [
	'render_callback' => 'render_callback',
	'attributes'      => [
		'some_string' => [
			'default' => 'default string',
			'type'    => 'string'
		],
		'some_array'  => [
			'type'  => 'array',
			'items' => [
				'type' => 'string',
			],
		]
	],
	'render_callback' => 'render_block_my_custom_blocks_calendar',
	'editor_script'   => 'calendar-editor-js',
	'editor_style'    => 'calendar-editor-css',
	'script'          => 'calendar-frontend-js',
	'style'           => 'calendar-frontend-css',
] );

Важно (проверено в 5.0.3): Обязательно нужно указать тип параметра, иначе будет выдан notice.

#7 Авто-создание блоков через .json файлы

class My_Blocks {

	public function setup_hooks(): void {
		add_action( 'init', [ $this, 'register_blocks' ] );
		add_filter( 'block_categories_all', [ $this, 'register_block_category' ] );
	}

	public function register_blocks(): void {
		$blocks = glob( __DIR__ . '/Blocks/*/block.json');

		if ( ! $blocks ) {
			return;
		}

		foreach ( $blocks as $block ) {
			register_block_type( $block );
		}
	}

}

( new My_Blocks() )->setup_hooks();

Пример .json файла:

{
  "name": "ice-cream/slider",
  "title": "Ice Cream Slider",
  "description": "Простой настраиваемый слайдер изображений",
  "style": "block.css",
  "category": "ice-cream",
  "icon": "images-alt",
  "apiVersion": 2,
  "keywords": [],
  "styles": [],
  "supports": {
	"align": false,
	"anchor": false,
	"alignContent": false,
	"color": {
	  "text": false,
	  "background": true,
	  "link": false
	},
	"alignText": false,
	"fullHeight": false
  }
}

Read more here: https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/

#8 PHP-only регистрация блоков

Регистрация блока только через PHP: https://make.wordpress.org/core/2026/03/03/php-only-block-registration/

WordPress 7.0 позволяет создавать простые блоки только на PHP, без JavaScript-регистрации на стороне редактора.

Это подходит для блоков, которые:

• рендерятся только на сервере;
• не требуют сложной интерактивности;
• используются в классических темах;
• подходят для server-driven workflows;
• не требуют полноценной клиентской логики.

Этот API не заменяет обычный подход к созданию блоков через JavaScript и не предназначен для сложных интерактивных блоков.

Чтобы создать такой блок, нужно использовать register_block_type() и добавить поддержку autoRegister.

Также обязательно нужно указать render_callback.

add_action( 'init', 'gutenberg_register_php_only_blocks' );
function gutenberg_register_php_only_blocks() {
	register_block_type(
		'my-plugin/example',
		[
			'title'           => __( 'My Example Block', 'myplugin' ),
			'attributes'      => [
				'title'   => [
					'label'   => __( 'Title', 'myplugin' ),
					'type'    => 'string',
					'default' => 'Hello World',
				],
				'count'   => [
					'label'   => __( 'Count', 'myplugin' ),
					'type'    => 'integer',
					'default' => 5,
				],
				'enabled' => [
					'label'   => __( 'Enabled?', 'myplugin' ),
					'type'    => 'boolean',
					'default' => true,
				],
				'size'    => [
					'label'   => __( 'Size', 'myplugin' ),
					'type'    => 'string',
					'enum'    => [ 'small', 'medium', 'large' ],
					'default' => 'medium',
				],
			],
			'render_callback' => function ( $attributes ) {
				return sprintf(
					__( '<p>%s: %d items (%s)</p>', 'myplugin' ),
					esc_html( $attributes['title'] ),
					(int) $attributes['count'],
					esc_html( $attributes['size'] )
				);
			},
			'supports'        => [
				'autoRegister' => true,
			],
		]
	);
}

После регистрации такой блок автоматически появится в редакторе. JavaScript-регистрация через registerBlockType() не требуется.

Где возможно, редактор сам сгенерирует контролы в боковой панели Inspector Controls для редактирования атрибутов блока.

Важно:

• контролы не будут созданы для атрибутов с ролью local;
• контролы не будут созданы для неподдерживаемых типов атрибутов;
• API подходит только для простых server-side блоков;
• для сложных блоков всё ещё нужен обычный JavaScript-подход.