block.json

Справочник параметров block.json в WordPress

Файл block.json нужен, чтобы упростить создание и регистрацию блоков в WordPress.

Он описывает блок в формате JSON и используется и на сервере (php), и в редакторе блоков (js) — то есть один файл отвечает сразу за всё.

В официальной документации есть полный список всех свойств block.json.

Документация по theme.json.

Смотрите также:

  • Используйте register_block_type(), чтобы зарегистрировать блок.

  • Используйте registerBlockType(), чтобы регистрировать блоки через JS.

Пример block.json:

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "my-plugin/notice",
  "title": "Notice",
  "description": "Shows warning, error or success notices...",
  "icon": "star",
  "category": "text",
  "keywords": [ "alert", "message" ],
  "textdomain": "my-plugin",

  "parent": [ "core/group" ],

  "render": "file:./render.php",

  "script": "file:./script.js",
  "style": [ "file:./style.css", "example-shared-style" ],
  "editorScript": "file:./index.js",
  "editorStyle": "file:./index.css",
  "viewScript": [ "file:./view.js", "example-shared-view-script" ],
  "viewStyle": [ "file:./view.css", "example-view-style" ],

  "attributes": {
	"message": {
	  "type": "string",
	  "source": "html",
	  "selector": ".message"
	}
  },

  "supports": {
	"align": true
  },

  "styles": [
	{ "name": "default", "label": "Default", "isDefault": true },
	{ "name": "other", "label": "Other" }
  ],

  "providesContext": {
	"my-plugin/message": "message"
  },

  "usesContext": [ "groupId" ],

  "selectors": {
	"root": ".wp-block-my-plugin-notice"
  },

  "example": {
	"attributes": {
	  "message": "This is a notice!"
	}
  },

  "variations": [
	{
	  "name": "example",
	  "title": "Example",
	  "attributes": {
		"message": "This is an example!"
	  }
	}
  ]
}

Параметры

Основные параметры:

  • apiVersion — Версия API, которую использует блок. Обычно нужно указывать последнюю.
  • name — Уникальное имя блока с пространством имён (например, my-plugin/my-custom-block).
  • title — Заголовок блока, отображаемый во вставщике.
  • category — Категория, в которой блок будет показан во вставщике. Общие категории: text, media, design, widgets, theme.
  • icon — Иконка блока во вставщике (может быть slug из Dashicons или SVG).
  • description — Короткое описание блока (больше деталей, чем у заголовка).
  • keywords — Массив ключевых слов, чтобы легче находить блок через поиск.
  • textdomain — Текстовый домен для перевода блока.

Подключаемые файлы для вывода и стилей блока:

  • script — JS-файл(ы) для фронта и редактора.
  • style — CSS-файл(ы) для фронта и редактора.
  • editorScript — JS-файл(ы) только для редактора блоков.
  • editorStyle — CSS-файл(ы) только для редактора.
  • viewScript — JS-файл(ы), только для фронта.
  • viewScriptModule — ES-модуль только на фронте.
  • viewStyle — CSS-файл(ы) только на фронте.

Свойство render
В WP 6.1, появилось свойство render, которое указывает путь к PHP-шаблону для динамического рендеринга блока на фронтенде.

Оглавление:
$schema(строка)
URI схемы JSON, чтобы IDE подсказывал. Обычно: https://schemas.wp.org/trunk/block.json.
По умолчанию: —
apiVersion(число) (обязательный)
Версия API, которую использует блок. Рекомендуется укаывзать последнюю. Например 3.
name(строка) (обязательный)
Уникальное имя блока namespace/block-name.
title(строка) (обязательный)
Заголовок блока, отображаемый во вставщике.
icon(строка)
Иконка блока во вставщике (может быть slug из Dashicons или SVG).
По умолчанию: —
category(строка)
Категория вставщика: text, media, design, widgets, theme, embed или произвольная.
Категория, в которой блок будет показан во вставщике.
Общие категории: text, media, design, widgets, theme.
По умолчанию: —
description(строка)

Короткое описание блока (больше деталей, чем у заголовка).

Выводится в панели блока (в инспекторе) (sidebar справа в редакторе блоков), когда блок выбран. Отображается под заголовком блока и помогает пользователю понять назначение подробнее.

По умолчанию: —

keywords(массив)
Массив ключевых слов (синонимов), чтобы легче находить блок через поиск.
По умолчанию: —
textdomain(строка)
Текстовый домен для перевода блока.
По умолчанию: —
script(строка/массив)
style(строка/массив)
editorScript(строка/массив)
editorStyle(строка/массив)
viewScript(строка/массив)
viewScriptModule(строка/массив)
viewStyle(строка/массив)

Файлы (скрипты и стили) которые отвечают за функциональность блока:

  • script — JS-файл(ы) для фронта и редактора.
  • style — CSS-файл(ы) для фронта и редактора.
  • editorScript — JS-файл(ы) только для редактора блоков.
  • editorStyle — CSS-файл(ы) только для редактора.
  • viewScript — JS-файл(ы), только для фронта.
  • viewScriptModule — ES-модуль только на фронте.
  • viewStyle — CSS-файл(ы) только на фронте.

Для всех этих параметров можно указать:

  • Путь к файлу (с префиксом file:),
  • Handle скрипта/стиля, зарегистрированного через wp_register_script() / wp_register_style(),
  • Массив из этих вариантов.

По умолчанию: —

render(строка) (WP 6.1)

Указывает путь к PHP-шаблону для динамического рендеринга блока на фронтенде.

Используется, если при регистрации блока в register_block_type() не передан параметр $render_callback.

По умолчанию: —

attributes(объект)

Атрибуты (параметры, свойства) блока.

Ключи-атрибуты → объект со свойствами:

  • type (строка/массив строк)
    Тип данных (null|boolean|object|array|string|rich-text|integer|number).

  • enum (массив)
    Фиксированный набор значений.

  • source (строка)
    Источник (attribute|text|rich-text|html|raw|query|meta).

  • selector (строка)
    CSS-селектор для извлечения.

  • attribute (строка)
    Имя HTML-атрибута при source=attribute.

  • query (объект)
    Схема выборки массива из разметки.

  • meta (строка)
    Ключ пост-меты (устаревший подход).

  • role (строка)
    content или local.

  • default (любой)
    Значение по умолчанию.

По умолчанию: —

blockHooks(объект)
Автовставка рядом с другими блоками: ключ namespace/block → before|after|firstChild|lastChild.
По умолчанию: —
parent(массив)

Ограничивает использование блока — он становится доступным только внутри указанных родительских блоков.

Если задать parent, блок исчезнет из общего вставщика и будет доступен только в тех местах, где родительский блок разрешает InnerBlocks.

Значения указываются как namespace/block.

Можно перечислить несколько родителей.

Пример:

{
  "name": "my-plugin/child",
  "title": "Child block",
  "apiVersion": 3,
  "parent": [ "core/columns", "core/group" ]
}

В этом примере блок my-plugin/child можно добавить только внутрь core/columns или core/group, но не отдельно.

Это удобно для «связанных» блоков — например:

  • «List Item» можно вставлять только внутри «List».
  • «Add to Cart» — только внутри «Product».

По умолчанию: —

ancestor(массив)

Список блоков, которые должны присутствовать в цепочке родителей (на любом уровне выше), чтобы данный блок можно было вставить.

"ancestor": [ "core/group", "core/columns" ]
  • Это проверка по всему дереву родителей, не только непосредственный родитель.

  • Можно комбинировать с parent:

    • parent ограничивает непосредственного родителя
    • ancestor требует наличие блока выше по дереву

По умолчанию: —

Пример: Разрешить блок только внутри core/group (на любом уровне вложенности):

{
  "name": "myplugin/child-block",
  "ancestor": [ "core/group" ]
}

Разрешить блок только если он находится внутри myplugin/slider, но непосредственным родителем должен быть core/group:

{
  "name": "myplugin/slider-item",
  "parent": [ "core/group" ],
  "ancestor": [ "myplugin/slider" ]
}

Это решает кейс slider > group > slider-item: slider-item вставляется в group только когда этот group расположен внутри slider.

allowedBlocks(массив) (WP 6.5)

Белый список блоков, которые могут быть вложенны в текущий блок.

Например: ["core/paragraph", "core/image"]

Параметр контролирует прямых потомков. Т.е. если например в текущий блок позволено (этим параметром) вложить только, например, core/group, то уже в core/group можно будет вложить то что позволено для core/group.

Этот параметр особенно полезен для контроля структуры — например, блок списка может разрешать только элементы списка, блок колонок — только колонки и т.п.

Если нужно динамически ограничивать вложенные блоки, используют свойство allowedBlocks компонента InnerBlocks в JavaScript, например:

<InnerBlocks allowedBlocks={ attributes.allowedBlocks } />

Но, если список статичен, предпочтительнее сразу указывать его в block.json.

По умолчанию: —

providesContext(объект)
Экспортируемый контекст: ключ контекста → имя атрибута блока.
По умолчанию: —
usesContext(массив)

Позволяет блоку объявить, какие значения из контекста он хочет наследовать от родительских блоков.

Контекст в Gutenberg — это механизм передачи данных сверху вниз по дереву блоков без явной передачи через атрибуты.

Как работает

  • Родительский блок указывает в providesContext, какие значения он «раздаёт» потомкам.
  • Потомок в usesContext перечисляет имена этих значений, чтобы их можно было использовать внутри edit/save функций.
  • В редакторе React-компонент такого блока получит эти данные в props.context.

Пример

{
  "name": "my-plugin/child-block",
  "title": "Child Block",
  "apiVersion": 3,
  "usesContext": [ "postId", "postType" ]
}

В JS-компоненте:

const MyChildBlock = ( props ) => {
	const { context } = props;

	return <div>Post ID: { context.postId }, Type: { context.postType }</div>;
};

Где применяется

  • Блоки комментариев (core/comment-*) получают данные о текущем комментарии от core/comment-template.
  • Блоки внутри Query Loop используют queryId, postId и другие параметры, чтобы отобразить данные конкретного поста.

Особенности

  • Работает только с контекстом, который был заранее объявлен через providesContext у предков.
  • Значения доступны только в рамках дерева блоков — нельзя «подтянуть» контекст из совершенно другого места.
  • Если родитель не предоставляет нужный контекст, то в props.context значение будет undefined.

Подробнее: https://developer.wordpress.org/block-editor/reference-guides/block-api/block-context/

По умолчанию: —

version(строка)

Версия блока (например, 1.0.3). Это чисто служебное поле.

  • Оно нигде не отображается в UI редактора.
  • Используется WordPress внутри, в основном для кеширования и инвалидирования ассетов (скриптов и стилей блока).
  • Если указана версия — она добавляется как query string (?ver=1.0.3) при подключении CSS/JS блока.
  • Если не указать — WP автоматически подставит версию самой WordPress.

По умолчанию: —

__experimental(строка/логический)

Экспериментальный флаг.

Это параметры котоыре начинаются с префикса __experimental. Поведение и сам ключ могут измениться без сохранения обратной совместимости.

Такие параметры практически не документированы. По возможности лучше не использовать.

Список всех найденных эксперементальных свойств в ядре WP 6.9 - из папки wp-includes/blocks:

supports

	__experimentalOnEnter: true        // core/group
	__experimentalOnMerge: true        // core/group
	__experimentalSettings: true       // core/group
	__experimentalSlashInserter: true  // core/navigation-link
	__experimentalToolbar: false       // core/page-list-item
	__experimentalSelector: "p",       // core/paragraph
	__unstablePasteTextInline: true,   // core/paragraph

	__experimentalBorder: {
		__experimentalSkipSerialization: true
		radius: true
		color: true
		width: true
		style: true
		__experimentalDefaultControls: {
			radius: true
			color: true
			style: true
			width: true
		}
	}

	__experimentalExposeControlsToChildren: true

	spacing
		__experimentalSkipSerialization: [ "blockGap" ]
		__experimentalDefaultControls: {
			margin: false
			padding: false
			blockGap: true
		}
		blockGap
			__experimentalDefault: "2em"

	typography
		__experimentalFontFamily: true
		__experimentalFontWeight: true
		__experimentalFontStyle: true
		__experimentalTextTransform: true
		__experimentalTextDecoration: true
		__experimentalLetterSpacing: true
		__experimentalWritingMode: true
		__experimentalDefaultControls: {
			fontSize: true
			__experimentalFontFamily: true,
			__experimentalFontStyle: true,
			__experimentalFontWeight: true
		}
		__experimentalSkipSerialization: [
			"fontSize",
			"lineHeight",
			"fontFamily",
			"fontWeight",
			"fontStyle",
			"textTransform",
			"textDecoration",
			"letterSpacing"
		]

	color
		__experimentalDuotone: "img"   ||   "> .wp-block-cover__image-background, > .wp-block-cover__video-background"
		__experimentalSkipSerialization: true   ||   [ "text", "background" ]    ||     [ "gradients" ]
		__experimentalSelector: "table, th"
		__experimentalDefaultControls: {
			"background": true
			"text": true
			"link": true
		}

	shadow:
		__experimentalSkipSerialization: true
supports(объект)
Включение возможностей редактора и стилей. Подключает UI и расширяет style/атрибуты.
По умолчанию: —
supports.anchor(логический)

Включает контрол добалвяени HTML ANCHOR в разделе Advansed. Обычно этот якорь исползуется как id="" атрибут тега, который сохраняется в контенте при сохранении блока.

"supports": {
  "anchor": true,
}

Если этот параметр включается для кастомного блока, HTML которого не сохраняется в контент, то также нужно указать anchor в качестве атрибута блока, чтобы он сохранился в json данные блока:

"attributes": {
  "anchor": { "type": "string" },
}

Затем в файле рендера блока этот атрибут можно получить как обычно:

$attributes['anchor']

По умолчанию: false

supports.align(логический/массив)

Контролы выравнивания (wide|full|left|center|right). Отвечает за поддержку выравнивания блока в редакторе.

По умолчанию: false

Возможные варианты:

  • false — выравнивание отключено (по умолчанию).
  • true — включены все варианты выравнивания, которые разрешает тема: wide|full|left|center|right.
  • ["left","center","right"] — явно перечислены допустимые варианты.
  • ["wide","full"] — разрешить только широкую и полную ширину.

Пример:

{
  "name": "my-plugin/banner",
  "title": "Banner",
  "supports": {
	"align": [ "left", "center", "right" ]
  }
}

В редакторе блок получит кнопки для выбора выравнивания, но не будет доступен wide и full.

align приоритетнее alignWide. Так если align = ["wide","full"] и alignWide = false, то кнопки все равно будут работаь.

supports.alignWide(логический)

Управляет поддержкой широкого выравнивания для блока.

По умолчанию: true

Если в теме включена поддержка широкого и полного выравнивания add_theme_support( 'align-wide' ), то редактор покажет кнопки:

Чтобы отключить такую возможность для конкретного блока, нужно задать:

{
	"supports": {
	  "alignWide": false
	}
}

Тогда даже при активной поддержке в теме блок не сможет использовать alignwide (широкая ширина).

Пример: Оставим только стандартные выравнивания

{
  "name": "my-plugin/custom-block",
  "title": "Custom Block",
  "supports": {
	"align": [ "left", "right", "center" ],
	"alignWide": false
  }
}
  • align управляет наличием кнопок выравнивания: left, right, center, wide, full.
  • alignWide — отдельный флажок, чтобы запретить широкую ширину у блока, даже если тема её поддерживает.
supports.ariaLabel(логический)

Разрешает атрибут aria-label для блока, но без отображения отдельного поля в UI редактора.

  • Если true → Gutenberg добавит поддержку aria-label к блоку. Атрибут можно задать вручную (например через setAttribute или в save), но в интерфейсе редактора отдельного поля для него не появится.

  • Если false (по умолчанию) → блок не поддерживает aria-label.

Используется для доступности (accessibility): можно добавить текстовое описание блока для скринридеров, не нагружая UI редактора.

По умолчанию: false

supports.className(логический)

Определяет, будет ли WordPress автоматически добавлять CSS-класс блока wp-block-* к корневому HTML-элементу при сохранении.

{
  "supports": {
	"className": false
  }
}

Этот класс обычно используется темами и плагинами как стабильная точка для стилизации блока.

По умолчанию: true

Когда отключать

  • Если блок не имеет одного корневого контейнера.
  • Если разметка полностью контролируется вручную и стандартный класс мешает.
  • Если блок рендерится динамически и класс не нужен по архитектурным причинам.

Важно понимать

  • supports.className — отвечает только за автоматический класс wp-block-*.
  • supports.customClassName — отвечает за UI-поле «Дополнительный CSS-класс» в инспекторе.
  • Это разные механизмы, их часто путают.
supports.color(объект)
Поддержка цветовых свойств.
По умолчанию: —
supports.color.background(логический)
UI для фонового цвета, добавляет backgroundColor и style.
По умолчанию: true
supports.color.gradients(логический)
UI для градиентов, добавляет gradient и style.
По умолчанию: false

UI для цвета ссылок. Разрешает/запрещает панель выбора цвета ссылок (link color).

Используется для любых блоков, у которых есть текст с потенциальными <a> внутри:

  • paragraph
  • heading
  • group
  • columns
  • custom blocks со своими richText полями

Если включено, Гутенберг начинает применять к блоку CSS custom property:
--wp--style--color--link

И этот цвет влияет только на <a> внутри блока, а не на обычный текст.

По умолчанию: false

supports.color.text(логический)
UI для цвета текста, добавляет textColor и style.
По умолчанию: true
supports.color.heading(логический)
UI для цвета заголовков, добавляет style.
По умолчанию: false
supports.color.button(логический)
UI для цветов кнопок, добавляет style.
По умолчанию: false
supports.color.enableContrastChecker(логический)
Показывать виджет проверки контраста.
По умолчанию: true
supports.customClassName(логический)
Поле кастомного класса в Advanced.
По умолчанию: true
supports.dimensions(объект)
Поддержка размеров.
По умолчанию: —
supports.dimensions.aspectRatio(логический)
UI для соотношения сторон.
По умолчанию: false
supports.dimensions.minHeight(логический)
UI для минимальной высоты.
По умолчанию: false
supports.dimensions.width(логический) (WP 7.0)

Включает поддержку CSS-свойства width.

Пример в block.json:

{
	"supports": {
		"dimensions": {
			"width": true
		}
	}
}

После включения у блока появляется поле Width в панели Dimensions в инспекторе блока. Также ширину можно настраивать через Site Editor в Styles > Blocks > Block Name.

Значение сохраняется в стилях блока и применяется как обычный CSS width.

Пример значения в theme.json:

{
	"styles": {
		"blocks": {
			"my-plugin/card": {
				"dimensions": {
					"width": "300px"
				}
			}
		}
	}
}

Если пользователь задаст ширину прямо в редакторе, это значение переопределит дефолт из theme.json.

По умолчанию: false

supports.dimensions.height(логический) (WP 7.0)

Включает поддержку CSS-свойства height.

Пример в block.json:

{
	"supports": {
		"dimensions": {
			"height": true
		}
	}
}

После включения у блока появляется поле Height в панели Dimensions в инспекторе блока.

Также высоту можно задавать через Global Styles / theme.json. Это новое block support API в WordPress 7.0.

Пример значения в theme.json:

{
	"styles": {
		"blocks": {
			"my-plugin/card": {
				"dimensions": {
					"height": "400px"
				}
			}
		}
	}
}

Можно включить сразу width и height:

{
	"supports": {
		"dimensions": {
			"width": true,
			"height": true
		}
	}
}

Значение, заданное пользователем в редакторе, переопределяет дефолт из theme.json, как и другие block supports.

По умолчанию: false

supports.filter(объект)
Поддержка CSS-фильтров.
По умолчанию: —
supports.filter.duotone(логический)
Дуотон-фильтр.
По умолчанию: false
supports.background(объект)
Поддержка фоновых свойств.
По умолчанию: —
supports.background.backgroundImage(логический)
UI для фонового изображения.
По умолчанию: false
supports.background.backgroundSize(логический)
UI для size/position/repeat фона.
По умолчанию: false
supports.html(логический)

Разрешить редактирование HTML блока.

По умолчанию: true

supports.inserter(логический)
Показывать блок в UI (вставщик, трансформы, Style Book).
По умолчанию: true
supports.renaming(логический)
Разрешить переименование блока пользователем.
По умолчанию: true
supports.layout(логический/объект)

Включает и настраивает Layout API — управление тем, как располагаются inner blocks (flow / flex / grid / constrained) и какие контролы показываются в редакторе.

Используется только для контейнерных блоков (блоков с InnerBlocks).

По умолчанию: false

"supports": {
  "layout": true
}

  • false (по умолчанию)

    • Layout API отключен
    • Блок не управляет размещением inner blocks
    • Не добавляются layout-классы (is-layout-*)
    • Нет UI-контролов в сайдбаре

  • true

    • Включает layout flow
    • Эквивалентно: type: "flow"
    • Используется, если нужен стандартный вертикальный поток без настроек

Расширенная конфигурация (object):

"supports": {
  "layout": {
	"default": { ... },
	"allowSwitching": false,
	"allowEditing": true,
	"allowInheriting": true,
	"allowSizingOnChildren": false,
	"allowVerticalAlignment": true,
	"allowJustification": true,
	"allowOrientation": true,
	"allowCustomContentAndWideSize": true
  }
}

Что происходит технически:

  • WordPress добавляет классы:

    • is-layout-flow
    • is-layout-flex
    • is-layout-grid
    • is-layout-constrained
  • Генерируется CSS через theme.json Layout Styles
  • Настройки сохраняются в attributes.layout
  • Layout наследуется вложенными блоками (если разрешено)

Когда использовать

  • true

    • Простой контейнер без UI

  • layout.default.type = constrained

    • FSE-контейнеры, секции, шаблоны

  • layout.default.type = flex

    • Кнопки, навигация, карточки
  • layout.default.type = grid
    • Галереи, списки карточек

UI-флаги: allow***

Управляют видимостью контролов в редакторе.

  • allowSwitching

    • Разрешает переключение между flow / flex / grid / constrained
    • По умолчанию: false

  • allowEditing

    • Показывать/скрывать layout-настройки в сайдбаре
    • По умолчанию: true

  • allowInheriting (только flow)

    • Контрол “Inner blocks use content width”
    • По умолчанию: true

  • allowSizingOnChildren (только flex)

    • Контролы Fit / Fill / Fixed у дочерних блоков
    • По умолчанию: false

  • allowVerticalAlignment (только flex)

    • Vertical alignment в toolbar
    • По умолчанию: true

  • allowJustification

    • Flex: toolbar + sidebar
    • Constrained: sidebar
    • По умолчанию: true

  • allowOrientation (только flex)

    • Переключатель horizontal / vertical
    • По умолчанию: true
  • allowCustomContentAndWideSize (только constrained)
    • Контроль кастомных contentSize / wideSize
    • По умолчанию: true
supports.layout.default(объект)

Определяет тип layout по умолчанию и его стартовые настройки.

type — тип layout:

  • constrained

    • Контент ограничен шириной (contentSize, wideSize)
    • Используется в core/group, core/post-content

  • flex

    • Flexbox-раскладка
    • Используется в core/buttons, core/navigation
  • grid
    • CSS Grid
    • Используется в core/gallery
"default": {
  "type": "flex"
}

Свойства default (зависят от типа)

Для constrained

  • contentSize — ширина контента
  • wideSize — ширина alignwide
"default": {
  "type": "constrained",
  "contentSize": "720px",
  "wideSize": "1200px"
}

Для flex

  • orientation — horizontal | vertical
  • justifyContent — left | center | right | space-between | stretch
  • verticalAlignment — top | center | bottom | space-between | stretch
  • flexWrap — wrap | nowrap
"default": {
  "type": "flex",
  "orientation": "horizontal",
  "justifyContent": "space-between",
  "flexWrap": "wrap"
}

Для grid

  • columnCount — количество колонок
  • minimumColumnWidth — минимальная ширина колонки
"default": {
  "type": "grid",
  "minimumColumnWidth": "240px"
}
supports.layout.default.type(строка)
Тип layout: constrained|grid|flex.
По умолчанию: —
supports.layout.default.contentSize(строка)
Ширина контента детей.
По умолчанию: —
supports.layout.default.wideSize(строка)
Ширина для alignwide детей.
По умолчанию: —
supports.layout.default.orientation(строка)

Ориентация: horizontal|vertical.

По умолчанию: —

supports.layout.default.flexWrap(строка)
Перенос: wrap|nowrap.
По умолчанию: —
supports.layout.default.justifyContent(строка)
Выравнивание: right|center|space-between|left|stretch.
По умолчанию: —
supports.layout.default.verticalAlignment(строка)
Вертикальное выравнивание: top|center|bottom|space-between|stretch.
По умолчанию: —
supports.layout.default.minimumColumnWidth(строка)
Мин. ширина колонки.
По умолчанию: —
supports.layout.default.columnCount(число)
Количество колонок.
По умолчанию: —
supports.layout.allowSwitching(bool)

Переключатель типов layout.

По умолчанию: false

supports.layout.allowEditing(bool)
Показывать контролы layout в сайдбаре.
По умолчанию: true
supports.layout.allowInheriting(bool)
Только для flow: показывать «Inner blocks use content width».
По умолчанию: true
supports.layout.allowSizingOnChildren(bool)

Управляет контролами размеров дочерних блоков внутри контейнера с layout flex.

По умолчанию: false

{
  "supports": {
	"layout": {
	  "allowSizingOnChildren": true
	}
  }
}

Что делает:

  • Включает/Отключает UI-контролы Fit / Fill / Fixed у всех дочерних блоков внутри flex-контейнера.
  • Эти контролы управляют тем, как каждый вложенный блок ведёт себя по ширине/размеру внутри flex-контекста.

Важные замечания:

  • Работает только если layout = flex. Для constrained и grid игнорируется.
  • Контролы появляются на дочерних блоках.
  • Аналогичное поведение можно увидеть у core/group при layout flex.
supports.layout.allowVerticalAlignment(bool)

Добавляет контролы вертикального выравнивание. Только для flex.

"layout": {
  "default": { "type": "flex" },
  "allowVerticalAlignment": true
},

По умолчанию: true

supports.layout.allowJustification(bool)
flex и constrained: контролы Justify.
По умолчанию: true
supports.layout.allowOrientation(bool)

Только для flex. Отвечает за контролы ориентации: horizontal|vertical.

По умолчанию: true

supports.layout.allowWrap(bool) (WP 6.9)

Только для flex. Отвечает за контрол "wrap" параметра flex модели.

По умолчанию: true

supports.layout.allowCustomContentAndWideSize(bool)
Только для constrained: кастомные content/wide size.
По умолчанию: true
supports.listView(bool) (WP 7.0)

Включает отдельную вкладку List View в sidebar-инспекторе блока в админке, в редакторе.

Эта вкладка показывает внутреннюю структуру блока и позволяет удобнее работать с его дочерними блоками.

{
	"supports": {
		"listView": true
	}
}

Параметр полезен для контейнерных блоков, которые содержат список вложенных блоков. Например:

  • buttons/button
  • list/list-item
  • cards/card
  • tabs/tab
  • accordion/accordion-item
  • gallery/image

Рекомендуется включать listView для блоков, где пользователь часто работает с набором дочерних элементов. Это особенно удобно в паттернах, потому что List View отображается прямо в контексте выбранного блока, а не только в общем дереве редактора.

Пример для кастомного блока:

{
	"apiVersion": 3,
	"name": "my-plugin/cards",
	"title": "Cards",
	"supports": {
		"listView": true
	}
}
supports.multiple(bool)
Разрешить несколько экземпляров блока в записи.
По умолчанию: true
supports.reusable(bool)
Разрешить преобразование в повторно используемый блок.
По умолчанию: true
supports.lock(bool)
Разрешить пользователю менять состояние блокировки.
По умолчанию: true
supports.position(объект)
Поддержка позиционирования.
По умолчанию: —
supports.position.sticky(bool)
Позиция sticky относительно родителя.
По умолчанию: false
supports.spacing(объект)
Поддержка отступов.
По умолчанию: —
supports.spacing.margin(bool/массив)
UI для margin. Массив: стороны top|right|left|bottom или оси vertical|horizontal.
По умолчанию: —
supports.spacing.padding(bool/массив)
UI для padding. Массив: стороны или оси.
По умолчанию: —
supports.shadow(bool/объект)
Поддержка теней (box-shadow).
По умолчанию: false
supports.typography(объект)
Поддержка типографики.
По умолчанию: —
supports.typography.fontSize(bool)
UI для font-size, добавляет fontSize и style.
По умолчанию: false
supports.typography.fitText(bool) (WP 6.9)

Включает для блока настройку Fit text в панели Typography.

Настройка позволяет автоматически подбирать размер шрифта так, чтобы текст помещался в доступную ширину контейнера.

{
	"supports": {
		"typography": {
			"fitText": true
		}
	}
}

В разметке блока появляется класс:

<p class="has-fit-text">Text</p>

или для заголовка:

<h2 class="wp-block-heading has-fit-text">Text</h2>

В ядре она включена для core/paragraph и core/heading.

В редакторе настройка находится в боковой панели блока: Block Settings > Typography > Fit text.

Как это работает.

На фронтенде WordPress проверяет атрибут fitText. Если он включён, подключается JS-модуль @wordpress/block-editor/utils/fit-text-frontend, а в разметку добавляются data-атрибуты Interactivity API. Этот модуль рассчитывает оптимальный font-size и записывает его как inline style. При изменении размера контейнера пересчёт выполняется через ResizeObserver.

  • fitText не задаёт фиксированный CSS-размер шрифта.
  • Размер рассчитывается динамически через JavaScript.
  • Обычный fontSize при включении fitText сбрасывается.
  • Лучше использовать для коротких текстов, крупных заголовков, hero-секций и декоративной типографики.
  • Для длинных абзацев это обычно плохой вариант.
  • Первоначально обсуждались отдельные variations вроде Stretchy Paragraph и Stretchy Heading, но позже их убрали, чтобы не засорять inserter. Осталась именно настройка в Typography panel.

Подробнее: https://github.com/WordPress/gutenberg/pull/71904

supports.typography.lineHeight(bool)
UI для line-height, хранится в style.
По умолчанию: false
supports.typography.textAlign(bool/массив)
Тулбар выравнивания текста (left|center|right).
По умолчанию: false
supports.interactivity(bool/объект)
Использование Interactivity API.
По умолчанию: false (если bool)
supports.interactivity.clientNavigation(bool)
Совместимость с клиентской навигацией IA.
По умолчанию: false
supports.interactivity.interactive(bool)
Есть ли IA-директивы.
По умолчанию: false
supports.splitting(bool)
Возможность split по Enter/вставке.
По умолчанию: false
supports.__experimentalOnEnter

Обработка Enter внутри блока (выход/разделение контейнера, не точно).

Где встречается: core/group, core/columns

Назначение (не точно): включает для блока специальную обработку клавиши Enter — редактор по-особому решает, что делать при нажатии Enter в последнем RichText внутри блока (например, выйти из контейнера и создать параграф после блока, а не внутри него). Используется ядром, чтобы упростить «выход» из сложных контейнеров (Group/Columns и т.п.).

Пример:

  • В блоке-контейнере (условный my-plugin/container) можно задать:
    "supports": { "__experimentalOnEnter": true }, чтобы при нажатии Enter в конце последнего параграфа курсор выходил за пределы контейнера и создавался новый core/paragraph.

По умолчанию: false

supports.__experimentalOnMerge

Логика слияния блока с соседними при Backspace/Delete (не точно).

Где встречается: core/group

Назначение (не точно): включает кастомное поведение при «слиянии» блоков — обычно когда курсор в начале блока и пользователь жмёт Backspace/Delete, редактор пытается слить блок с предыдущим. Для контейнеров этот флаг позволяет им перехватить событие и, например, переместить соседний блок внутрь/наружу контейнера вместо стандартного удаления/слияния.

Пример:

  • Для пользовательского блока-обёртки можно включить:
    "supports": { "__experimentalOnMerge": true }, чтобы при Backspace в начале блока предыдущий параграф не удалялся, а, например, перемещался внутрь контейнера.

По умолчанию: false

supports.__experimentalSettings

Внутренний флаг Gutenberg для включения дополнительных настроек/панелей блока (не точно).

Где встречается: у ряда core-блоков, например core/group.

Назначение (не точно): Служебное свойство, которое помечает блок как использующий дополнительные возможности редактора (панели настроек, опции, UI). Конкретный набор влияний не документирован и может отличаться между версиями Gutenberg. Рекомендуется не использовать в пользовательских блоках без необходимости, так как API нестабильный и ориентирован на внутренние нужды ядра (не точно).

Пример:

  • В некоторых core-блоках можно увидеть:
    "supports": { "__experimentalSettings": true }, что включает для них расширенные панели в инспекторе (точный состав панелей меняется от версии к версии, не точно).

По умолчанию: false

supports.__experimentalSlashInserter

Включает slash-вставку (/), показывающую список блоков/команд прямо в тексте блока.

Где встречается: текстовые блоки (core/heading, и др.).

Назначение: Делает блок участником механики «slash inserter»: при вводе символа «/» в RichText-поле блока показывается всплывающий список блоков и команд (как в параграфе).

Полезно для текстовых блоков, которые должны ощущаться как стандартный параграф/заголовок.

Исторически также использовался для включения автодополнения ссылок по [[…]], но сейчас это поведение в основном глобальное.

Пример:

  • Для текстового блока my-plugin/lead-paragraph:
    "supports": { "__experimentalSlashInserter": true } — позволяет пользователю, не выходя из блока, набрать /image и вставить core/image прямо из подсказки.

По умолчанию: false

supports.__experimentalToolbar

Управляет показом стандартного тулбара блока (можно скрыть для внутренних блоков).

Назначение (не точно): управляет показом стандартного toolbar блока (панель с иконками над блоком) для отдельных «внутренних»/служебных блоков.

Для таких блоков, как core/page-list-item означает «не показывать собственный тулбар, управлять блоком через родительский (например, core/page-list)».

Рекомендации:

  • Использовать только если вы создаёте технический внутренний блок, который не должен иметь свой интерфейс редактирования (toolbar) напрямую.

Пример:

  • Внутренний элемент-блок, который используется только внутри родительского блока (например, пункт меню в кастомном навигационном блоке), можно объявить так:
    "supports": { "__experimentalToolbar": false }, чтобы управление шло только через тулбар родителя.

По умолчанию: true (по смыслу; ядро явно ставит false у некоторых внутренних блоков)

supports.__experimentalSelector

Переопределяет CSS-селектор, к которому применяются глобальные стили (theme.json) для блока.

Пример:

  • ".my-custom-classname"
  • "p"
  • ".wp-block-button .wp-block-button__link"

Назначение: Позволяет указать альтернативный CSS-селектор, к которому будут применяться глобальные стили (theme.json / Global Styles) для этого блока.

По умолчанию WordPress использует селектор вида .wp-block-<имя-блока>. Если блок не использует такую обёртку или нужно стилизовать внутренний элемент (например, сам <form> или <a> в кнопке), можно использовать это свойство.

Типичные случаи использования:

  • Блок не рендерит стандартный класс .wp-block-…, но вы хотите, чтобы на него работали глобальные стили.
  • Нужно, чтобы глобальные стили применялись не к wrapper-div, а к «настоящему» элементу, например:
    • Form block: "__experimentalSelector": "form"
    • Button-link: "__experimentalSelector": ".wp-block-button .wp-block-button__link"

Особенности:

  • Для корректной работы глобальных стилей блок должен быть зарегистрирован через block.json через register_block_type_from_metadata(), иначе информация о селекторе недоступна PHP-части.

  • Флаг по-прежнему помечен как experimental, но считается относительно зрелым и активно используется в core-блоках.

Риски:

  • Неправильно выбранный селектор может затронуть не только сам блок, но и вложенные элементы (особенно для контейнеров вроде <form>).

Пример:

  • Для блока-формы, который рендерит только <form class="my-form">…</form> без обёртки .wp-block-*, можно указать:
    "supports": { "__experimentalSelector": "form.my-form" }, чтобы глобальные стили цвета/типографики из theme.json применялись именно к тегу <form>.

По умолчанию: используется стандартный селектор .wp-block-<block-name>

supports.__unstablePasteTextInline

Особая обработка вставки текста как inline-контента без разбиения на блоки (не точно).

Где встречается: core/paragraph, core/heading и др. текстовые блоки с RichText.

Назначение (не точно):

  • Включает особый режим обработки вставки текста (paste) в RichText поля блока:

    • вставка обрабатывается как «inline-текст» без дробления/создания новых блоков,

    • сложные вставки (многострочный текст, HTML) упрощаются до текста и вставляются в текущую позицию курсора.
  • Используется ядром для того, чтобы такие блоки вели себя более «предсказуемо» при вставке текста из буфера (заголовки, абзацы и т.п.).

Статус: Свойство помечено как __unstable, то есть оно ещё менее стабильно, чем __experimental.

В кастомных блоках лучше задавать его только если вы точно воспроизводите поведение core-текстовых блоков и готовы к возможным изменениям API.

Пример:

  • Для пользовательского текстового блока, основанного на RichText:
    "supports": { "__unstablePasteTextInline": true } — вставка из буфера (например, из Word/Google Docs) будет преобразована в простой текст и вставлена в текущий блок, не создавая новых блоков.

По умолчанию: false

supports.__experimentalExposeControlsToChildren

Делится панелью настроек контейнерного блока с его дочерними блоками.

Флаг используется у контейнерных блоков с InnerBlocks (например, группы кнопок), чтобы часть настроек родителя (layout, выравнивание, отступы и т.п.) оставалась доступной, даже когда выделен внутренний блок.

При включении этого свойства инспектор может продолжать показывать/применять некоторые контролы родительского блока, когда пользователь кликает по дочерним блокам, что облегчает работу с составными блоками.

Точное поведение и набор «расшариваемых» контролов зависят от версии редактора и могут меняться.

Пример:

{
	"name": "my-plugin/buttons-group",
	"supports": {
		"__experimentalExposeControlsToChildren": true,
		"spacing": {
			"blockGap": true,
			"margin": [ "top", "bottom" ]
		}
	}
}

По умолчанию: false

supports.__experimentalBorder

Включает поддержку рамки у блока (цвет, толщина, стиль, скругление) и настраивает видимые контролы.

При включении в инспекторе блока появляются соответствующие панели, а выбранные значения попадают в style-атрибуты (style.border.*) и/или CSS-классы. Используется многими core-блоками.

Основные ключи объекта:

  • radius — включает контрол скругления углов рамки.
  • color — включает выбор цвета рамки.
  • width — включает контрол толщины рамки.

  • style — включает выбор типа линии рамки (solid, dashed, dotted и т.п.).

  • __experimentalDefaultControls — объект с теми же ключами (radius, color, width, style), который управляет тем, какие контролы показывать активными по умолчанию в UI (например, можно включить только радиус).

  • __experimentalSkipSerialization — если true, стили рамки не будут автоматически сериализованы на wrapper-элемент блока. Значения по-прежнему будут храниться в атрибутах стилей, и их можно применить вручную через useBorderProps в JS или get_block_wrapper_attributes() в PHP к любому нужному элементу.

Дополнительно:

  • Если какой-то из ключей (radius, color, width, style) не указан соответствующий контрол скрывается.
  • Если тема не включает поддержку рамок/appearance tools (например, через theme.json или add_theme_support( 'border' )), UI может быть скрыт, даже при включённом support в блоке.
  • В новых версиях WordPress планируется перенос этого support в стабильный ключ border (без префикса), при этом старый __experimentalBorder ещё какое-то время будет поддерживаться как алиас.

Пример:

{
	"name": "my-plugin/box",
	"supports": {
		"__experimentalBorder": {
			"__experimentalSkipSerialization": true,
			"radius": true,
			"color": true,
			"width": true,
			"style": true,
			"__experimentalDefaultControls": {
				"radius": true,
				"color": true,
				"style": true,
				"width": true
			}
		}
	}
}

По умолчанию: false - Панель рамки отключена и все вложенные свойства тоже.

selectors(объект)

Позволяет блоку настраивать CSS-селектор, на элементе которого генерируются стили.

Можно переопределять CSS-селекторы на трёх уровнях:

  • Корневом (root).
  • Уровне «возможности» (feature).
  • Уровне «подсвойства» (subfeature).

Корневой селектор (root selector)

Корневой селектор — это основной CSS-селектор блока.

Все блоки должны иметь основной селектор, под которым будут собраны их стилевые декларации. Если он не задан, по умолчанию используется селектор .wp-block-<name>:

{
  ...
  "selectors": {
	"root": ".my-custom-block-selector"
  }
}

Селекторы возможностей (feature selectors)

Селекторы «возможностей» относятся к стилям для block supports, например: border, color, typography и т.п.

Блок может захотеть применять стили отдельных возможностей к разным элементам внутри себя. Например, цвета — к обёртке блока, а типографику — только к внутреннему заголовку.

Пример

{
  ...
  "selectors": {
	"root": ".my-custom-block-selector",
	"color": ".my-custom-block-selector",
	"typography": ".my-custom-block-selector > h2"
  }
}

Селекторы подсвойств (subfeature selectors)

Эти селекторы относятся к отдельным стилям, предоставляемым конкретной «возможностью» блока, например background-color.

Для подсвойства можно сгенерировать стили под его собственным уникальным селектором. Это особенно полезно, когда одно из подсвойств не может быть применено к тому же элементу, что и другие подсвойства той же «возможности».

Отличный пример — text-decoration. Браузеры рендерят это свойство по-разному, из-за чего его трудно переопределять, если оно добавлено на элемент-обёртку. Назначив text-decoration отдельный селектор, можно таргетировать именно те элементы, к которым его нужно применить.

{
  ...
  "selectors": {
	"root": ".my-custom-block-selector",
	"color": ".my-custom-block-selector",
	"typography": {
	  "root": ".my-custom-block-selector > h2",
	  "text-decoration": ".my-custom-block-selector > h2 span"
	}
  }
}

Сокращённая запись (shorthand)

Вместо того чтобы указывать селектор для каждого подсвойства, можно задать один селектор строкой для соответствующей «возможности». Так сделано для color в приведённых выше примерах.

Фолбэки (Fallbacks)

Если селектор для конкретной «возможности» не настроен, он откатывается к корневому селектору блока. Аналогично, если для подсвойства не задан кастомный селектор, используется селектор родительской «возможности», а при его отсутствии — корневой селектор блока.

Вместо повторения одного и того же селектора для множества подсвойств можно указать общий селектор как root у родительской «возможности», а уникальные селекторы определить только для отличающихся подсвойств.

Пример:

{
  ...
  "selectors": {
	"root": ".my-custom-block-selector",
	"color": {
	  "text": ".my-custom-block-selector p"
	},
	"typography": {
	  "root": ".my-custom-block-selector > h2",
	  "text-decoration": ".my-custom-block-selector > h2 span"
	}
  }
}

В примере выше color.background-color явно не задан. Так как для color тоже не определён root, то color.background-color будет сгенерирован под корневым селектором блока — .my-custom-block-selector.

Для подсвойства вроде typography.font-size будет использован фолбэк к селектору родительской «возможности», поскольку он задан — .my-custom-block-selector > h2.

По умолчанию: —

selectors.root(строка)
Основной CSS-класс блока, заменяет .wp-block-*.
По умолчанию: —
selectors.border(строка/объект)
Селекторы для границ: root|color|radius|style|width.
По умолчанию: —
selectors.color(строка/объект)
Селекторы для цвета: root|text|background.
По умолчанию: —
selectors.dimensions(строка/объект)
Селекторы размеров: root|aspectRatio|minHeight.
По умолчанию: —
selectors.spacing(строка/объект)
Селекторы отступов: root|blockGap|padding|margin.
По умолчанию: —
selectors.typography(строка/объект)
Селекторы типографики: root|fontFamily|fontSize|fontStyle|fontWeight|lineHeight|letterSpacing|textDecoration|textTransform.
По умолчанию: —
styles(массив)

Позволяет задать альтернативные стили для блока.

При выборе пользователем конкретного стиля, к обёртке блока добавляется CSS-класс is-style-{name}, который можно стилизовать в CSS.

Каждый объект внутри массива описывает отдельный стиль и может содержать:

  • name(string, обязательно)
    Уникальное машинное имя стиля (используется в классе CSS).

  • label(string, обязательно)
    Читаемое название стиля, отображается в UI. Может быть локализовано.

  • isDefault(boolean)
    Если true, стиль будет выбран по умолчанию.
    По умолчанию: false

Также эти вариации стилей можно настроить в style в админке:

Пример:

{
  "styles": [
	{ "name": "default", "label": "Default", "isDefault": true },
	{ "name": "outline", "label": "Outline" },
	{ "name": "fancy",   "label": "Fancy Style" }
  ]
}

В результате при выборе стиля outline блок получит класс:

<div class="wp-block-my-block is-style-outline"></div>

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

  • Тема или плагин должны определить CSS для соответствующих классов.
  • Полезно для упрощённого переключения оформления (например, кнопки: «заполненная» или «обводка»).

Можно регистрировать стили и для core-блоков, добавляя свои варианты:

Через PHP:

register_block_style( 'core/image', [
	'name'         => 'outline',
	'label'        => 'Outline',
	'inline_style' => <<<'CSS'
		.wp-block-image.is-style-shadowed img {
			box-shadow: 0 8px 24px rgba(0,0,0,.2);
		}
		CSS,
] );

Через JS:

// В вашем editor.js, который грузится только в редакторе.
wp.domReady( () => {
	wp.blocks.registerBlockStyle( 'core/paragraph', {
		name: 'outline',
		label: 'Outline'
	} );

	// Удалить встроенный стиль:
	// wp.blocks.unregisterBlockStyle( 'core/image', 'rounded' );
} );

По умолчанию: — (пустой массив)

example(объект)
Данные предпросмотра для Inspector Help.
По умолчанию: —
example.viewportWidth(число)
Ширина iframe предпросмотра.
По умолчанию: 1200
example.attributes(объект)
Атрибуты для превью.
По умолчанию: —
example.innerBlocks(массив)
Вложенные блоки для превью.
По умолчанию: —
variations(строка/массив)
Вариации блока. Путь к PHP, возвращающему массив, или массив объектов.
По умолчанию: —
variations[].name(строка) (обязательный)
Машиночитаемое имя вариации.
По умолчанию: —
variations[].title(строка) (обязательный)
Заголовок вариации.
По умолчанию: —
variations[].description(строка)
Описание вариации.
По умолчанию: —
variations[].category(строка)
Категория вариации.
По умолчанию: —
variations[].icon(строка)
Иконка вариации.
По умолчанию: —
variations[].isDefault(bool)
Сделать вариацию по умолчанию.
По умолчанию: false
variations[].attributes(объект)
Переопределения атрибутов.
По умолчанию: —
variations[].innerBlocks(массив)
Начальная конфигурация вложенных блоков.
По умолчанию: —
variations[].example(объект)
Данные предпросмотра для вариации.
По умолчанию: —
variations[].scope(массив)
Где доступна вариация: inserter|block|transform.
По умолчанию: ["inserter","block"]
variations[].keywords(массив)
Ключевые слова поиска вариации.
По умолчанию: —
variations[].isActive(массив)
Список атрибутов для сравнения активности вариации.
По умолчанию: —