С появлением редактора Gutenberg создание собственных блоков в WordPress стало значительно проще. Одним из ключевых элементов современной разработки является файл block.json, который содержит описание блока, его настройки, подключаемые ресурсы и метаданные. Вместо регистрации каждого параметра через PHP разработчик может описать всю конфигурацию в одном JSON-файле, а WordPress автоматически зарегистрирует блок и связанные с ним CSS, JavaScript и другие ресурсы.

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

Что такое block.json

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

Файл обычно располагается в каталоге блока:

my-plugin/ └── blocks/ └── card/ ├── block.json ├── index.js ├── editor.css ├── style.css └── render.php

Преимущества использования block.json

  • единая конфигурация блока;
  • автоматическая регистрация ресурсов;
  • меньше PHP-кода;
  • поддержка современных возможностей WordPress;
  • лучшая совместимость с редактором Gutenberg;
  • удобная структура проекта;
  • простое сопровождение блоков.

Минимальный block.json

{ "$schema": "https://schemas.wp.org/trunk/block.json", "apiVersion": 3, "name": "mytheme/card", "title": "Карточка", "category": "widgets" }

Даже такого файла достаточно для регистрации базового блока.

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

В файле functions.php или основном файле плагина:

add_action('init', function () { register_block_type( __DIR__ . '/blocks/card' ); });

WordPress автоматически прочитает содержимое block.json.

Основные параметры block.json

Параметр Описание
apiVersion Версия Block API
name Уникальное имя блока
title Название блока
description Описание
category Категория
icon Иконка
keywords Ключевые слова
attributes Атрибуты
supports Поддерживаемые возможности
style CSS сайта
editorStyle CSS редактора
editorScript JS редактора
script JS сайта и редактора
viewScript JS только фронтенда
render PHP-шаблон динамического блока

Название блока

{ "name":"mytheme/card" }

Имя должно быть уникальным и содержать пространство имен.

Добавление описания

{ "description":"Карточка товара" }

Выбор категории

{ "category":"widgets" }

Популярные категории:

  • text
  • media
  • widgets
  • design
  • theme
  • embed

Добавление иконки

{ "icon":"admin-post" }

Можно использовать любую Dashicons-иконку.

Ключевые слова

{ "keywords":[ "карточка", "товар", "каталог" ] }

Подключение JavaScript

{ "editorScript":"file:./index.js" }

Файл используется только внутри редактора Gutenberg.

Подключение CSS редактора

{ "editorStyle":"file:./editor.css" }

Подключение CSS сайта

{ "style":"file:./style.css" }

Подключение JavaScript фронтенда

{ "viewScript":"file:./view.js" }

Используется только на опубликованных страницах.

Подключение общего JavaScript

{ "script":"file:./script.js" }

Файл загружается и в редакторе, и на сайте.

Создание атрибутов

{ "attributes":{ "title":{ "type":"string", "default":"" }, "text":{ "type":"string" } } }

Поддержка настроек блока

{ "supports":{ "align":true, "anchor":true, "color":{ "background":true, "text":true }, "spacing":{ "margin":true, "padding":true } } }

После регистрации соответствующие настройки автоматически появятся в боковой панели редактора.

Динамический блок

{ "render":"file:./render.php" }

Вместо сохранения HTML WordPress будет использовать PHP.

Пример render.php

<?php return sprintf( '<div class="card">%s</div>', esc_html( $attributes['title'] ) );

Использование нескольких файлов

{ "style":[ "file:./style.css", "file:./animations.css" ] }

Полный пример block.json

{ "$schema":"https://schemas.wp.org/trunk/block.json", "apiVersion":3, "name":"mytheme/card", "title":"Карточка", "description":"Информационная карточка", "category":"widgets", "icon":"screenoptions", "keywords":[ "карточка", "блок", "товар" ], "editorScript":"file:./index.js", "editorStyle":"file:./editor.css", "style":"file:./style.css", "viewScript":"file:./view.js", "attributes":{ "title":{ "type":"string" }, "text":{ "type":"string" } }, "supports":{ "align":true, "spacing":{ "padding":true } } }

Типичные ошибки

  • неверный синтаксис JSON;
  • отсутствует apiVersion;
  • неправильный путь к CSS или JS;
  • использование одинаковых имен блоков;
  • не совпадает имя блока в JavaScript и block.json;
  • отсутствует register_block_type();
  • не очищен кэш после сборки проекта.

Итог

  • используйте актуальную версию apiVersion;
  • размещайте каждый блок в отдельной директории;
  • подключайте ресурсы через file:, а не вручную;
  • используйте понятные пространства имен для параметра name;
  • разделяйте стили редактора и фронтенда;
  • используйте динамический рендеринг для блоков с изменяющимися данными;
  • добавляйте описание и ключевые слова для удобного поиска блока в редакторе.

Файл block.json является основой современной разработки блоков Gutenberg в WordPress. Он объединяет регистрацию блока, подключение CSS и JavaScript, описание атрибутов, поддержку возможностей редактора и динамический рендеринг в одном конфигурационном файле. Использование block.json делает код более структурированным, сокращает количество PHP, упрощает сопровождение проекта и обеспечивает совместимость с актуальными версиями WordPress. При разработке новых тем и плагинов рекомендуется использовать именно этот подход, так как он соответствует современным стандартам Block API и значительно ускоряет процесс создания собственных блоков.

Метки: ,