Перейти до вмісту

Контекст блоків і взаємодія

Більшість блоків автономні. Вони мають власні поля та шаблони й не залежать від оточення. Але деякі компоненти природно утворюють ієрархію: сітка карток, у якій батьківський блок керує кількістю стовпців і проміжками; таблиця цін, у якій батьківський блок задає валюту; обгортка секції, яка повідомляє дочірнім блокам, використовувати світлу чи темну тему.

WordPress надає для цього контекст блока API. Батьківський блок надає частину своїх даних, а дочірні блоки підписуються на них. Коли батьківський блок змінюється, дочірні оновлюються автоматично. Blockstudio значно спрощує цей процес: вам зовсім не потрібно налаштовувати providesContext. Кожен блок Blockstudio автоматично передає всі свої атрибути як контекст. Дочірньому блоку достатньо додати один рядок у block.json, щоб підписатися.

У цьому посібнику розглянуто чотири практичні шаблони компонентів із контекстом, кожен із яких демонструє окрему потребу у взаємодії.

Як працює контекст у Blockstudio

У стандартному WordPress потрібно явно зіставити кожен атрибут батьківського блока з ключем контексту в providesContext, а потім перелічити ці ключі в usesContext дочірнього блока. Blockstudio повністю усуває перший крок.

Батьківський блок: налаштування не потрібне. Кожен блок Blockstudio автоматично передає всі свої атрибути під назвою блока.

Дочірній блок: додайте usesContext із назвою батьківського блока:

JSON
{
  "usesContext": ["my-theme/parent-block"]
}

Шаблон дочірнього блока: отримуйте доступ до атрибутів батьківського блока через $context (або скорочений запис $c):

PHP
<?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, яким потрібно знати, яку публікацію вони відображають. У цьому посібнику йдеться про перший тип.

Підтримка редактора

У редакторі зміни контексту застосовуються реактивно. Коли користувач змінює значення поля батьківського блока, усі дочірні блоки, підписані на його контекст, автоматично перерендерюються з новим значенням. Оновлювати їх вручну не потрібно.

Обгортка секції

Найпоширеніший шаблон контексту: блок-обгортка передає дочірнім блокам налаштування теми. У батьківському блоці є поля для кольору тла, кольору тексту та внутрішніх відступів. Дочірні блоки читають ці значення, щоб узгоджено оформити себе.

Батьківський блок: секція

JSON
{
  "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
<?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>

Дочірній блок: заголовок секції

JSON
{
  "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
<?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. Це необов’язково, але рекомендовано для блоків, які мають сенс лише всередині певного батьківського блока.

Дочірній блок: текст секції

JSON
{
  "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
<?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>

Тепер і заголовок, і текст реагують на тему секції. Користувач один раз вибирає тему для батьківського блока, а всі дочірні блоки адаптуються.

Сітка карток

Батьківський блок сітки керує параметрами макета дочірніх карток. Він задає кількість стовпців і проміжки. Дочірні блоки використовують ці значення, щоб визначити параметри свого макета й відповідно налаштувати стиль.

Батьківський блок: сітка карток

JSON
{
  "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
<?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>

Дочірній блок: картка

JSON
{
  "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
<?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> попередньо заповнює сітку трьома картками, щоб користувач мав із чого почати.

Таблиця цін

Складніший шаблон, у якому батьківський блок надає спільну бізнес-логіку (валюту та період оплати), а дочірні блоки використовують її під час відображення. Так не доведеться дублювати ті самі поля для кожного тарифного плану.

Батьківський блок: таблиця цін

JSON
{
  "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" }
        ]
      }
    ]
  }
}
PHP
<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>

Дочірній блок: тарифний план

JSON
{
  "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
<?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">&#10003;</span>
          <?php echo esc_html( $feature['text'] ); ?>
        </li>
      <?php endforeach; ?>
    </ul>
  <?php endif; ?>
</div>

Що це демонструє: символ валюти та період оплати задаються один раз у таблиці цін і успадковуються всіма тарифними планами. Коли користувач перемикає валюту з USD на EUR, символ валюти в усіх трьох тарифних планах оновлюється одночасно. Без контексту довелося б додати поле валюти до кожного тарифного плану й синхронізувати їх вручну.

Контекст циклу запиту

Є окремий тип контексту, який WordPress надає всередині циклів блока Query. Коли блок відображається в циклі, $block['context'] (або $b['context']) містить дані публікації для поточної ітерації:

PHP
<?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, блоки для відображення метаданих публікації або будь-які блоки, які мають по-різному відображатися для кожної публікації в циклі.

Також можна отримати дані публікації зовнішньої сторінки незалежно від контексту циклу:

PHP
$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 працює на будь-якій глибині.

Кілька батьківських блоків

Дочірній блок може підписатися на кілька батьківських блоків:

JSON
{
  "usesContext": ["my-theme/section", "my-theme/card-grid"]
}
PHP
<?php
$section = $context['my-theme/section'] ?? array();
$grid    = $context['my-theme/card-grid'] ?? array();

$theme     = $section['theme'] ?? 'light';
$cardStyle = $grid['cardStyle'] ?? 'elevated';
?>

Якщо батьківського блока немає в дереві предків, його ключ буде відсутній у $context. Завжди використовуйте оператор об’єднання з null (??) або перевіряйте isset() під час читання значень контексту — на випадок, якщо блок використовується поза очікуваним батьківським блоком.

Захисне програмування

Блоки, що використовують контекст, завжди мають передбачати випадок, коли батьківського блока немає. Користувач може вставити блок поза призначеним для нього батьківським блоком, або батьківський блок може не мати значення для певного поля.

PHP
<?php
// Always provide defaults
$section = $context['my-theme/section'] ?? array();
$theme   = $section['theme'] ?? 'light';
$spacing = $section['spacing'] ?? 'md';
?>

Щоб дочірній блок з’являвся лише всередині батьківського, додайте властивість parent:

JSON
{
  "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 забезпечує те, чого не може контекст: взаємодію дочірнього блока з батьківським, стан між блоками та оновлення, ініційовані користувачем).