Hoppa till innehåll

Blockkontext och kommunikation

De flesta block är fristående. De har egna fält och egna mallar och bryr sig inte om vad som finns omkring dem. Men vissa komponenter är naturligt hierarkiska: ett kortnät där det överordnade blocket styr antalet kolumner och mellanrummet, en pristabell där det överordnade blocket anger valutan, eller ett sektionsomslag som talar om för underordnade block om de ska använda ett ljust eller mörkt tema.

WordPress tillhandahåller blockkontext API för detta. Ett överordnat block gör en del av sina data tillgängliga, och underordnade block prenumererar på dem. När det överordnade blocket ändras uppdateras de underordnade blocken automatiskt. Blockstudio förenklar detta avsevärt: du behöver inte konfigurera providesContext alls. Varje Blockstudio-block tillhandahåller automatiskt alla sina attribut som kontext. Underordnade block behöver bara en rad i sin block.json för att prenumerera.

Den här guiden bygger fyra verkliga komponentmönster som använder kontext. Varje mönster visar ett olika kommunikationsbehov.

Så fungerar kontext i Blockstudio

I vanlig WordPress måste du uttryckligen koppla varje attribut i det överordnade blocket till en kontextnyckel i providesContext och sedan ange dessa nycklar i det underordnade blockets usesContext. Blockstudio tar helt bort det första steget.

Överordnat block: Ingen konfiguration behövs. Varje Blockstudio-block tillhandahåller automatiskt alla sina attribut under sitt blocknamn.

Underordnat block: Lägg till usesContext med det överordnade blockets namn:

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

Mall för underordnat block: Åtkomst till attribut från det överordnade blocket via $context (eller kortformen $c):

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

Det är hela konfigurationen. Inget providesContext i det överordnade blocket, ingen attributmappning och ingen registreringskod. Det underordnade blocket får alla transformerade attribut från det överordnade blocket. Mediefält omvandlas till bilagedata, valfält följer returnFormat och upprepningsfält expanderas helt.

Två typer av kontext

Blockstudio tillhandahåller två kontextvariabler i mallar, och de fyller olika syften:

Variabel Innehåller Användningsområde
$context / $c Attribut från överordnat block (via usesContext) Kommunikation mellan komponenter
$block['context'] / $b['context'] WordPress-loopdata (postId, postType) Loopar i frågeblock

Den första är till för block som kommunicerar med sina överordnade block. Den andra är till för block inuti en Query-loop som behöver veta vilket inlägg de återger. Den här guiden fokuserar på den första typen.

Stöd i redigeraren

Kontextuppdateringar sker reaktivt i redigeraren. När en användare ändrar fältvärdet i ett överordnat block återges alla underordnade block som prenumererar på blockets kontext automatiskt med det nya värdet. Ingen manuell uppdatering behövs.

Sektionsomslag

Det vanligaste kontextmönstret: ett omslagsblock som förser sina underordnade block med temainställningar. Det överordnade blocket har fält för bakgrundsfärg, textfärg och utfyllnad. Underordnade block läser dessa värden för att utforma sig konsekvent.

Överordnat block: sektion

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>

Underordnat block: sektionsrubrik

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>

Det här visar: Rubriken har inget eget färgfält. Den läser sektionens värde för theme från kontexten och anpassar sig efter det. När användaren byter sektionen från “Ljust” till “Mörkt” i redigeraren uppdateras rubrikens textfärg omedelbart.

Egenskapen parent i det underordnade blockets block.json begränsar var blocket kan infogas. Det visas bara i infogaren när användaren befinner sig i ett my-theme/section-block. Detta är valfritt, men rekommenderas för block som bara är meningsfulla inuti ett visst överordnat block.

Underordnat block: sektionstext

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>

Nu följer både rubriken och texten sektionens tema. Användaren väljer ett tema en gång i det överordnade blocket, och alla underordnade block anpassar sig.

Kortnät

Ett överordnat rutnätsblock som styr layoutinställningarna för sina underordnade kort. Det överordnade blocket definierar kolumner och mellanrum. De underordnade blocken använder dessa värden för att förstå sin layoutkontext och anpassa stilen därefter.

Överordnat block: kortnät

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>

Underordnat block: kort

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>

Det här visar: Kortet har inget eget stilfält. Det läser cardStyle från det överordnade rutnätsblocket. När användaren byter rutnätets stil från “Upphöjd” till “Konturerad” uppdateras alla kort i rutnätet samtidigt. Det håller kortens utseende konsekvent utan att användaren behöver uppdatera dem ett och ett.

Attributet template i <InnerBlocks> förifyller rutnätet med tre kort och ger användaren en utgångspunkt.

Pristabell

Ett mer avancerat mönster där det överordnade blocket tillhandahåller gemensam affärslogik (valuta och faktureringsperiod) som underordnade block använder vid visning. Det undviker att samma fält dupliceras för varje prisnivå.

Överordnat block: pristabell

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>

Underordnat block: prisnivå

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>

Det här visar: Valutasymbolen och faktureringsperioden definieras en gång i pristabellen och ärvs av alla prisnivåer. När användaren byter från USD till EUR uppdateras valutasymbolen för alla tre nivåer samtidigt. Utan kontext måste du duplicera valutafältet på varje nivå och hålla dem synkroniserade manuellt.

Kontext i frågeloopar

Det finns en separat typ av kontext som WordPress tillhandahåller i loopar i Query-block. När ett block återges inuti en loop innehåller $block['context'] (eller $b['context']) data för inlägget i den aktuella iterationen:

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>

Detta skiljer sig från kontexten för överordnade block ($context / $c). Loopkontext tillhandahålls av WordPress Core och innehåller bara postId och postType. Du behöver inte usesContext i din block.json för detta. Blockstudio prenumererar automatiskt alla block på postId och postType.

När loopkontext är användbart: Anpassade inläggskort i Query-block, block som visar inläggsmetadata eller block som behöver återges olika för varje inlägg i en loop.

Du kan också komma åt den yttre sidans inläggsdata, oavsett loopkontext:

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

Nästlad kontext

Kontext flödar genom hela blockträdet, inte bara en nivå. Om block A innehåller block B, som innehåller block C, kan C prenumerera på A:s kontext. Det fungerar eftersom WordPress sprider kontext genom varje nivå av InnerBlocks.

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

Rubriken behöver inte vara ett direkt underordnat block till sektionen. Den kan vara nästlad inuti kärnblock (kolumner, grupper och så vidare) och ändå få sektionens kontext. Prenumerationen på usesContext fungerar på alla djup.

Flera överordnade block

Ett underordnat block kan prenumerera på flera överordnade block:

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

Om ett överordnat block saknas i förälderträdet saknas dess nyckel i $context. Använd alltid nullkoalesceringsoperatorn (??) eller kontrollera isset() när du läser kontextvärden, ifall blocket används utanför sitt förväntade överordnade block.

Felresistent kodning

Block som använder kontext bör alltid hantera situationen att det överordnade blocket saknas. En användare kan infoga blocket utanför det avsedda överordnade blocket, eller så kanske det överordnade blocket saknar ett värde för ett visst fält.

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

Om du vill säkerställa att ett underordnat block bara visas inuti sitt överordnade block lägger du till egenskapen parent:

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

Detta tar bort blocket från infogaren när användaren inte befinner sig i ett my-theme/section-block. Utan parent visas blocket överallt, och det är mallens ansvar att hantera saknad kontext på ett smidigt sätt.

Använd parent för block som saknar mening utanför sin behållare (prisnivåer, kort i ett kortnät). Hoppa över det för block som fungerar fristående men får extra stil från ett överordnat block (sektionsrubriker som också kan användas separat).

Tips

Kontext är skrivskyddad. Underordnade block kan inte ändra det överordnade blockets attribut via kontext. Data flödar nedåt, aldrig uppåt. Om ett underordnat block behöver kommunicera något till sitt överordnade block behöver du ett annat tillvägagångssätt (till exempel delat servertillstånd via Interactivity API eller inläggsmetadata).

Alla attribut tillhandahålls. Blockstudio tillhandahåller alla attribut från det överordnade blocket, inte bara de du väljer. Det innebär att det underordnade blocket kan komma åt alla fält som det överordnade blocket definierar. Om det överordnade blocket senare får ett nytt fält får underordnade block automatiskt åtkomst till det utan konfigurationsändringar.

Transformerade värden. Kontextvärden passerar genom attributtransformeringskedjan i Blockstudio. Filfält innehåller alla bilagedata (url, alt, width, height), valfält följer returnFormat och upprepningsfält expanderas rekursivt. Du får samma datastruktur som $a i mallen för det överordnade blocket.

Reaktivitet i redigeraren. När en användare ändrar ett fält i det överordnade blocket i redigeraren återges underordnade block automatiskt igen. Detta använder WordPresss inbyggda kontextspridning med en React useEffect som upptäcker kontextändringar och utlöser en återgivning av det underordnade blocket på serversidan.

Håll kontexten slimmad. Även om Blockstudio automatiskt tillhandahåller alla attribut från det överordnade blocket bör underordnade block bara läsa de värden de faktiskt behöver. Det handlar inte om prestanda (data finns redan där), utan om tydlig kod. Dokumentera vilka fält från det överordnade blocket ett underordnat block är beroende av, så att framtida utvecklare förstår sambandet.

Nästa steg

  • Kontextreferens: mallvariabler, loopkontext och datastrukturen $block.
  • InnerBlocks: komponenten <InnerBlocks />, allowedBlocks, mallar och filtret för frontend-omslaget.
  • Guide till Interactivity: för reaktivitet på klientsidan mellan block (Interactivity API hanterar det som kontext inte kan: kommunikation från underordnat block till överordnat, tillstånd mellan block och uppdateringar som utlöses av användaren).