Функция register_block_type_from_metadata() в WordPress

Функция register_block_type_from_metadata() позволяет регистрировать блоки в WordPress, используя метаданные, хранящиеся в файле block.json. Этот способ регистрации блоков появился в WordPress 5.8 и является удобным для использования метаданных, но на версиях WordPress от 5.5 до 5.7 следует использовать именно эту функцию. В более поздних версиях WordPress рекомендуется использовать более короткую функцию register_block_type().

register_block_type_from_metadata( string $file_or_folder, array $args = array() ): WP_Block_Type|false

• $file_or_folder (обязательный) — строка, путь к JSON файлу с метаданными для блока или к папке, где находится файл block.json. Если указывается путь к файлу, его имя должно оканчиваться на block.json.
• $args (необязательный) — массив аргументов для настройки блока. Принимает публичные свойства объекта WP_Block_Type.

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

Параметры в block.json

Файл block.json содержит метаданные, описывающие блок. Например:

• name — уникальное имя блока.
• title — название блока.
• category — категория, к которой относится блок.
• icon — иконка блока.
• description — описание блока.
• attributes — атрибуты блока.
• supports — возможности блока, такие как поддержка HTML или стилей.
• scripts и styles — скрипты и стили, которые необходимо подключить для работы блока.

Пример 1: Регистрация блока с указанием пути к JSON файлу

add_action( 'init', 'register_my_block' );

function register_my_block() {
    register_block_type_from_metadata( __DIR__ . '/block.json' );
}

Здесь блок регистрируется на основе метаданных, содержащихся в файле block.json, который находится в текущей директории.

Пример 2: Регистрация блока с аргументами

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

add_action( 'init', 'register_custom_block' );

function register_custom_block() {
    register_block_type_from_metadata(
        __DIR__ . '/block.json',
        [
            'icon' => 'admin-home', // Указание иконки
        ]
    );
}

Пример 3: Регистрация нескольких блоков

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

Структура директорий:

my-blocks
├── block-a
│   └── block.json
├── block-b
    └── block.json

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

add_action( 'init', 'register_multiple_blocks' );

function register_multiple_blocks() {
    register_block_type_from_metadata( __DIR__ . '/block-a' );
    register_block_type_from_metadata( __DIR__ . '/block-b' );
}

Пример 4: Автоматическая регистрация блоков

Если блоков много, можно автоматизировать их регистрацию, просматривая все подкаталоги в директории Blocks:

class My_Blocks {

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

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

        if ( ! $blocks ) {
            return;
        }

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

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

Структура файла block.json

{
    "$schema": "https://schemas.wp.org/trunk/block.json",
    "apiVersion": 2,
    "name": "custom/block",
    "title": "Custom Block",
    "category": "widgets",
    "icon": "smiley",
    "description": "Пример блока с настройками.",
    "supports": {
        "html": false
    },
    "editorScript": "file:./index.js",
    "editorStyle": "file:./index.css",
    "viewScript": "file:./view.js",
    "viewStyle": "file:./style.css"
}

Заключение

Использование этой функции оправдано в версиях WordPress 5.5 – 5.7, где ещё не было внедрено сокращение до register_block_type(). В более новых версиях WordPress предпочтительнее использовать короткую функцию.

Однако register_block_type_from_metadata() может быть полезна, если требуется обеспечить обратную совместимость для старых сайтов, которые ещё используют ранние версии WordPress.