title: >- Анатомия block.json (Block API v3), коллекции метаданных и архитектура современного блока description: >- Глубокий разбор спецификации block.json в WordPress 7.0+ «Armstrong» (Block API v3): изолированный iframe-редактор, ES-модули фронтенда (viewScriptModule), контекстное дерево (providesContext / usesContext), компиляция манифеста wp_register_block_metadata_collection() и условная загрузка ассетов. module: gutenberg-blocks order: 1 difficulty: intermediate estimatedTime: 35 мин topics:
В ранних версиях Gutenberg регистрация блока была разорвана между двумя мирами: часть конфигурации дублировалась в JavaScript внутри registerBlockType(), а часть — в PHP. Это приводило к рассинхронизации схемы атрибутов при серверном рендеринге (SSR), невозможности проанализировать зависимости блока без запуска JS-бандла и принудительной загрузке сотен килобайт CSS и JS на каждой странице сайта.
В WordPress 7.0+ («Armstrong») единственным источником истины (Single Source of Truth) для любого блока является декларативный манифест block.json спецификации Block API v3 ("apiVersion": 3). Этот JSON-файл одновременно управляет четырьмя подсистемами ядра:
apiVersion: 3): гарантирует, что стили админки WordPress (wp-admin) никогда не протекут в верстку вашего блока, а сам блок корректно масштабируется в режимах предпросмотра планшета и смартфона.should_load_separate_core_block_assets): ядро парсит post_content перед отправкой ответа и инжектирует на фронтенд (style, viewStyle, viewScriptModule) ровно те CSS/JS-модули, чьи блоки реально присутствуют на текущей странице.providesContext / usesContext): позволяет родительским блокам передавать состояние дочерним блокам на любую глубину без глобальных переменных и prop-drilling.wp_register_block_metadata_collection): устраняет дисковый I/O (file_get_contents + json_decode) при регистрации десятков блоков в крупных дизайн-системах.В архитектуре WordPress 7.0+ декларативный манифест block.json выступает единственным источником истины (Single Source of Truth) жизненного цикла блока. Ядру не требуется загружать и исполнять клиентский бандл React (index.js), чтобы зарегистрировать схему атрибутов, определить правила серверного рендеринга и сформировать граф зависимостей. Прочитав статический манифест, сервер детерминированно выполняет следующие операции:
<!-- wp:agentic/metric-card {...} -->;theme.json v3) через секцию supports;viewScriptModule) для условной загрузки через <script type="module"> на клиенте.ЕДИНЫЙ МАНИФЕСТ: block.json (apiVersion: 3)
│
┌────────────────────────────────┼────────────────────────────────┐
▼ ▼ ▼
┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐
│ КОНТУР PHP (Сервер) │ │ КОНТУР EDITOR (Iframe)│ │ КОНТУР FRONTEND (Edge)│
├───────────────────────┤ ├───────────────────────┤ ├───────────────────────┤
│ • Валидация атрибутов │ │ • editorScript (React)│ │ • style / viewStyle │
│ • render: render.php │ │ • editorStyle │ │ • viewScriptModule │
│ • Передача $context │ │ • Генерация Inspector │ │ (Native ES Modules) │
│ • Условный Enqueue │ │ Controls из supports│ │ • Interactivity API │
└───────────────────────┘ └───────────────────────┘ └───────────────────────┘Сборщик компилирует TypeScript/SCSS в папку build/, генерирует .asset.php с хэшами версий и собирает единый blocks-manifest.php для всей библиотеки.
PHP регистрирует коллекцию через wp_register_block_metadata_collection() и подключает блоки из памяти без чтения десятков JSON-файлов с диска.
В Gutenberg блок монтируется внутрь изолированного <iframe> холста; ядро автоматически строит UI-панели цветов, отступов и границ по декларации supports.
При сохранении поста атрибуты валидируются по схеме attributes и записываются в post_content как структурированный комментарий <!-- wp:namespace/slug -->.
При рендере страницы ядро обнаруживает блок, вызывает render.php и подключает viewScriptModule через нативный Import Map браузера ТОЛЬКО для этой страницы.
Определите строгие типы (string, number, boolean, object, array), дефолтные значения и допустимые списки enum без использования хрупких HTML-селекторов source.
Вместо создания кастомных контролов отступов, рамок и палитр активируйте color, spacing, typography, border и shadow — они автоматически свяжутся с theme.json v3.
Оставьте React-зависимости строго в editorScript, а для фронтенда подключите легковесный нативный ES-модуль через viewScriptModule.
Запустите wp-scripts build --blocks-manifest для генерации единого файла blocks-manifest.php и подключите его через wp_register_block_types_from_metadata_collection().
Какое фундаментальное требование накладывает использование стандарта apiVersion: 3 в block.json на JavaScript-код компонента edit()?
В инженерных проектах Fullstack Agentic Lab грамотное проектирование block.json решает четыре ключевые задачи:
editorScript (тяжёлый React-код админки) и легковесного viewScriptModule (менее 3 КБ), посетитель сайта получает 0 байт кода редактора.supports): вместо написания сотен строк кастомных ColorPalette, BoxControl и FontSizePicker в React, включение "spacing", "color", "typography" и "shadow" в block.json бесплатно подключает нативный UI Gutenberg, синхронизированный с дизайн-токенами theme.json v3."supports": { "interactivity": true } включает клиентскую гидратацию директив data-wp-* и клиентскую навигацию без перезагрузки страницы.wp_register_block_types_from_metadata_collection() с нулевым оверхедом файловой системы.Сравним устаревшую регистрацию блоков (Block API v1/v2 с ручным wp_enqueue_script) и современный стандарт Block API v3 в WordPress 7.0+:
Ниже представлен эталонный производственный артефакт для WordPress 7.0+ и PHP 8.4+, включающий полную спецификацию block.json (apiVersion: 3) для интерактивной карточки телеметрии и серверный загрузчик коллекции метаданных с нулевым дисковым I/O.
<?php
/**
* Plugin Name: Fullstack Agentic Lab — Block API v3 & Metadata Collection Engine
* Description: Мгновенная регистрация библиотеки блоков через предкомпилированный манифест.
* Version: 3.2.0
* Requires at least: 6.8
* Requires PHP: 8.4
* Author: Artur Yusupov (Fullstack Agentic Lab)
*/
declare(strict_types=1);
namespace AgenticLab\Blocks;
defined('ABSPATH') || exit;
final readonly class BlockLibraryRegistrar
{
public function __construct(
private string $buildDir,
private string $manifestFile,
) {}
public function registerHooks(): void
{
add_action('init', $this->registerAllBlocks(...), 10);
add_filter('block_categories_all', $this->registerCustomCategory(...), 10, 1);
}
/**
* Регистрирует всю коллекцию блоков за O(1) обращений к диску (WordPress 6.8 / 7.0+).
*/
public function registerAllBlocks(): void
{
// Принудительно включаем раздельную загрузку CSS только для используемых на странице блоков
add_filter('should_load_separate_core_block_assets', '__return_true');
if (function_exists('wp_register_block_types_from_metadata_collection')) {
wp_register_block_types_from_metadata_collection($this->buildDir, $this->manifestFile);
return;
}
// Fallback для окружений с ручным обходом после регистрации коллекции
if (function_exists('wp_register_block_metadata_collection') && is_readable($this->manifestFile)) {
wp_register_block_metadata_collection($this->buildDir, $this->manifestFile);
/** @var array<string, array<string, mixed>> $manifest */
$manifest = require $this->manifestFile;
foreach (array_keys($manifest) as $blockFolder) {
register_block_type($this->buildDir . '/' . $blockFolder);
}
}
}
/**
* Добавляет фирменную категорию блоков в инсертер Gutenberg.
*
* @param array<int, array<string, mixed>> $categories
* @return array<int, array<string, mixed>>
*/
public function registerCustomCategory(array $categories): array
{
array_unshift($categories, [
'slug' => 'agentic-lab-architecture',
'title' => 'Fullstack Agentic Lab',
'icon' => 'performance',
]);
return $categories;
}
}
(new BlockLibraryRegistrar(
buildDir: __DIR__ . '/build/blocks',
manifestFile: __DIR__ . '/build/blocks-manifest.php',
))->registerHooks();
/*
* ============================================================================
* ЭТАЛОННЫЙ ФАЙЛ: build/blocks/telemetry-card/block.json (Block API v3)
* ============================================================================
* {
* "$schema": "https://schemas.wp.org/trunk/block.json",
* "apiVersion": 3,
* "name": "agentic-lab/telemetry-card",
* "version": "3.2.0",
* "title": "Architecture Telemetry Card",
* "category": "agentic-lab-architecture",
* "icon": "chart-area",
* "description": "Интерактивная карточка метрик инфраструктуры с поддержкой Interactivity API и Block Context.",
* "keywords": ["telemetry", "metrics", "benchmark", "agentic"],
* "textdomain": "agentic-lab",
* "attributes": {
* "serviceName": {
* "type": "string",
* "default": "Edge Worker Gateway"
* },
* "latencyP95Ms": {
* "type": "number",
* "default": 14
* },
* "uptimePercent": {
* "type": "number",
* "default": 99.99
* },
* "statusLevel": {
* "type": "string",
* "enum": ["optimal", "degraded", "critical"],
* "default": "optimal"
* }
* },
* "providesContext": {
* "agentic-lab/statusLevel": "statusLevel"
* },
* "usesContext": [
* "postId",
* "postType",
* "agentic-lab/environmentMode"
* ],
* "supports": {
* "html": false,
* "align": ["wide", "full"],
* "interactivity": {
* "clientNavigation": true,
* "interactive": true
* },
* "color": {
* "background": true,
* "gradients": true,
* "text": true
* },
* "spacing": {
* "padding": true,
* "margin": ["top", "bottom"],
* "blockGap": true
* },
* "typography": {
* "fontSize": true,
* "lineHeight": true
* },
* " '__experimentalBorder' -> border ": {
* "radius": true,
* "width": true,
* "color": true
* },
* "shadow": true
* },
* "editorScript": "file:./index.js",
* "editorStyle": "file:./index.css",
* "style": "file:./style-index.css",
* "viewScriptModule": "file:./view.js",
* "render": "file:./render.php"
* }
*/
К каким негативным последствиям приводит указание source: 'html' или source: 'attribute' вместо стандартного хранения поля в JSON-комментарии блока?