Към съдържанието

Контекст и комуникация между блокове

Повечето блокове са самостоятелни. Те имат собствени полета и шаблон и не се интересуват от обкръжението си. Някои компоненти обаче естествено са йерархични: мрежа от карти, в която родителят управлява броя на колоните и разстоянието между тях; ценова таблица, в която родителят задава валутата; обвивка на секция, която указва на дъщерните блокове дали да използват светла или тъмна тема.

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) Цикли в блок за заявки

Първият вид позволява на блоковете да комуникират с родителите си. Вторият е за блокове в цикъл на блок за заявки, които трябва да знаят коя публикация визуализират. Това ръководство разглежда първия вид.

Поддръжка в редактора

Промените в контекста се отразяват реактивно в редактора. Когато потребител промени стойността на поле в родителски блок, всички дъщерни блокове, абонирани за контекста на родителя, автоматично се изобразяват отново с новата стойност. Не е необходимо ръчно обновяване.

Обвивка на секция

Най-често срещаният шаблон за контекст е блок обвивка, който предоставя настройки на темата на дъщерните си блокове. Родителят има полета за цвят на фона, цвят на текста и отстъп. Дъщерните блокове четат тези стойности, за да оформят стила си последователно.

Родител: Секция

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 предоставя в циклите на блокове за заявки. Когато блок се визуализира в цикъл, $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.

Кога е полезен контекстът на цикъла: За персонализирани карти на публикации в блокове за заявки, блокове, които показват метаданни на публикации, или всеки блок, който трябва да се изобразява различно за всяка публикация в цикъл.

Можете да получите достъп и до данните за публикацията на външната страница независимо от контекста на цикъла:

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, шаблони и филтърът за обвивката на фронтенда.
  • Ръководство за интерактивност: за реактивност от страна на клиента между блокове (Interactivity API обработва нещата, с които контекстът не може да се справи: комуникация от дъщерен към родителски блок, състояние между блокове и актуализации, задействани от потребителя).