Treci la conținut

Contextul și comunicarea între blocuri

Majoritatea blocurilor sunt autonome. Au propriile câmpuri și propriul șablon și nu le pasă ce se află în jurul lor. Însă unele componente au în mod firesc o structură ierarhică: o grilă de carduri în care părintele controlează numărul de coloane și spațierea, un tabel de prețuri în care părintele stabilește moneda sau un container de secțiune care le indică blocurilor copil dacă să folosească o temă deschisă sau închisă.

WordPress oferă pentru aceasta o contextualizare a blocului API. Un bloc părinte expune o parte din datele sale, iar blocurile copil se abonează la ele. Când părintele se modifică, copiii se actualizează automat. Blockstudio simplifică mult acest proces: nu trebuie să configurați deloc providesContext. Fiecare bloc Blockstudio oferă automat toate atributele sale drept context. Blocurile copil au nevoie doar de o linie în block.json pentru a se abona.

Acest ghid construiește patru tipare de componente din lumea reală care folosesc contextul, fiecare demonstrând o nevoie diferită de comunicare.

Cum funcționează contextul în Blockstudio

În WordPress standard, trebuie să mapați explicit fiecare atribut al părintelui la o cheie de context în providesContext, apoi să enumerați acele chei în usesContext copilului. Blockstudio elimină complet primul pas.

Bloc părinte: Nu este necesară nicio configurare. Fiecare bloc Blockstudio oferă automat toate atributele sale sub numele blocului.

Bloc copil: Adăugați usesContext cu numele blocului părinte:

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

Șablonul copilului: Accesați atributele părintelui prin $context (sau prescurtarea $c):

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

Aceasta este toată configurarea. Fără providesContext în părinte, fără maparea atributelor și fără cod de înregistrare. Copilul primește toate atributele transformate ale părintelui, ceea ce înseamnă că câmpurile media sunt rezolvate la datele atașamentului, câmpurile de selecție respectă returnFormat, iar repetoarele sunt extinse complet.

Două tipuri de context

Blockstudio oferă două variabile de context în șabloane, fiecare cu un scop diferit:

Variabilă Conține Caz de utilizare
$context / $c Atributele blocului părinte (prin usesContext) Comunicarea între componente
$block['context'] / $b['context'] Datele buclei WordPress (postId, postType) Bucle de blocuri de interogare

Prima servește blocurilor care comunică cu părinții lor. A doua servește blocurilor dintr-o buclă Query care trebuie să știe ce postare redau. Acest ghid se concentrează pe primul tip.

Asistență în editor

Actualizările contextului sunt reactive în editor. Când un utilizator modifică valoarea unui câmp dintr-un bloc părinte, toate blocurile copil abonate la contextul acelui părinte se randează din nou automat cu noua valoare. Nu este necesară reîmprospătarea manuală.

Container de secțiune

Cel mai frecvent tipar de context: un bloc container care oferă setări de temă blocurilor copil. Părintele are câmpuri pentru culoarea de fundal, culoarea textului și spațierea interioară. Copiii citesc aceste valori pentru a-și aplica stilurile în mod consecvent.

Părinte: Secțiune

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>

Copil: Titlu de secțiune

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>

Ce demonstrează: Titlul nu are propriul câmp de culoare. Citește valoarea theme a secțiunii din context și se adaptează. Când utilizatorul schimbă secțiunea din „Light” în „Dark” în editor, culoarea textului titlului se actualizează imediat.

Proprietatea parent din block.json copilului restricționează locurile în care poate fi inserat blocul. Acesta apare în inserator doar când utilizatorul se află într-un bloc my-theme/section. Este opțională, dar recomandată pentru blocurile care au sens doar într-un anumit bloc părinte.

Copil: Text de secțiune

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>

Acum, atât titlul, cât și textul reacționează la tema secțiunii. Utilizatorul alege tema o singură dată în părinte, iar fiecare copil se adaptează.

Grilă de carduri

Un bloc părinte de tip grilă controlează setările de aranjare pentru cardurile copil. Părintele definește coloanele și spațierea. Copiii folosesc aceste valori pentru a înțelege contextul de aranjare și pentru a-și ajusta stilurile în consecință.

Părinte: Grilă de carduri

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>

Copil: Card

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>

Ce demonstrează: Cardul nu are propriul câmp de stil. Citește cardStyle de la blocul părinte al grilei. Când utilizatorul schimbă grila din „Elevated” în „Outlined”, toate cardurile din grilă se actualizează simultan. Astfel, cardurile rămân consecvente vizual fără ca utilizatorul să fie nevoit să le actualizeze pe fiecare în parte.

Atributul template din <InnerBlocks> precompletează grila cu trei carduri, oferindu-i utilizatorului un punct de pornire.

Tabel de prețuri

Un tipar mai avansat în care părintele oferă o logică de afaceri comună (moneda, perioada de facturare), pe care copiii o folosesc la afișare. Astfel, nu trebuie să duplicați aceleași câmpuri pentru fiecare nivel de preț.

Părinte: Tabel de prețuri

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>

Copil: Nivel de preț

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>

Ce demonstrează: Simbolul monedei și perioada de facturare sunt definite o singură dată în tabelul de prețuri și sunt moștenite de fiecare nivel. Când utilizatorul schimbă moneda din USD în EUR, simbolul monedei se actualizează simultan în toate cele trei niveluri. Fără context, ar trebui să duplicați câmpul monedei pentru fiecare nivel și să le mențineți sincronizate manual.

Contextul buclei Query

Există un tip separat de context oferit de WordPress în interiorul buclelor blocurilor Query. Când un bloc este redat într-o buclă, $block['context'] (sau $b['context']) conține datele postării din iterația curentă:

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>

Acesta diferă de contextul blocului părinte ($context / $c). Contextul buclei este oferit de nucleul WordPress și conține doar postId și postType. Pentru aceasta, nu aveți nevoie de usesContext în block.json. Blockstudio abonează automat fiecare bloc la postId și postType.

Unde este util contextul buclei: carduri personalizate pentru postări în blocuri Query, blocuri care afișează metadatele postării sau orice bloc care trebuie să se randeze diferit pentru fiecare postare dintr-o buclă.

Puteți accesa și datele postării din pagina exterioară, indiferent de contextul buclei:

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

Context imbricat

Contextul se propagă prin întregul arbore de blocuri, nu doar pe un singur nivel. Dacă blocul A conține blocul B, care conține blocul C, atunci C se poate abona la contextul lui A. Acest lucru funcționează deoarece WordPress propagă contextul prin fiecare nivel de InnerBlocks.

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

Titlul nu trebuie să fie copilul direct al secțiunii. Poate fi imbricat în blocuri de bază (coloane, grupuri etc.) și tot va primi contextul secțiunii. Abonarea usesContext funcționează la orice adâncime.

Mai mulți părinți

Un copil se poate abona la mai mulți părinți:

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

Dacă un părinte nu este găsit în arborele strămoșilor, cheia sa va lipsi din $context. Folosiți întotdeauna operatorul de coalescență pentru valori nule (??) sau verificați isset() când citiți valorile contextului, în cazul în care blocul este folosit în afara părintelui așteptat.

Programare defensivă

Blocurile care folosesc contextul trebuie să gestioneze întotdeauna situația în care părintele lipsește. Un utilizator ar putea insera blocul în afara părintelui destinat sau blocul părinte ar putea să nu aibă o valoare setată pentru un anumit câmp.

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

Dacă doriți să impuneți ca un copil să apară doar în interiorul părintelui său, adăugați proprietatea parent:

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

Astfel, blocul este eliminat din inserator când utilizatorul nu se află într-un bloc my-theme/section. Fără parent, blocul apare peste tot, iar șablonul trebuie să gestioneze cu grijă lipsa contextului.

Folosiți parent pentru blocurile care nu au sens în afara containerului lor (niveluri de preț, elemente din grila de carduri). Omiteți-l pentru blocurile care funcționează independent, dar beneficiază de stiluri suplimentare din partea unui părinte (titluri de secțiune care pot fi folosite și independent).

Sfaturi

Contextul este doar pentru citire. Copiii nu pot modifica atributele părintelui prin context. Datele curg în jos, niciodată în sus. Dacă un copil trebuie să comunice ceva părintelui, aveți nevoie de o altă abordare (precum starea partajată pe server prin API Interactivity sau metadatele postării).

Sunt oferite toate atributele. Blockstudio oferă fiecare atribut al blocului părinte, nu doar pe cele selectate de dvs. Astfel, copilul poate accesa orice câmp definit de părinte. Dacă părintele adaugă ulterior un câmp nou, copiii îl pot accesa automat, fără modificări de configurare.

Valori transformate. Valorile contextului trec prin conducta de transformare a atributelor pentru Blockstudio. Câmpurile pentru fișiere conțin datele complete ale atașamentului (url, alt, width, height), câmpurile de selecție respectă returnFormat, iar repetoarele sunt extinse recursiv. Obțineți aceeași structură de date ca $a în șablonul părintelui.

Reactivitate în editor. Când un utilizator modifică un câmp al părintelui în editor, blocurile copil se randează din nou automat. Se folosește propagarea contextului încorporată în WordPress, împreună cu un React useEffect care detectează modificările contextului și declanșează randarea din nou a copilului pe server.

Păstrați contextul restrâns. Deși Blockstudio oferă automat toate atributele părintelui, copiii ar trebui să citească doar valorile de care au nevoie. Nu este o problemă de performanță (datele sunt deja disponibile), ci una de claritate a codului. Documentați câmpurile părintelui de care depinde un copil, astfel încât viitorii dezvoltatori să înțeleagă relația.

Pașii următori

  • Referință pentru context: variabile de șablon, contextul buclei și structura de date $block.
  • InnerBlocks: componenta <InnerBlocks />, allowedBlocks, șabloane și filtrul containerului din frontend.
  • Ghidul Interactivity: pentru reactivitatea din partea clientului între blocuri (API Interactivity gestionează ceea ce contextul nu poate: comunicarea de la copil la părinte, starea între blocuri și actualizările inițiate de utilizator).