Gå til indhold

Blokkontekst og kommunikation

De fleste blokke er selvstændige. De har deres egne felter og deres egen skabelon, og de er ligeglade med, hvad der omgiver dem. Men nogle komponenter er naturligt hierarkiske: en kortrække, hvor den overordnede blok styrer antallet af kolonner og afstanden mellem dem, en pristabel, hvor den overordnede blok angiver valutaen, eller et sektionsomslag, der fortæller de underordnede blokke, om de skal bruge et lyst eller mørkt tema.

WordPress giver en blokkontekst API til dette. En overordnet blok eksponerer nogle af sine data, og underordnede blokke abonnerer på dem. Når den overordnede blok ændres, opdateres de underordnede automatisk. Blockstudio gør dette meget enklere: du behøver slet ikke konfigurere providesContext. Hver Blockstudio-blok leverer automatisk alle sine attributter som kontekst. Underordnede blokke skal blot have én linje i deres block.json for at abonnere.

Denne guide gennemgår fire virkelige komponentmønstre, der bruger kontekst, og viser hver især et forskelligt kommunikationsbehov.

Sådan fungerer kontekst i Blockstudio

I standard-WordPress skal du eksplicit knytte hver attribut i den overordnede blok til en kontekstnøgle i providesContext og derefter angive disse nøgler i den underordnede bloks usesContext. Blockstudio fjerner det første trin helt.

Overordnet blok: Ingen konfiguration nødvendig. Hver Blockstudio-blok stiller automatisk alle sine attributter til rådighed under sit bloknavn.

Underordnet blok: Tilføj usesContext med navnet på den overordnede blok:

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

Underordnet skabelon: Få adgang til den overordnede bloks attributter via $context (eller den korte form $c):

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

Det er hele opsætningen. Ingen providesContext i den overordnede blok, ingen attributtilknytning og ingen registreringskode. Den underordnede blok modtager alle den overordnede bloks transformerede attributter, så mediefelter opløses til vedhæftningsdata, select-felter følger returnFormat, og repeatere foldes helt ud.

To typer kontekst

Blockstudio stiller to kontekstvariabler til rådighed i skabeloner, og de tjener forskellige formål:

Variabel Indeholder Anvendelse
$context / $c Den overordnede bloks attributter (via usesContext) Kommunikation mellem komponenter
$block['context'] / $b['context'] WordPress-loopdata (postId, postType) Query-blokloops

Den første type bruges, når blokke kommunikerer med deres overordnede blokke. Den anden bruges til blokke inde i et Query-loop, som skal vide, hvilket indlæg de gengiver. Denne guide fokuserer på den første type.

Understøttelse i editoren

Kontektopdateringer er reaktive i editoren. Når en bruger ændrer en feltværdi i en overordnet blok, gengives alle underordnede blokke, der abonnerer på den overordnede bloks kontekst, automatisk igen med den nye værdi. Det er ikke nødvendigt at opdatere manuelt.

Sektionsomslag

Det mest almindelige kontekst mønster: en omslagsblok, der giver sine underordnede blokke temaindstillinger. Den overordnede blok har felter til baggrundsfarve, tekstfarve og indvendig afstand. De underordnede blokke læser værdierne for at style sig ensartet.

Overordnet: Section

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>

Underordnet: Section Heading

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>

Dette demonstrerer: Overskriften har ikke sit eget farvefelt. Den læser sektionens theme-værdi fra konteksten og tilpasser sig. Når brugeren skifter sektionen fra “Light” til “Dark” i editoren, opdateres overskriftens tekstfarve med det samme.

Egenskaben parent i den underordnede bloks block.json begrænser, hvor blokken kan indsættes. Den vises kun i indsætteren, når brugeren befinder sig i en my-theme/section-blok. Det er valgfrit, men anbefales til blokke, der kun giver mening inde i en bestemt overordnet blok.

Underordnet: Section Text

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 reagerer både overskriften og teksten på sektionens tema. Brugeren vælger et tema én gang på den overordnede blok, og alle underordnede blokke tilpasser sig.

Kortrække

En overordnet gitterblok, der styrer layoutindstillingerne for sine underordnede kort. Den overordnede blok angiver kolonner og afstand. De underordnede blokke bruger værdierne til at forstå layoutkonteksten og tilpasse deres styling derefter.

Overordnet: Card Grid

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>

Underordnet: 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>

Dette demonstrerer: Kortet har intet stilfelt. Det læser cardStyle fra den overordnede gitterblok. Når brugeren skifter gitteret fra “Elevated” til “Outlined”, opdateres alle kort i gitteret på én gang. Det holder kortenes udseende ensartet uden at tvinge brugeren til at opdatere hvert kort individuelt.

Attributten template på <InnerBlocks> udfylder gitteret på forhånd med tre kort og giver brugeren et udgangspunkt.

Pristabel

Et mere avanceret mønster, hvor den overordnede blok stiller fælles forretningslogik til rådighed (valuta, faktureringsperiode), som de underordnede blokke bruger i deres visning. Det undgår at duplikere de samme felter på hvert prisniveau.

Overordnet: Pricing Table

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>

Underordnet: Pricing Tier

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>

Dette demonstrerer: Valutasymbolet og faktureringsperioden defineres én gang i pristabellen og nedarves af hvert prisniveau. Når brugeren skifter fra USD til EUR, opdateres valutasymbolet for alle tre niveauer samtidigt. Uden kontekst skulle du duplikere valutafeltet på hvert niveau og holde dem synkroniserede manuelt.

Kontekst i Query-loops

Der findes en separat type kontekst, som WordPress stiller til rådighed inde i Query-blokloops. Når en blok gengives i et loop, indeholder $block['context'] (eller $b['context']) dataene for indlægget i den aktuelle iteration:

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>

Dette adskiller sig fra konteksten for den overordnede blok ($context / $c). Loopkonteksten stilles til rådighed af WordPress core og indeholder kun postId og postType. Du behøver ikke usesContext i din block.json til dette. Blockstudio abonnerer automatisk på postId og postType for hver blok.

Hvor loopkontekst er nyttig: Brugerdefinerede indlægskort inde i Query-blokke, blokke, der viser indlægsmetadata, eller enhver blok, der skal gengives forskelligt for hvert indlæg i et loop.

Du kan også få adgang til den ydre sides indlægsdata, uanset loopkonteksten:

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

Indlejret kontekst

Kontekst flyder gennem hele bloktræet, ikke kun ét niveau. Hvis blok A indeholder blok B, som indeholder blok C, kan C abonnere på A’s kontekst. Det fungerer, fordi WordPress viderefører konteksten gennem alle niveauer af InnerBlocks.

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

Overskriften behøver ikke være en direkte underordnet blok af sektionen. Den kan være indlejret i core-blokke (kolonner, grupper osv.) og stadig modtage sektionens kontekst. Abonnementet på usesContext fungerer i alle dybder.

Flere overordnede blokke

En underordnet blok kan abonnere på flere overordnede blokke:

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

Hvis en overordnet blok ikke findes i forfædretræet, vil dens nøgle mangle i $context. Brug altid null-coalescing-operatoren (??), eller kontrollér isset(), når du læser kontekstværdier, hvis blokken bruges uden for sin forventede overordnede blok.

Robust kodning

Blokke, der bruger kontekst, bør altid håndtere situationen, hvor den overordnede blok mangler. En bruger kan indsætte blokken uden for dens tilsigtede overordnede blok, eller den overordnede blok har muligvis ikke en værdi angivet for et bestemt felt.

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

Hvis du vil sikre, at en underordnet blok kun vises inde i sin overordnede blok, skal du tilføje egenskaben parent:

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

Dermed fjernes blokken fra indsætteren, når brugeren ikke befinder sig i en my-theme/section-blok. Uden parent vises blokken overalt, og det er din skabelons ansvar at håndtere manglende kontekst på en hensigtsmæssig måde.

Brug parent til blokke, der er meningsløse uden for deres beholder (prisniveauer, kortrækkeelementer). Undlad den til blokke, der fungerer selvstændigt, men får ekstra styling fra en overordnet blok (sektionsoverskrifter, der også kan bruges uafhængigt).

Tips

Kontekst er skrivebeskyttet. Underordnede blokke kan ikke ændre den overordnede bloks attributter gennem konteksten. Data flyder nedad, aldrig opad. Hvis en underordnet blok skal kommunikere noget til sin overordnede blok, har du brug for en anden løsning (f.eks. delt servertillstand via Interactivity API eller indlægsmetadata).

Alle attributter stilles til rådighed. Blockstudio stiller alle attributter i den overordnede blok til rådighed, ikke kun dem, du vælger. Det betyder, at den underordnede blok kan få adgang til alle felter, som den overordnede blok definerer. Hvis den overordnede blok senere får et nyt felt, får de underordnede blokke automatisk adgang til det uden ændringer i konfigurationen.

Transformerede værdier. Kontekstværdier gennemgår Blockstudios attributtransformationspipeline. Filfelter indeholder de fulde vedhæftningsdata (url, alt, width, height), select-felter følger returnFormat, og repeatere foldes rekursivt ud. Du får samme datastruktur som $a i den overordnede skabelon.

Reaktivitet i editoren. Når en bruger ændrer et felt i den overordnede blok i editoren, gengives de underordnede blokke automatisk igen. Dette bruger WordPresss indbyggede kontekstvideregivelse med en React useEffect, der registrerer kontekstændringer og udløser en serverbaseret gengivelse af den underordnede blok.

Hold konteksten enkel. Selvom Blockstudio automatisk stiller alle attributter i den overordnede blok til rådighed, bør underordnede blokke kun læse de værdier, de faktisk har brug for. Det handler ikke om ydeevne (dataene er der allerede), men om tydelig kode. Dokumentér, hvilke felter i den overordnede blok en underordnet blok afhænger af, så fremtidige udviklere forstår relationen.

Næste trin

  • Kontekstreference: skabelonvariabler, loopkontekst og datastrukturen $block.
  • InnerBlocks: komponenten <InnerBlocks />, allowedBlocks, skabeloner og filteret til frontend-omslaget.
  • Interactivity-guide: til reaktivitet på klientsiden mellem blokke (Interactivity API håndterer det, som kontekst ikke kan: kommunikation fra underordnet til overordnet blok, tilstand på tværs af blokke og brugerudløste opdateringer).