register_block_type()
Регистрирует новый тип блока для редактора блоков (Гутенберг).
Для корректной регистрации блока поле $block_type должно быть идентичным в php функции
register_block_type( 'alias/example', [] )
и js функции
registerBlockType( 'alias/example', {} )
Офф документация по редактору блоков: https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/
Хуков нет.
Возвращает
WP_Block_Type|false
. Объект зарегистрированного блока в случае успеха или false в случае ошибки.
Использование
register_block_type( $block_type, $args );
- $block_type(строка/WP_Block_Type) (обязательный)
Имя типа блока, включая пространство имен или полный экземпляр WP_Block_Type. Параметр $args не нужен, когда указан экземпляр WP_Block_Type (он будет проигнорирован).
Можно указать пусть к файлу блока:
register_block_type( __DIR__ . '/block.json' );
- $args(массив)
Массив аргументов блока. Принимает любое публичное свойство класса WP_Block_Type. Возможные параметры смотрите в WP_Block_Type::__construct().
- render_callback(callable)
Функция обратного вызова, используемая для отображения контента блока. Принимает параметры $attributes и $content
По умолчанию: array()
- render_callback(callable)
Примеры
#1 Зарегистрируем новый тип блока без дополнительных параметров
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' ); }
#2 Зарегистрируем новый тип блока с дополнительными параметрами
Пример показывает как регистрировать блок в контексте класса. Блок бдует выводить записи.
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; } }
#3 Pass custom $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.
#4 Использование WP Dashicon
Префикс dashicons-
нужно удалить:
register_block_type( __DIR__ . '/build.json', [ 'icon' => 'admin-home', // omit 'dashicons-' prefix ] );
#5 Авто-создание блоков через .json файлы
class My_Blocks { public function setup_hooks(): void { add_action( 'acf/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": [], "acf": { "mode": "preview", "renderTemplate": "render.php" }, "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/
#6 Использование dashicon для блока
Для этого нужно в $args в параметре icon
указать иконку без префикса dashicons-
:
register_block_type( __DIR__ . '/build', [ 'icon' => 'admin-home', /* omit 'dashicons-' prefix */ ] );
Все имена Dashicons: https://developer.wordpress.org/resource/dashicons/
Список изменений
С версии 5.0.0 | Введена. |
С версии 5.8.0 | First parameter now accepts a path to the block.json file. |
Код register_block_type() register block type WP 6.1.1
function register_block_type( $block_type, $args = array() ) { if ( is_string( $block_type ) && file_exists( $block_type ) ) { return register_block_type_from_metadata( $block_type, $args ); } return WP_Block_Type_Registry::get_instance()->register( $block_type, $args ); }