Przejdź do treści

Kontekst i komunikacja bloków

Większość bloków jest samodzielna. Mają własne pola i szablony, a otoczenie nie ma na nie wpływu. Niektóre komponenty mają jednak naturalnie hierarchiczną strukturę: siatka kart, w której blok nadrzędny kontroluje liczbę kolumn i odstępy; tabela cenowa, w której blok nadrzędny ustala walutę; opakowanie sekcji, które informuje bloki podrzędne, czy mają używać jasnego, czy ciemnego motywu.

WordPress udostępnia do tego kontekst bloku API. Blok nadrzędny udostępnia część swoich danych, a bloki podrzędne je subskrybują. Gdy blok nadrzędny się zmienia, bloki podrzędne aktualizują się automatycznie. Blockstudio znacznie to upraszcza: nie trzeba w ogóle konfigurować providesContext. Każdy blok Blockstudio automatycznie udostępnia wszystkie swoje atrybuty jako kontekst. Bloki podrzędne potrzebują tylko jednej linijki w swoim block.json, aby go subskrybować.

W tym przewodniku zbudujemy cztery praktyczne wzorce komponentów wykorzystujące kontekst; każdy z nich pokazuje inną potrzebę komunikacji.

Jak działa kontekst w Blockstudio

W standardowym WordPress trzeba jawnie przypisać każdy atrybut bloku nadrzędnego do klucza kontekstu w providesContext, a następnie wymienić te klucze w usesContext bloku podrzędnego. Blockstudio całkowicie eliminuje pierwszy krok.

Blok nadrzędny: Nie wymaga konfiguracji. Każdy blok Blockstudio automatycznie udostępnia wszystkie swoje atrybuty pod nazwą bloku.

Blok podrzędny: Dodaj usesContext z nazwą bloku nadrzędnego:

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

Szablon bloku podrzędnego: Uzyskaj dostęp do atrybutów bloku nadrzędnego przez $context (lub skróconą formę $c):

PHP
<?php $parent = $context['my-theme/parent-block']; ?>
<p>Parent says: <?php echo esc_html( $parent['message'] ); ?></p>

To całe wymagane skonfigurowanie. Żadnego providesContext w bloku nadrzędnym, żadnego mapowania atrybutów ani kodu rejestracji. Blok podrzędny otrzymuje wszystkie przekształcone atrybuty bloku nadrzędnego, co oznacza, że pola multimedialne są rozwijane do danych załączników, pola wyboru uwzględniają returnFormat, a pola powtarzalne są w pełni rozwijane.

Dwa rodzaje kontekstu

Blockstudio udostępnia w szablonach dwie zmienne kontekstu, które służą różnym celom:

Zmienna Zawartość Zastosowanie
$context / $c Atrybuty bloku nadrzędnego (przez usesContext) Komunikacja między komponentami
$block['context'] / $b['context'] Dane pętli WordPress (postId, postType) Pętle bloków zapytań

Pierwszy rodzaj służy blokom do komunikacji z blokami nadrzędnymi. Drugi jest przeznaczony dla bloków wewnątrz pętli zapytania, które muszą wiedzieć, który wpis renderują. Ten przewodnik dotyczy pierwszego rodzaju.

Obsługa w edytorze

Aktualizacje kontekstu w edytorze są reaktywne. Gdy użytkownik zmieni wartość pola bloku nadrzędnego, wszystkie bloki podrzędne subskrybujące jego kontekst automatycznie renderują się ponownie z nową wartością. Nie trzeba ręcznie odświeżać widoku.

Opakowanie sekcji

Najczęstszy wzorzec kontekstu: blok opakowujący, który udostępnia bloki podrzędnym ustawienia motywu. Blok nadrzędny ma pola koloru tła, koloru tekstu i marginesów wewnętrznych. Bloki podrzędne odczytują te wartości, aby zachować spójny styl.

Blok nadrzędny: Sekcja

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>

Blok podrzędny: Nagłówek sekcji

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>

Co to pokazuje: Nagłówek nie ma własnego pola koloru. Odczytuje z kontekstu wartość theme sekcji i dostosowuje się do niej. Gdy użytkownik zmieni motyw sekcji z „Jasny” na „Ciemny” w edytorze, kolor tekstu nagłówka natychmiast się aktualizuje.

Właściwość parent w block.json bloku podrzędnego ogranicza miejsca, w których można wstawić blok. Pojawia się on w inserterze tylko wtedy, gdy użytkownik znajduje się wewnątrz bloku my-theme/section. To ustawienie jest opcjonalne, ale zalecane dla bloków, które mają sens tylko wewnątrz określonego bloku nadrzędnego.

Blok podrzędny: Tekst sekcji

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>

Teraz zarówno nagłówek, jak i tekst reagują na motyw sekcji. Użytkownik wybiera motyw raz w bloku nadrzędnym, a wszystkie bloki podrzędne się do niego dostosowują.

Siatka kart

Blok nadrzędny siatki kontroluje ustawienia układu kart podrzędnych. Definiuje liczbę kolumn i odstępy. Bloki podrzędne używają tych wartości, aby poznać kontekst układu i odpowiednio dostosować styl.

Blok nadrzędny: Siatka kart

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>

Blok podrzędny: Karta

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>

Co to pokazuje: Karta nie ma własnego pola stylu. Odczytuje wartość cardStyle z bloku nadrzędnego siatki. Gdy użytkownik zmieni styl siatki z „Uniesiony” na „Obramowany”, wszystkie karty w siatce aktualizują się jednocześnie. Dzięki temu zachowują spójny wygląd, a użytkownik nie musi aktualizować każdej z nich osobno.

Atrybut template bloku <InnerBlocks> wstępnie wypełnia siatkę trzema kartami, zapewniając użytkownikowi punkt wyjścia.

Tabela cenowa

Bardziej zaawansowany wzorzec, w którym blok nadrzędny udostępnia wspólną logikę biznesową (walutę i okres rozliczeniowy), z której bloki podrzędne korzystają przy wyświetlaniu. Pozwala to uniknąć powielania tych samych pól w każdym progu cenowym.

Blok nadrzędny: Tabela cenowa

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>

Blok podrzędny: Próg cenowy

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>

Co to pokazuje: Symbol waluty i okres rozliczeniowy są określane raz w tabeli cenowej i dziedziczone przez każdy próg cenowy. Gdy użytkownik zmieni USD na EUR, symbole waluty we wszystkich trzech progach aktualizują się jednocześnie. Bez kontekstu trzeba byłoby powielić pole waluty w każdym progu i ręcznie dbać o ich zgodność.

Kontekst pętli zapytania

Istnieje osobny rodzaj kontekstu udostępniany przez WordPress wewnątrz pętli bloków zapytań. Gdy blok renderuje się wewnątrz pętli, $block['context'] (lub $b['context']) zawiera dane wpisu z bieżącej iteracji:

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>

Różni się to od kontekstu bloku nadrzędnego ($context / $c). Kontekst pętli jest udostępniany przez rdzeń WordPress i zawiera tylko postId oraz postType. Nie trzeba w tym celu dodawać usesContext do block.json. Blockstudio automatycznie subskrybuje każdy blok do postId i postType.

Przydatne zastosowania kontekstu pętli: Niestandardowe karty wpisów wewnątrz bloków zapytań, bloki wyświetlające metadane wpisu lub dowolne bloki, które muszą renderować się inaczej dla każdego wpisu w pętli.

Można też uzyskać dostęp do danych wpisu na stronie zewnętrznej, niezależnie od kontekstu pętli:

PHP
$outer_post_id   = $block['postId'];   // always the current page
$loop_post_id    = $block['context']['postId'];  // current loop iteration

Zagnieżdżony kontekst

Kontekst przepływa przez całe drzewo bloków, a nie tylko jeden poziom. Jeśli blok A zawiera blok B, który zawiera blok C, blok C może subskrybować kontekst bloku A. Dzieje się tak, ponieważ WordPress propaguje kontekst na każdym poziomie InnerBlocks.

Kod
my-theme/section (theme: "dark")
└── core/columns
    └── core/column
        └── my-theme/section-heading (reads section context)

Nagłówek nie musi być bezpośrednim blokiem podrzędnym sekcji. Może być zagnieżdżony wewnątrz bloków rdzenia (kolumn, grup itp.) i nadal otrzymywać kontekst sekcji. Subskrypcja usesContext działa na dowolnej głębokości.

Wielu bloków nadrzędnych

Blok podrzędny może subskrybować kontekst wielu bloków nadrzędnych:

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';
?>

Jeśli bloku nadrzędnego nie ma w drzewie przodków, jego klucz nie będzie obecny w $context. Przy odczytywaniu wartości kontekstu zawsze używaj operatora łączenia z null (??) albo sprawdzaj isset() na wypadek, gdyby blok był używany poza oczekiwanym blokiem nadrzędnym.

Programowanie defensywne

Bloki korzystające z kontekstu powinny zawsze obsługiwać sytuację, w której brakuje bloku nadrzędnego. Użytkownik może wstawić blok poza przeznaczonym dla niego blokiem nadrzędnym albo blok nadrzędny może nie mieć ustawionej wartości danego pola.

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

Jeśli chcesz wymusić, aby blok podrzędny pojawiał się tylko wewnątrz bloku nadrzędnego, dodaj właściwość parent:

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

Spowoduje to usunięcie bloku z insertera, gdy użytkownik nie znajduje się wewnątrz bloku my-theme/section. Bez parent blok będzie widoczny wszędzie, a szablon będzie musiał poprawnie obsłużyć brak kontekstu.

Używaj parent w blokach, które nie mają sensu poza swoim kontenerem (progi cenowe, elementy siatki kart). Pomiń tę właściwość w blokach działających samodzielnie, które zyskują jedynie dodatkowy styl dzięki blokowi nadrzędnemu (nagłówki sekcji, których można też używać niezależnie).

Wskazówki

Kontekst jest tylko do odczytu. Bloki podrzędne nie mogą modyfikować atrybutów bloków nadrzędnych za pośrednictwem kontekstu. Dane przepływają w dół, nigdy w górę. Jeśli blok podrzędny ma przekazywać informacje do bloku nadrzędnego, potrzebne jest inne rozwiązanie (np. współdzielony stan serwera przez API Interactivity lub metadane wpisu).

Udostępniane są wszystkie atrybuty. Blockstudio udostępnia wszystkie atrybuty bloku nadrzędnego, nie tylko wybrane. Oznacza to, że blok podrzędny ma dostęp do każdego pola zdefiniowanego przez blok nadrzędny. Jeśli ten później doda nowe pole, bloki podrzędne automatycznie uzyskają do niego dostęp bez zmiany konfiguracji.

Przekształcone wartości. Wartości kontekstu przechodzą przez potok przekształcania atrybutów Blockstudio. Pola plików zawierają pełne dane załączników (url, alt, width, height), pola wyboru uwzględniają returnFormat, a pola powtarzalne są rozwijane rekurencyjnie. Otrzymujesz tę samą strukturę danych co $a w szablonie bloku nadrzędnego.

Reaktywność edytora. Gdy użytkownik zmieni pole bloku nadrzędnego w edytorze, bloki podrzędne automatycznie renderują się ponownie. Wykorzystuje to wbudowane w WordPress propagowanie kontekstu oraz React useEffect, który wykrywa zmiany kontekstu i uruchamia renderowanie bloku podrzędnego po stronie serwera.

Dbaj o zwięzłość kontekstu. Mimo że Blockstudio automatycznie udostępnia wszystkie atrybuty bloku nadrzędnego, bloki podrzędne powinny odczytywać tylko potrzebne wartości. Nie wpływa to na wydajność (dane i tak są dostępne), ale na czytelność kodu. Opisz, od których pól bloku nadrzędnego zależy blok podrzędny, aby przyszli programiści znali tę zależność.

Następne kroki

  • Odwołanie do kontekstu: zmienne szablonów, kontekst pętli i struktura danych $block.
  • InnerBlocks: komponent <InnerBlocks />, allowedBlocks, szablony i filtr opakowania frontendu.
  • Przewodnik po interaktywności: reaktywność po stronie klienta między blokami (Interactivity API obsługuje to, czego nie umożliwia kontekst: komunikację z bloku podrzędnego do nadrzędnego, stan współdzielony między blokami i aktualizacje wywoływane przez użytkownika).