Siirry sisältöön

Lohkokonteksti ja viestintä

Useimmat lohkot ovat itsenäisiä. Niillä on omat kenttänsä ja mallipohjansa, eivätkä ne välitä ympärillään olevasta sisällöstä. Jotkin komponentit ovat kuitenkin luonteeltaan hierarkkisia: korttiruudukossa ylälohko hallitsee sarakkeiden määrää ja välistystä, hinnoittelutaulukossa ylälohko määrittää valuutan ja osion kääre kertoo alilohkoille, käytetäänkö vaaleaa vai tummaa teemaa.

WordPress tarjoaa tätä varten lohkokontekstin API. Ylälohko tuo osan tiedoistaan saataville, ja alilohkot tilaavat ne. Kun ylälohko muuttuu, alilohkot päivittyvät automaattisesti. Blockstudio yksinkertaistaa tätä huomattavasti: sinun ei tarvitse määrittää providesContexta lainkaan. Jokainen Blockstudio-lohko tuo automaattisesti kaikki attribuuttinsa saataville kontekstina. Alilohkojen tarvitsee vain lisätä yksi rivi block.jsononsa tilatakseen kontekstin.

Tässä oppaassa rakennetaan neljä käytännön komponenttimallia, joissa käytetään kontekstia. Kukin niistä havainnollistaa erilaista viestintätarvetta.

Miten konteksti toimii Blockstudiossa

Tavallisessa WordPressssa kukin ylälohkon attribuutti on yhdistettävä erikseen kontekstiavaimeen providesContextssa, minkä jälkeen nämä avaimet luetellaan alilohkon usesContextssa. Blockstudio poistaa ensimmäisen vaiheen kokonaan.

Ylälohko: Ei vaadi määrityksiä. Jokainen Blockstudio-lohko tuo automaattisesti kaikki attribuuttinsa saataville lohkon nimellä.

Alilohko: Lisää usesContext ylälohkon nimellä:

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

Alilohkon mallipohja: Käytä ylälohkon attribuutteja $contextn (tai lyhyemmin $c):

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

Siinä on kaikki tarvittava. Ylälohkoon ei lisätä providesContexta, attribuutteja ei tarvitse yhdistää eikä rekisteröintikoodia kirjoittaa. Alilohko saa kaikki ylälohkon muunnetut attribuutit: mediat kentät ratkaistaan liitetiedoiksi, valintakentissä noudatetaan returnFormata ja toistimet laajennetaan kokonaan.

Kaksi kontekstityyppiä

Blockstudio tarjoaa mallipohjissa kaksi kontekstimuuttujaa, joilla on eri käyttötarkoitukset:

Muuttuja Sisältö Käyttötarkoitus
$context / $c Ylälohkon attribuutit (usesContextn kautta) Komponenttien välinen viestintä
$block['context'] / $b['context'] WordPress-silmukan tiedot (postId, postType) Kyselylohkon silmukat

Ensimmäistä käytetään lohkojen viestintään ylälohkojensa kanssa. Toinen on lohkoille, jotka ovat kyselysilmukan sisällä ja joiden on tiedettävä, mitä artikkelia ne parhaillaan näyttävät. Tässä oppaassa keskitytään ensimmäiseen tyyppiin.

Editorin tuki

Kontekstin päivitykset reagoivat muutoksiin editorissa. Kun käyttäjä muuttaa ylälohkon kentän arvoa, kaikki sen kontekstia tilaavat alilohkot hahmonnetaan automaattisesti uudelleen uudella arvolla. Manuaalista päivitystä ei tarvita.

Osion kääre

Yleisin kontekstimalli on käärelohko, joka välittää teema-asetukset alilohkoilleen. Ylälohkon kentissä määritetään taustaväri, tekstin väri ja täyte. Alilohkot lukevat nämä arvot ja muotoilevat itsensä niiden mukaisesti.

Ylälohko: osio

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>

Alilohko: osion otsikko

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>

Mitä tämä havainnollistaa: Otsikolla ei ole omaa värikenttää. Se lukee osion theme-arvon kontekstista ja mukautuu sen mukaan. Kun käyttäjä vaihtaa osion teemaksi editorissa “Vaalea”-teeman sijaan “Tumma”, otsikon tekstin väri päivittyy heti.

Lapsen parent-ominaisuus kohteen block.json sisällä rajoittaa, mihin lohko voidaan lisätä. Se näkyy lisäystyökalussa vain, kun käyttäjä on my-theme/section-lohkon sisällä. Tämä on valinnainen, mutta suositeltava lohkoille, joista on hyötyä vain tietyn ylätason lohkon sisällä.

Alilohko: osion teksti

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>

Nyt sekä otsikko että teksti mukautuvat osion teemaan. Käyttäjä valitsee teeman kerran ylälohkossa, ja kaikki alilohkot mukautuvat siihen.

Korttiruudukko

Ruudukon ylälohko hallitsee korttialilohkojensa asetteluasetuksia. Se määrittää sarakkeet ja välistyksen. Alilohkot käyttävät näitä arvoja hahmottaakseen asettelukontekstinsa ja mukauttaakseen tyylinsä sen mukaan.

Ylälohko: korttiruudukko

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>

Alilohko: kortti

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>

Mitä tämä havainnollistaa: Kortilla ei ole omaa tyylikenttää. Se lukee cardStylen ruudukon ylälohkosta. Kun käyttäjä vaihtaa ruudukon tyyliksi “Kohotettu”-tyylin sijaan “Ääriviiva”, kaikki ruudukon kortit päivittyvät kerralla. Näin kortit pysyvät visuaalisesti yhtenäisinä ilman, että käyttäjän tarvitsee päivittää jokaista erikseen.

<InnerBlocks>n template-attribuutti lisää ruudukkoon valmiiksi kolme korttia, jotta käyttäjä pääsee alkuun.

Hinnoittelutaulukko

Tässä edistyneemmässä mallissa ylälohko tarjoaa yhteisen liiketoimintalogiikan, kuten valuutan ja laskutusjakson, joita alilohkot käyttävät esityksessään. Näin samoja kenttiä ei tarvitse kopioida jokaiselle hintatasolle.

Ylälohko: hinnoittelutaulukko

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>

Alilohko: hintataso

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>

Mitä tämä havainnollistaa: Valuuttasymboli ja laskutusjakso määritetään hinnoittelutaulukossa kerran, ja jokainen hintataso perii ne. Kun käyttäjä vaihtaa valuutaksi USD:n sijaan EUR:n, kaikkien kolmen hintatason valuuttasymboli päivittyy samanaikaisesti. Ilman kontekstia valuuttakenttä pitäisi kopioida jokaiseen tasoon ja pitää ne manuaalisesti synkronoituina.

Kyselysilmukan konteksti

WordPress tarjoaa kyselylohkon silmukoiden sisällä erillisen kontekstityypin. Kun lohko hahmonnetaan silmukan sisällä, $block['context'] (tai $b['context']) sisältää nykyisen iteraation artikkelitiedot:

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>

Tämä eroaa ylätason lohkon kontekstista ($context / $c). Silmukan kontekstin tarjoaa WordPress-ydin, ja se sisältää vain postId ja postType. Tätä varten usesContext ei tarvitse lisätä block.json-tiedostoosi. Blockstudio tilaa jokaisen lohkon automaattisesti kohteisiin postId ja postType.

Milloin silmukkakontekstista on hyötyä: mukautetut artikkelikortit kyselylohkojen sisällä, artikkelin metatietoja näyttävät lohkot tai mikä tahansa lohko, jonka esityksen on vaihduttava silmukan artikkelin mukaan.

Voit käyttää myös ulomman sivun artikkelitietoja silmukkakontekstista riippumatta:

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

Sisäkkäinen konteksti

Konteksti kulkee koko lohkopuun läpi, ei vain yhtä tasoa. Jos lohko A sisältää lohkon B, joka puolestaan sisältää lohkon C, C voi tilata A:n kontekstin. Tämä toimii, koska WordPress välittää kontekstin InnerBlocks-lohkojen kaikille tasoille.

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

Otsikon ei tarvitse olla osion suora alilohko. Se voi olla sisäkkäin ydinklohkoissa, kuten palstoissa tai ryhmissä, ja saada silti osion kontekstin. usesContext-tilaus toimii millä tahansa sisäkkäisyyden tasolla.

Useita ylälohkoja

Alilohko voi tilata useiden ylälohkojen kontekstin:

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

Jos ylälohkoa ei löydy edeltävien lohkojen puusta, sen avain puuttuu $contextsta. Käytä kontekstiarvoja lukiessasi aina null-arvon yhdistämisoperaattoria (??) tai tarkista isset(), jos lohkoa käytetään odotetun ylälohkon ulkopuolella.

Virhetilanteiden käsittely

Kontekstia käyttävien lohkojen on aina varauduttava siihen, että ylälohko puuttuu. Käyttäjä voi lisätä lohkon sille tarkoitetun ylälohkon ulkopuolelle, tai ylälohkolle ei ehkä ole asetettu tietyn kentän arvoa.

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

Jos haluat varmistaa, että alilohko näkyy vain ylälohkon sisällä, lisää parent-ominaisuus:

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

Tämä piilottaa lohkon lisäysvalikosta, kun käyttäjä ei ole my-theme/section-lohkon sisällä. Ilman parenta lohko näkyy kaikkialla, ja mallipohjan vastuulla on käsitellä puuttuva konteksti asianmukaisesti.

Käytä parenta lohkoille, jotka eivät toimi säiliönsä ulkopuolella, kuten hintatasoille ja korttiruudukon kohteille. Jätä se pois lohkoilta, jotka toimivat itsenäisesti mutta saavat ylälohkolta lisätyylejä, kuten osion otsikoilta, joita voi käyttää myös erillään.

Vinkkejä

Konteksti on vain luettavissa. Alilohkot eivät voi muuttaa ylälohkon attribuutteja kontekstin kautta. Tiedot kulkevat alaspäin, eivät koskaan ylöspäin. Jos alilohkon on viestittävä ylälohkolle, tarvitaan toinen ratkaisu, kuten yhteinen palvelintila Interactivity APIn kautta tai artikkelin metatiedot.

Kaikki attribuutit ovat saatavilla. Blockstudio tarjoaa kaikki ylälohkon attribuutit, ei vain valitsemiasi. Siksi alilohko voi käyttää mitä tahansa ylälohkon määrittämää kenttää. Jos ylälohkoon lisätään myöhemmin uusi kenttä, alilohkot saavat sen automaattisesti käyttöönsä ilman määritysmuutoksia.

Muunnetut arvot. Kontekstiarvot kulkevat Blockstudion attribuuttien muunnosputken läpi. Tiedostokentät sisältävät täydet liitetiedot (url, alt, width, height), valintakentissä noudatetaan returnFormata ja toistimet laajennetaan rekursiivisesti. Tietorakenne on sama kuin $an ylälohkon mallipohjassa.

Editorin reagointi. Kun käyttäjä muuttaa ylälohkon kenttää editorissa, alilohkot hahmonnetaan automaattisesti uudelleen. Tämä käyttää WordPressn sisäänrakennettua kontekstin välitystä ja React useEffecta, joka tunnistaa kontekstimuutokset ja käynnistää alilohkon uudelleenhahmonnuksen palvelimella.

Pidä konteksti suppeana. Vaikka Blockstudio tarjoaa automaattisesti kaikki ylälohkon attribuutit, alilohkojen kannattaa lukea vain tarvitsemansa arvot. Kyse ei ole suorituskyvystä, sillä tiedot ovat jo saatavilla, vaan koodin selkeydestä. Dokumentoi, mistä ylälohkon kentistä alilohko riippuu, jotta suhde on selvä tuleville kehittäjille.

Seuraavat vaiheet

  • Kontekstiviite: mallipohjamuuttujat, silmukkakonteksti ja $block-tietorakenne.
  • InnerBlocks: <InnerBlocks />-komponentti, allowedBlocks, mallipohjat ja käyttöliittymän kääreen suodatin.
  • Interactivity-opas: lohkojen väliseen reaktiivisuuteen asiakaspuolella. Interactivity API käsittelee sen, mihin konteksti ei pysty: viestintää alilohkolta ylälohkolle, lohkojen välistä tilaa ja käyttäjän käynnistämiä päivityksiä.