Функция REGISTER_BLOCK_TYPE_FROM_METADATA() │ WP 5.5.0

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

Используемые функции

• WP_Block_Type_Registry()
• wp_json_file_decode()
• register_block_script_handle()
• register_block_style_handle()
• register_block_script_module_id()

Используется в

• register_block_type()

Хуки, используемые функцией

• block_type_metadata
• block_type_metadata_settings

Возврат

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

Синтаксис

register_block_type_from_metadata( $file_or_folder, $args );

Параметры

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

• $args (массив) — Массив аргументов для типа блока. Принимает любые публичные свойства класса WP_Block_Type. По умолчанию: пустой массив.

Примеры использования

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

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

add_action( 'init', 'wpkama_register_block' );

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

Пример 2: Автоматическое создание блоков через .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
  }
}

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

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

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

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

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": "Пример блока, созданного с помощью инструмента 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"
}

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, а блоки будут собраны в внутренней папке (где вы указали).

Изменения в функции

• С 5.5.0 — функция была введена.
• С 5.7.0 — добавлена поддержка поля textdomain и обработка i18n для всех переводимых полей.
• С 5.9.0 — добавлена поддержка полей variations и viewScript.
• С 6.1.0 — добавлена поддержка поля render.
• С 6.3.0 — добавлено поле selectors.
• С 6.4.0 — добавлена поддержка поля blockHooks.
• С 6.5.0 — добавлены поля allowedBlocks, viewScriptModule и viewStyle.
• С 6.7.0 — разрешено использовать PHP имя файла в качестве аргумента variations.

Это основная информация о функции register_block_type_from_metadata(). Если у вас есть вопросы, пожалуйста, дайте знать!