Контекст и взаимодействие блоков
Большинство блоков автономны. У них есть собственные поля и шаблон, и им безразлично, что находится вокруг. Но некоторые компоненты по своей природе иерархичны: сетка карточек, где родитель управляет количеством столбцов и интервалом; таблица цен, где родитель задает валюту; обертка секции, которая указывает дочерним блокам, использовать светлую или темную тему.
WordPress предоставляет для этого контекст блока API. Родительский блок открывает доступ к некоторым своим данным, а дочерние блоки подписываются на них. Когда родитель меняется, дочерние блоки обновляются автоматически. Blockstudio значительно упрощает эту задачу: настраивать providesContext вообще не нужно. Каждый блок Blockstudio автоматически предоставляет все свои атрибуты в качестве контекста. Дочерним блокам достаточно добавить одну строку в block.json, чтобы подписаться на него.
В этом руководстве разобраны четыре практических шаблона компонентов с контекстом, каждый из которых показывает разные потребности во взаимодействии.
Как работает контекст в Blockstudio
В стандартном WordPress нужно явно сопоставить каждый атрибут родительского блока с ключом контекста в providesContext, а затем перечислить эти ключи в usesContext дочернего блока. Blockstudio полностью устраняет первый шаг.
Родительский блок: настройка не требуется. Каждый блок Blockstudio автоматически предоставляет все свои атрибуты под именем блока.
Дочерний блок: добавьте usesContext с именем родительского блока:
{
"usesContext": ["my-theme/parent-block"]
}
Шаблон дочернего блока: получайте доступ к атрибутам родителя через $context (или сокращенную запись $c):
<?php $parent = $context['my-theme/parent-block']; ?>
<p>Parent says: <?php echo esc_html( $parent['message'] ); ?></p>
Вот и вся настройка. В родителе не нужен providesContext, не требуется сопоставление атрибутов или код регистрации. Дочерний блок получает все преобразованные атрибуты родителя: медиаполя разрешаются в данные вложений, поля выбора учитывают returnFormat, а повторители полностью раскрываются.
Два вида контекста
Blockstudio предоставляет в шаблонах две переменные контекста с разными назначениями:
| Переменная | Содержимое | Применение |
|---|---|---|
$context / $c |
Атрибуты родительского блока (через usesContext) |
Взаимодействие компонентов |
$block['context'] / $b['context'] |
Данные цикла WordPress (postId, postType) |
Циклы блоков запросов |
Первый вариант позволяет блокам взаимодействовать с родительскими блоками. Второй нужен блокам внутри цикла Query, чтобы знать, какую запись они выводят. В этом руководстве рассматривается первый вид.
Поддержка в редакторе
В редакторе обновления контекста происходят реактивно. Когда пользователь меняет значение поля родительского блока, все дочерние блоки, подписанные на его контекст, автоматически перерисовываются с новым значением. Обновлять страницу вручную не нужно.
Обертка секции
Самый распространенный шаблон контекста: блок-обертка, который предоставляет дочерним блокам настройки темы. У родителя есть поля для цвета фона, цвета текста и внутренних отступов. Дочерние блоки читают эти значения, чтобы оформлять себя единообразно.
Родительский блок: Section
{
"name": "my-theme/section",
"title": "Section",
"category": "design",
"icon": "align-wide",
"description": "Section wrapper with theme settings.",
"blockstudio": {
"attributes": [
{
"id": "theme",
"type": "select",
"label": "Theme",
"default": "light",
"options": [
{ "value": "light", "label": "Light" },
{ "value": "dark", "label": "Dark" },
{ "value": "accent", "label": "Accent" }
]
},
{
"id": "spacing",
"type": "select",
"label": "Spacing",
"default": "md",
"options": [
{ "value": "sm", "label": "Small" },
{ "value": "md", "label": "Medium" },
{ "value": "lg", "label": "Large" }
]
}
]
}
}
<?php
$theme_classes = array(
'light' => 'bg-white text-gray-900',
'dark' => 'bg-gray-900 text-white',
'accent' => 'bg-indigo-600 text-white',
);
$spacing_classes = array(
'sm' => 'py-8',
'md' => 'py-16',
'lg' => 'py-24',
);
$classes = ( $theme_classes[ $a['theme'] ] ?? '' ) . ' ' . ( $spacing_classes[ $a['spacing'] ] ?? '' );
?>
<div useBlockProps class="<?php echo esc_attr( $classes ); ?>">
<InnerBlocks
allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/section-heading', 'my-theme/section-text', 'core/columns', 'core/group' ) ) ); ?>'
/>
</div>
Дочерний блок: Section Heading
{
"name": "my-theme/section-heading",
"title": "Section Heading",
"category": "design",
"icon": "heading",
"description": "Heading that adapts to section theme.",
"usesContext": ["my-theme/section"],
"parent": ["my-theme/section"],
"blockstudio": {
"attributes": [
{ "id": "text", "type": "text", "label": "Heading", "default": "Section Title" },
{
"id": "size",
"type": "select",
"label": "Size",
"default": "lg",
"options": [
{ "value": "sm", "label": "Small" },
{ "value": "lg", "label": "Large" },
{ "value": "xl", "label": "Extra Large" }
]
}
]
}
}
<?php
$section = $context['my-theme/section'] ?? array();
$theme = $section['theme'] ?? 'light';
$color_class = match ( $theme ) {
'light' => 'text-gray-900',
'dark' => 'text-white',
'accent' => 'text-white',
default => 'text-gray-900',
};
$size_class = match ( $a['size'] ) {
'sm' => 'text-2xl',
'lg' => 'text-4xl',
'xl' => 'text-6xl',
default => 'text-4xl',
};
?>
<h2 useBlockProps class="<?php echo esc_attr( "$color_class $size_class font-bold" ); ?>">
<?php echo esc_html( $a['text'] ); ?>
</h2>
Что показывает этот пример: У заголовка нет собственного поля цвета. Он читает значение theme секции из контекста и подстраивается под него. Когда пользователь переключает секцию с «Светлой» на «Темную» в редакторе, цвет текста заголовка обновляется сразу.
Свойство parent в block.json дочернего блока ограничивает места, куда его можно вставить. Он отображается в панели вставки, только когда пользователь находится внутри блока my-theme/section. Это необязательно, но рекомендуется для блоков, которые имеют смысл только внутри определенного родителя.
Дочерний блок: Section Text
{
"name": "my-theme/section-text",
"title": "Section Text",
"category": "design",
"icon": "text",
"description": "Body text that adapts to section theme.",
"usesContext": ["my-theme/section"],
"parent": ["my-theme/section"],
"blockstudio": {
"attributes": [
{ "id": "text", "type": "textarea", "label": "Text", "default": "Section body text." }
]
}
}
<?php
$section = $context['my-theme/section'] ?? array();
$theme = $section['theme'] ?? 'light';
$color_class = match ( $theme ) {
'dark', 'accent' => 'text-white/80',
default => 'text-gray-600',
};
?>
<p useBlockProps class="<?php echo esc_attr( "$color_class text-lg leading-relaxed" ); ?>">
<?php echo esc_html( $a['text'] ); ?>
</p>
Теперь и заголовок, и текст реагируют на тему секции. Пользователь выбирает тему один раз в родительском блоке, и каждый дочерний блок подстраивается.
Сетка карточек
Родительская сетка управляет настройками макета дочерних карточек. Родитель задает количество столбцов и интервал. Дочерние блоки используют эти значения, чтобы определить контекст своего макета и соответствующим образом настроить оформление.
Родительский блок: Card Grid
{
"name": "my-theme/card-grid",
"title": "Card Grid",
"category": "design",
"icon": "grid-view",
"description": "Responsive card grid with configurable columns.",
"blockstudio": {
"attributes": [
{
"id": "columns",
"type": "range",
"label": "Columns",
"default": 3,
"min": 1,
"max": 4,
"step": 1
},
{
"id": "gap",
"type": "select",
"label": "Gap",
"default": "md",
"options": [
{ "value": "sm", "label": "Small" },
{ "value": "md", "label": "Medium" },
{ "value": "lg", "label": "Large" }
]
},
{
"id": "cardStyle",
"type": "select",
"label": "Card Style",
"default": "elevated",
"options": [
{ "value": "elevated", "label": "Elevated (shadow)" },
{ "value": "outlined", "label": "Outlined (border)" },
{ "value": "flat", "label": "Flat (no decoration)" }
]
}
]
}
}
<?php
$gap_class = match ( $a['gap'] ) {
'sm' => 'gap-4',
'md' => 'gap-6',
'lg' => 'gap-8',
default => 'gap-6',
};
?>
<div useBlockProps class="grid grid-cols-<?php echo esc_attr( $a['columns'] ); ?> <?php echo esc_attr( $gap_class ); ?>">
<InnerBlocks
allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/card' ) ) ); ?>'
template='<?php echo esc_attr( wp_json_encode( array(
array( 'my-theme/card', array() ),
array( 'my-theme/card', array() ),
array( 'my-theme/card', array() ),
) ) ); ?>'
/>
</div>
Дочерний блок: Card
{
"name": "my-theme/card",
"title": "Card",
"category": "design",
"icon": "cover-image",
"description": "Card that inherits style from its grid parent.",
"usesContext": ["my-theme/card-grid"],
"parent": ["my-theme/card-grid"],
"blockstudio": {
"attributes": [
{ "id": "image", "type": "files", "label": "Image", "multiple": false },
{ "id": "title", "type": "text", "label": "Title", "default": "Card Title" },
{ "id": "description", "type": "textarea", "label": "Description", "default": "Card description goes here." },
{ "id": "url", "type": "link", "label": "Link" }
]
}
}
<?php
$grid = $context['my-theme/card-grid'] ?? array();
$card_style = $grid['cardStyle'] ?? 'elevated';
$style_class = match ( $card_style ) {
'elevated' => 'bg-white rounded-xl shadow-md',
'outlined' => 'bg-white rounded-xl border border-gray-200',
'flat' => 'bg-gray-50 rounded-xl',
default => 'bg-white rounded-xl shadow-md',
};
?>
<div useBlockProps class="<?php echo esc_attr( "$style_class overflow-hidden" ); ?>">
<?php if ( $a['image'] ) : ?>
<img
src="<?php echo esc_url( $a['image']['url'] ); ?>"
alt="<?php echo esc_attr( $a['image']['alt'] ); ?>"
class="w-full aspect-video object-cover" />
<?php endif; ?>
<div class="p-6">
<h3 class="text-lg font-semibold"><?php echo esc_html( $a['title'] ); ?></h3>
<p class="mt-2 text-gray-600"><?php echo esc_html( $a['description'] ); ?></p>
<?php if ( $a['url'] ) : ?>
<a href="<?php echo esc_url( $a['url']['url'] ); ?>" class="mt-4 inline-block text-indigo-600 font-medium">
<?php echo esc_html( $a['url']['title'] ?: 'Learn more' ); ?>
</a>
<?php endif; ?>
</div>
</div>
Что показывает этот пример: У карточки нет собственных полей стиля. Она читает cardStyle из родительской сетки. Когда пользователь переключает сетку со стиля «С тенью» на «С контуром», все карточки в сетке обновляются одновременно. Так карточки сохраняют единый вид, и пользователю не нужно обновлять каждую по отдельности.
Атрибут template у <InnerBlocks> заранее заполняет сетку тремя карточками, давая пользователю исходный вариант.
Таблица цен
Более сложный шаблон, в котором родительский блок предоставляет общую бизнес-логику (валюту, период оплаты), используемую дочерними блоками при выводе данных. Это позволяет не дублировать одни и те же поля в каждом тарифном плане.
Родительский блок: Pricing Table
{
"name": "my-theme/pricing-table",
"title": "Pricing Table",
"category": "text",
"icon": "money-alt",
"description": "Pricing comparison with shared currency and billing settings.",
"blockstudio": {
"attributes": [
{
"id": "currency",
"type": "select",
"label": "Currency",
"default": "usd",
"options": [
{ "value": "usd", "label": "USD ($)" },
{ "value": "eur", "label": "EUR (\u20ac)" },
{ "value": "gbp", "label": "GBP (\u00a3)" }
]
},
{
"id": "period",
"type": "select",
"label": "Billing Period",
"default": "month",
"options": [
{ "value": "month", "label": "Monthly" },
{ "value": "year", "label": "Yearly" }
]
}
]
}
}
<div useBlockProps class="grid grid-cols-3 gap-6 items-start">
<InnerBlocks
allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/pricing-tier' ) ) ); ?>'
template='<?php echo esc_attr( wp_json_encode( array(
array( 'my-theme/pricing-tier', array( 'name' => 'Starter', 'price' => 9 ) ),
array( 'my-theme/pricing-tier', array( 'name' => 'Pro', 'price' => 29, 'highlighted' => true ) ),
array( 'my-theme/pricing-tier', array( 'name' => 'Enterprise', 'price' => 99 ) ),
) ) ); ?>'
/>
</div>
Дочерний блок: Pricing Tier
{
"name": "my-theme/pricing-tier",
"title": "Pricing Tier",
"category": "text",
"icon": "tag",
"description": "Single pricing tier that reads currency from parent.",
"usesContext": ["my-theme/pricing-table"],
"parent": ["my-theme/pricing-table"],
"blockstudio": {
"attributes": [
{ "id": "name", "type": "text", "label": "Tier Name", "default": "Plan" },
{ "id": "price", "type": "number", "label": "Price", "default": 0 },
{ "id": "highlighted", "type": "toggle", "label": "Highlighted", "default": false },
{
"id": "features",
"type": "repeater",
"label": "Features",
"attributes": [
{ "id": "text", "type": "text", "label": "Feature" }
]
}
]
}
}
<?php
$table = $context['my-theme/pricing-table'] ?? array();
$currency = $table['currency'] ?? 'usd';
$period = $table['period'] ?? 'month';
$symbols = array(
'usd' => '$',
'eur' => "\u{20AC}",
'gbp' => "\u{00A3}",
);
$symbol = $symbols[ $currency ] ?? '$';
$period_label = $period === 'year' ? '/year' : '/month';
$border_class = $a['highlighted'] ? 'border-2 border-indigo-600' : 'border border-gray-200';
?>
<div useBlockProps class="<?php echo esc_attr( "rounded-xl p-8 $border_class" ); ?>">
<h3 class="text-lg font-semibold"><?php echo esc_html( $a['name'] ); ?></h3>
<div class="mt-4">
<span class="text-4xl font-bold"><?php echo esc_html( $symbol . $a['price'] ); ?></span>
<span class="text-gray-500"><?php echo esc_html( $period_label ); ?></span>
</div>
<?php if ( ! empty( $a['features'] ) ) : ?>
<ul class="mt-6 space-y-3">
<?php foreach ( $a['features'] as $feature ) : ?>
<li class="flex items-center gap-2">
<span class="text-indigo-600">✓</span>
<?php echo esc_html( $feature['text'] ); ?>
</li>
<?php endforeach; ?>
</ul>
<?php endif; ?>
</div>
Что показывает этот пример: Символ валюты и период оплаты задаются один раз в таблице цен и наследуются всеми тарифами. Когда пользователь переключает валюту с USD на EUR, символ валюты одновременно меняется во всех трех тарифах. Без контекста пришлось бы дублировать поле валюты в каждом тарифе и синхронизировать их вручную.
Контекст цикла Query
Есть отдельный вид контекста, который WordPress предоставляет внутри циклов блока Query. Когда блок выводится внутри цикла, $block['context'] (или $b['context']) содержит данные записи для текущей итерации:
<?php
$loop_post_id = $block['context']['postId'];
$loop_post_type = $block['context']['postType'];
?>
<article useBlockProps>
<h2><?php echo esc_html( get_the_title( $loop_post_id ) ); ?></h2>
<p><?php echo esc_html( get_the_excerpt( $loop_post_id ) ); ?></p>
<a href="<?php echo esc_url( get_permalink( $loop_post_id ) ); ?>">Read more</a>
</article>
Это отличается от контекста родительского блока ($context / $c). Контекст цикла предоставляет ядро WordPress; он содержит только postId и postType. Для этого не требуется usesContext в вашем block.json. Blockstudio автоматически подписывает каждый блок на postId и postType.
Где полезен контекст цикла: пользовательские карточки записей внутри блоков Query, блоки, отображающие метаданные записи, и любые блоки, которым нужно по-разному выводить каждую запись в цикле.
Также можно получить доступ к данным записи внешней страницы независимо от контекста цикла:
$outer_post_id = $block['postId']; // always the current page
$loop_post_id = $block['context']['postId']; // current loop iteration
Вложенный контекст
Контекст передается по всему дереву блоков, а не только на один уровень вниз. Если блок A содержит блок B, а тот — блок C, то C может подписаться на контекст A. Это работает, потому что WordPress передает контекст через все уровни InnerBlocks.
my-theme/section (theme: "dark")
└── core/columns
└── core/column
└── my-theme/section-heading (reads section context)
Заголовок не обязательно должен быть непосредственным дочерним блоком секции. Он может быть вложен в стандартные блоки (колонки, группы и т. д.) и все равно получать контекст секции. Подписка usesContext работает на любой глубине.
Несколько родителей
Дочерний блок может подписаться на несколько родительских блоков:
{
"usesContext": ["my-theme/section", "my-theme/card-grid"]
}
<?php
$section = $context['my-theme/section'] ?? array();
$grid = $context['my-theme/card-grid'] ?? array();
$theme = $section['theme'] ?? 'light';
$cardStyle = $grid['cardStyle'] ?? 'elevated';
?>
Если родительский блок не найден в дереве предков, его ключ будет отсутствовать в $context. Всегда используйте оператор нулевого слияния (??) или проверяйте isset() при чтении значений контекста на случай, если блок используется вне ожидаемого родителя.
Защитное программирование
Блоки, использующие контекст, всегда должны обрабатывать ситуацию, когда родительский блок отсутствует. Пользователь может вставить блок вне предназначенного для него родителя, или у родительского блока может быть не задано значение какого-либо поля.
<?php
// Always provide defaults
$section = $context['my-theme/section'] ?? array();
$theme = $section['theme'] ?? 'light';
$spacing = $section['spacing'] ?? 'md';
?>
Чтобы гарантировать, что дочерний блок появляется только внутри родительского, добавьте свойство parent:
{
"parent": ["my-theme/section"]
}
Так блок исчезает из панели вставки, если пользователь находится вне блока my-theme/section. Без parent блок отображается повсюду, и шаблон должен корректно обрабатывать отсутствие контекста.
Используйте parent для блоков, которые теряют смысл вне контейнера (тарифные планы, элементы сетки карточек). Не добавляйте его блокам, которые работают самостоятельно, но получают дополнительное оформление от родителя (например, заголовкам секций, которые можно использовать отдельно).
Советы
Контекст доступен только для чтения. Дочерние блоки не могут менять атрибуты родительского блока через контекст. Данные передаются только вниз, но не вверх. Если дочернему блоку нужно передать что-либо родительскому, используйте другой подход (например, общее состояние сервера через API интерактивности или метаданные записи).
Предоставляются все атрибуты. Blockstudio предоставляет все атрибуты родительского блока, а не только выбранные вами. Это значит, что дочерний блок может обращаться к любому полю, заданному родителем. Если позже родитель получит новое поле, оно автоматически станет доступно дочерним блокам без изменения настроек.
Преобразованные значения. Значения контекста проходят через конвейер преобразования атрибутов Blockstudio. Поля файлов содержат полные данные вложения (url, alt, width, height), поля выбора учитывают returnFormat, а повторители рекурсивно раскрываются. Вы получаете ту же структуру данных, что и $a в шаблоне родительского блока.
Реактивность редактора. Когда пользователь меняет поле родительского блока в редакторе, дочерние блоки автоматически перерисовываются. Для этого используется встроенная в WordPress передача контекста и React useEffect, которое обнаруживает изменения контекста и запускает серверный повторный рендеринг дочернего блока.
Не перегружайте контекст. Хотя Blockstudio автоматически предоставляет все атрибуты родителя, дочерним блокам следует читать только необходимые значения. Это важно не для производительности (данные уже доступны), а для ясности кода. Документируйте, от каких полей родителя зависит дочерний блок, чтобы будущие разработчики понимали эту связь.
Следующие шаги
- Справочник по контексту: переменные шаблонов, контекст цикла и структура данных
$block. - InnerBlocks: компонент
<InnerBlocks />,allowedBlocks, шаблоны и фильтр обертки для внешней части сайта. - Руководство по интерактивности: о клиентской реактивности между блоками (API интерактивности отвечает за то, с чем не справляется контекст: взаимодействие дочернего блока с родительским, состояние между блоками и обновления по действию пользователя).