Pāriet uz saturu

Bloku konteksts un saziņa

Lielākā daļa bloku ir pašpietiekami. Tiem ir savi lauki un veidne, un tiem nav svarīgi, kas atrodas apkārt. Taču daži komponenti dabiski veido hierarhiju: karšu režģis, kur vecākbloks nosaka kolonnu skaitu un atstarpes, cenu tabula, kur vecākbloks iestata valūtu, un sadaļas ietvars, kas bērnblokiem norāda, vai izmantot gaišo vai tumšo tēmu.

WordPress nodrošina bloku konteksta API. Vecākbloks atklāj daļu savu datu, un bērnbloki tiem abonē. Kad vecākbloks mainās, bērnbloki tiek automātiski atjaunināti. Blockstudio to ievērojami vienkāršo: jums vispār nav jākonfigurē providesContext. Katrs Blockstudio bloks automātiski nodrošina visus savus atribūtus kā kontekstu. Bērnblokam abonēšanai pietiek ar vienu rindu tā block.json.

Šajā ceļvedī ir izveidoti četri reālās pasaules komponentu modeļi, kuros izmantots konteksts, un katrs no tiem demonstrē atšķirīgu saziņas vajadzību.

Kā konteksts darbojas Blockstudio

Standarta WordPress gadījumā katrs vecākbloka atribūts ir skaidri jāsaista ar konteksta atslēgu providesContext, pēc tam šīs atslēgas jānorāda bērnbloka usesContext. Blockstudio pilnībā novērš pirmo darbību.

Vecākbloks: konfigurācija nav vajadzīga. Katrs Blockstudio bloks automātiski nodrošina visus savus atribūtus ar bloka nosaukumu.

Bērnbloks: pievienojiet usesContext ar vecākbloka nosaukumu:

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

Bērnbloka veidne: piekļūstiet vecākbloka atribūtiem, izmantojot $context (vai saīsinājumu $c):

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

Ar to arī visa iestatīšana ir pabeigta. Vecākblokā nav vajadzīgs providesContext, atribūtu kartēšana vai reģistrācijas kods. Bērnbloks saņem visus vecākbloka pārveidotos atribūtus: multivides lauki tiek atrisināti līdz pielikuma datiem, atlases lauki ievēro returnFormat, un atkārtotāji tiek pilnībā izvērsti.

Divi konteksta veidi

Blockstudio veidnēs nodrošina divus konteksta mainīgos, un katram ir savs nolūks:

Mainīgais Saturs Lietojums
$context / $c Vecākbloka atribūti (ar usesContext starpniecību) Saziņa starp komponentiem
$block['context'] / $b['context'] WordPress cikla dati (postId, postType) Vaicājuma bloka cikli

Pirmais veids ļauj blokiem sazināties ar to vecākblokiem. Otrais ir paredzēts blokiem vaicājuma ciklā, kam jāzina, kuru ierakstu tie attēlo. Šajā ceļvedī aplūkots pirmais veids.

Redaktora atbalsts

Redaktorā konteksta atjauninājumi notiek reaģējoši. Kad lietotājs maina vecākbloka lauka vērtību, visi bērnbloki, kas abonē šī vecākbloka kontekstu, tiek automātiski atkārtoti renderēti ar jauno vērtību. Manuāla atsvaidzināšana nav vajadzīga.

Sadaļas ietvars

Visizplatītākais konteksta modelis: ietvara bloks, kas nodrošina bērnblokiem tēmas iestatījumus. Vecākblokā ir fona krāsas, teksta krāsas un iekšējās atkāpes lauki. Bērnbloki nolasa šīs vērtības, lai to stils būtu saskaņots.

Vecākbloks: sadaļa

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>

Bērnbloks: sadaļas virsraksts

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>

Ko tas demonstrē: Virsrakstam nav sava krāsas lauka. Tas nolasa sadaļas theme vērtību no konteksta un pielāgojas tai. Kad redaktorā sadaļas tēma tiek pārslēgta no “Light” uz “Dark”, virsraksta teksta krāsa mainās nekavējoties.

Bērnbloka block.json īpašība parent ierobežo vietas, kur šo bloku var ievietot. Tas ievietotājā parādās tikai tad, kad lietotājs atrodas my-theme/section blokā. Šis iestatījums nav obligāts, taču to ieteicams izmantot blokiem, kam ir jēga tikai konkrēta vecākbloka iekšienē.

Bērnbloks: sadaļas teksts

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>

Tagad gan virsraksts, gan teksts pielāgojas sadaļas tēmai. Lietotājs tēmu izvēlas vienreiz vecākblokā, un katrs bērnbloks tai pielāgojas.

Karšu režģis

Režģa vecākbloks kontrolē savu karšu bērnbloku izkārtojuma iestatījumus. Vecākbloks nosaka kolonnu skaitu un atstarpes. Bērnbloki izmanto šīs vērtības, lai izprastu savu izkārtojuma kontekstu un atbilstoši pielāgotu stilu.

Vecākbloks: karšu režģis

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>

Bērnbloks: karte

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>

Ko tas demonstrē: Kartei nav sava stila lauka. Tā nolasa cardStyle no režģa vecākbloka. Kad lietotājs pārslēdz režģi no “Elevated” uz “Outlined”, visas režģa kartes tiek atjauninātas vienlaikus. Tādējādi kartēm tiek saglabāts vizuāls saskaņots izskats, neliekot lietotājam atjaunināt katru karti atsevišķi.

<InnerBlocks> atribūts, kas norādīts template, sākotnēji aizpilda režģi ar trim kartēm, nodrošinot lietotājam sākuma punktu.

Cenu tabula

Sarežģītāks modelis, kurā vecākbloks nodrošina kopīgu biznesa loģiku (valūtu, norēķinu periodu), ko bērnbloki izmanto attēlošanai. Tā var izvairīties no vienu un to pašu lauku dublēšanas katrā cenu līmenī.

Vecākbloks: cenu tabula

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>

Bērnbloks: cenu līmenis

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>

Ko tas demonstrē: Valūtas simbols un norēķinu periods tiek definēti vienreiz cenu tabulā un pārmantoti visos līmeņos. Kad lietotājs pārslēdz valūtu no USD uz EUR, visu trīs līmeņu valūtas simboli mainās vienlaikus. Bez konteksta valūtas lauks būtu jādublē katrā līmenī un tie manuāli jāsaskaņo.

Vaicājuma cikla konteksts

Pastāv atsevišķs konteksta veids, ko WordPress nodrošina vaicājuma bloka ciklos. Kad bloks tiek renderēts ciklā, $block['context'] (vai $b['context']) satur pašreizējās iterācijas ieraksta datus:

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>

Tas atšķiras no vecākbloka konteksta ($context / $c). Cikla kontekstu nodrošina WordPress kodols, un tajā ir tikai postId un postType. Šim nolūkam usesContext jūsu block.json nav vajadzīgs. Blockstudio automātiski abonē postId un postType katram blokam.

Kur noder cikla konteksts: pielāgotām ierakstu kartēm vaicājuma blokos, blokiem, kas attēlo ieraksta metadatus, un jebkuram blokam, kam ciklā katram ierakstam jāattēlo atšķirīgs saturs.

Varat piekļūt arī ārējās lapas ieraksta datiem neatkarīgi no cikla konteksta:

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

Ligzdots konteksts

Konteksts tiek nodots pa visu bloku koku, nevis tikai vienu līmeni tālāk. Ja blokā A ir bloks B, kurā savukārt ir bloks C, bloks C var abonēt bloka A kontekstu. Tas darbojas tāpēc, ka WordPress nodod kontekstu caur visiem InnerBlocks līmeņiem.

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

Virsrakstam nav jābūt tiešam sadaļas bērnblokam. Tas var būt ligzdots pamata blokos (kolonnās, grupās u. c.) un joprojām saņemt sadaļas kontekstu. usesContext abonements darbojas jebkurā dziļumā.

Vairāki vecākbloki

Bērnbloks var abonēt vairākus vecākblokus:

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

Ja vecākbloks nav atrasts priekšteču kokā, tā atslēgas nebūs $context. Lasot konteksta vērtības, vienmēr izmantojiet nulles apvienošanas operatoru (??) vai pārbaudiet isset(), ja bloks tiek izmantots ārpus paredzētā vecākbloka.

Aizsargājoša programmēšana

Blokiem, kas izmanto kontekstu, vienmēr jāapstrādā gadījums, kad trūkst vecākbloka. Lietotājs var ievietot bloku ārpus tam paredzētā vecākbloka, vai arī vecākblokam var nebūt konkrētā lauka vērtības.

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

Ja vēlaties nodrošināt, lai bērnbloks parādītos tikai sava vecākbloka iekšienē, pievienojiet īpašību parent:

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

Tādējādi bloks tiek noņemts no ievietotāja, kad lietotājs neatrodas my-theme/section blokā. Bez parent bloks ir redzams visur, un veidnei ir pašai korekti jāapstrādā trūkstoša konteksta gadījumi.

Izmantojiet parent blokiem, kam nav jēgas ārpus to ietvara (cenu līmeņiem, karšu režģa elementiem). Neizmantojiet to blokiem, kas darbojas arī atsevišķi, bet iegūst papildu stilu no vecākbloka (sadaļas virsrakstiem, ko var izmantot arī neatkarīgi).

Padomi

Konteksts ir tikai lasāms. Bērnbloki nevar mainīt vecākbloka atribūtus, izmantojot kontekstu. Dati plūst uz leju, nekad uz augšu. Ja bērnblokam kaut kas jāpaziņo vecākblokam, ir vajadzīga cita pieeja (piemēram, koplietots servera stāvoklis, izmantojot Interactivity API, vai ieraksta metadati).

Tiek nodrošināti visi atribūti. Blockstudio nodrošina visus vecākbloka atribūtus, ne tikai atlasītos. Tādējādi bērnbloks var piekļūt jebkuram vecākblokā definētam laukam. Ja vēlāk vecākblokam pievienosiet lauku, bērnbloki tam automātiski varēs piekļūt bez konfigurācijas izmaiņām.

Pārveidotas vērtības. Konteksta vērtības tiek apstrādātas Blockstudio atribūtu pārveidošanas konveijerā. Failu lauki satur pilnus pielikumu datus (url, alt, width, height), atlases lauki ievēro returnFormat, un atkārtotāji tiek izvērsti rekursīvi. Iegūstat tādu pašu datu struktūru kā $a vecākbloka veidnē.

Redaktora reaģētspēja. Kad lietotājs redaktorā maina vecākbloka lauku, bērnbloki tiek automātiski atkārtoti renderēti. Šim nolūkam tiek izmantota WordPress iebūvētā konteksta izplatīšana ar React useEffect, kas nosaka konteksta izmaiņas un izraisa bērnbloka atkārtotu renderēšanu servera pusē.

Uzturiet kontekstu pēc iespējas vienkāršu. Lai gan Blockstudio automātiski nodrošina visus vecākbloka atribūtus, bērnblokiem vajadzētu nolasīt tikai vajadzīgās vērtības. Tas nav veiktspējas jautājums (dati jau ir pieejami), bet gan koda skaidrības jautājums. Dokumentējiet, no kuriem vecākbloka laukiem ir atkarīgs bērnbloks, lai nākamie izstrādātāji izprastu šo saistību.

Nākamie soļi

  • Konteksta atsauce: veidņu mainīgie, cikla konteksts un $block datu struktūra.
  • InnerBlocks: komponents <InnerBlocks />, allowedBlocks, veidnes un priekšgala ietvara filtrs.
  • Interactivity ceļvedis: reaģētspējai starp blokiem klienta pusē (Interactivity API nodrošina to, ko konteksts nespēj: saziņu no bērna uz vecāku, starpbloku stāvokli un lietotāja ierosinātus atjauninājumus).