REGISTER_BLOCK_TYPE() │ WP 5.0.0

Функция register_block_type() позволяет зарегистрировать новый тип блока в Gutenberg (редакто��е блоков WordPress).

Возвращаемое значение

Функция возвращает объект типа WP_Block_Type при успешной регистрации блока или false в случае ошибки.

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

register_block_type( $block_type, $args );

• $block_type (string|WP_Block_Type) — обязательный параметр. Имя типа блока, включая пространство имен, или путь к файлу JSON с метаданными блока. Также можно передать объект типа WP_Block_Type. Если передан этот объект, параметр $args будет игнорироваться.
• $args (array) — массив аргументов для типа блока. Принимает любые публичные свойства объекта WP_Block_Type. По умолчанию — пустой массив.

Примеры

Пример 1: Регистрация нового типа блока с дополнительными параметрами

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

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['posts_per_page'],
            'post_status'    => 'publish',
            'order'          => $attributes['order'],
        ];

        $posts = get_posts( $args );

        $html = '
';
        if ( $posts ) {
            $html .= '
';
            foreach ( $posts as $item ) {
                $html .= '
' . $item->post_title . '
';
            }
            $html .= '
';
        } else {
            $html .= '
' . __( 'Нет постов!', 'gutenberg-blocks' ) . '
';
        }
        $html .= '
';

        return $html;
    }
}

Пример 2: Регистрация нового типа блока без дополнительных параметров

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' );
}

Пример 3: Передача пользовательских атрибутов

Вы можете передать свои атрибуты, которые будут использоваться как в редакторе, так и на фронтенде:

register_block_type( 'my_namespace/my_block', [
    'render_callback' => 'render_callback',
    'attributes'      => [
        'some_string' => [
            'default' => 'строка по умолчанию',
            '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',
] );

Обратите внимание: обязательно указывайте параметр type, иначе будет выдано уведомление.

Пример 4: Автоматическое создание блоков через файлы .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": "Слайдер мороженого",
  "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
  }
}

Пример 5: Использование Dashicon для блока

Чтобы указать иконку, не добавляйте префикс dashicons- в $args:

add_action( 'init', 'wpkama_register_block' );

function wpkama_register_block(){
    register_block_type(
        __DIR__ . '/build.json',
        [
            'icon' => 'admin-home', /* уберите префикс 'dashicons-' */
        ]
    );
}

Пример 6: Как написать плагин/тему с несколькими блоками

• Создайте папку src, перейдите в неё и выполните команду npx @wordpress/create-block@latest my-blocks --variant=dynamic, затем cd my-blocks.
• Переместите содержимое директории src в подпапку, например, block-a: src/block-a.
• Дублируйте подпапку block-a, создайте вторую и назовите, например, block-b.
• Обновите файлы block.json в каждой подпапке, чтобы соответствовать требованиям блока.

Структура должна выглядеть так:

my-blocks
├── package.json
├── package-lock.json
└── src
    ├── block-a
    │   ├── block.json
    │   ├── edit.js
    │   ├── index.js
    │   ├── render.php
    │   ├── style.scss
    │   └── view.js
    └── block-b
        ├── block.json
        ├── edit.js
        ├── 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": "Блок A",
    "category": "widgets",
    "icon": "smiley",
    "description": "Пример блока, созданного с помощью инструмента Create Block.",
    "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"
}

Теперь выполните команду 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' );
}

Для настройки путей используйте опции в скриптах 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, и блоки будут собраны в указанной вами папке.

Изменения

Функция register_block_type() была введена в версии 5.0.0, в версии 5.8.0 первый параметр теперь принимает путь к файлу block.json.