Blokk-környezet és kommunikáció
A legtöbb blokk önálló egység. Saját mezőik és sablonjuk van, és nem törődnek azzal, mi veszi őket körül. Egyes komponensek azonban természetüknél fogva hierarchikusak: például egy kártyarács, amelynél a szülő szabályozza az oszlopok számát és a térközt; egy ártáblázat, amelynél a szülő állítja be a pénznemet; vagy egy szekcióburkoló, amely jelzi a gyermekblokkoknak, hogy világos vagy sötét témát használjanak.
WordPress ehhez blokk-környezet API biztosít. A szülőblokk elérhetővé teszi egyes adatait, a gyermekblokkok pedig feliratkoznak rájuk. Amikor a szülő megváltozik, a gyermekek automatikusan frissülnek. Blockstudio ezt jelentősen leegyszerűsíti: egyáltalán nem kell beállítania a providesContext-t. Minden Blockstudio blokk automatikusan elérhetővé teszi az összes attribútumát környezetként. A gyermekblokkoknak csak egy sort kell hozzáadniuk a block.json-jukhoz a feliratkozáshoz.
Ez az útmutató négy valós komponensmintát mutat be, amelyek környezetet használnak, és mindegyik más kommunikációs igényt szemléltet.
A környezet működése a Blockstudio rendszerben
A szabványos WordPress rendszerben minden szülőattribútumot kifejezetten hozzá kell rendelnie egy környezeti kulcshoz a providesContext fájlban, majd fel kell sorolnia ezeket a kulcsokat a gyermek usesContext fájljában. A Blockstudio teljesen elhagyja az első lépést.
Szülőblokk: Nincs szükség beállításra. Minden Blockstudio blokk automatikusan elérhetővé teszi az összes attribútumát a blokk neve alatt.
Gyermekblokk: Adja hozzá a usesContext elemet a szülőblokk nevével:
{
"usesContext": ["my-theme/parent-block"]
}
Gyermeksablon: A szülő attribútumai a $context (vagy a rövidített $c) segítségével érhetők el:
<?php $parent = $context['my-theme/parent-block']; ?>
<p>Parent says: <?php echo esc_html( $parent['message'] ); ?></p>
Ennyi az egész beállítás. Nincs szükség providesContext-re a szülőben, attribútum-hozzárendelésre vagy regisztrációs kódra. A gyermek megkapja a szülő összes átalakított attribútumát: a média mezői mellékletadatokká oldódnak fel, a választómezők figyelembe veszik a returnFormat beállítást, az ismétlők pedig teljesen kibontódnak.
A környezet két típusa
A Blockstudio két környezeti változót biztosít a sablonokban, és ezek eltérő célokat szolgálnak:
| Változó | Tartalma | Felhasználási terület |
|---|---|---|
$context / $c |
Szülőblokk attribútumai (a usesContext segítségével) |
Kommunikáció a komponensek között |
$block['context'] / $b['context'] |
WordPress ciklusadatai (postId, postType) |
Query blokkok ciklusai |
Az első arra szolgál, hogy a blokkok kommunikáljanak a szülőikkel. A második a Query cikluson belüli blokkoknak segít megállapítani, melyik bejegyzést jelenítik meg. Ez az útmutató az első típussal foglalkozik.
Szerkesztői támogatás
A környezet frissítései reaktívak a szerkesztőben. Amikor a felhasználó módosítja a szülőblokk egyik mezőjének értékét, a szülő környezetére feliratkozott összes gyermekblokk automatikusan újrarenderelődik az új értékkel. Nincs szükség kézi frissítésre.
Szekcióburkoló
A leggyakoribb környezeti minta egy burkolóblokk, amely témabeállításokat biztosít a gyermekei számára. A szülő háttérszín-, szövegszín- és belső térközmezőket tartalmaz. A gyermekek ezeket az értékeket olvassák be, hogy egységesen formázzák magukat.
Szülő: Szekció
{
"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
$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>
Gyermek: Szekciócím
{
"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
$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 szemléltet: A címnek nincs saját színmezője. A szekció theme értékét olvassa ki a környezetből, és ahhoz igazodik. Amikor a felhasználó a szerkesztőben „Világos”-ról „Sötét”-re váltja a szekciót, a címszöveg színe azonnal frissül.
A gyermek block.json fájljában lévő parent tulajdonság korlátozza, hová illeszthető be a blokk. Csak akkor jelenik meg a beszúróban, ha a felhasználó egy my-theme/section blokkon belül van. Ez nem kötelező, de ajánlott azoknál a blokkoknál, amelyek csak egy adott szülőn belül értelmesek.
Gyermek: Szekciószöveg
{
"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
$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>
Most már a cím és a szöveg is követi a szekció témáját. A felhasználó egyszer választ témát a szülőnél, és minden gyermekblokk alkalmazkodik hozzá.
Kártyarács
Egy rácsszülő szabályozza kártyagyermekeinek elrendezési beállításait. A szülő határozza meg az oszlopok számát és a térközt. A gyermekek ezeket az értékeket használják elrendezési környezetük megismeréséhez, és ennek megfelelően módosítják a stílusukat.
Szülő: Kártyarács
{
"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
$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>
Gyermek: Kártya
{
"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
$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 szemléltet: A kártyának nincs saját stílusmezője. A cardStyle értékét a rácsszülőtől olvassa ki. Amikor a felhasználó „Kiemelt”-ről „Körvonalas”-ra váltja a rácsot, az összes kártya egyszerre frissül. Így a kártyák megjelenése egységes marad anélkül, hogy a felhasználónak egyenként kellene frissítenie őket.
A <InnerBlocks> elemen lévő template attribútum három kártyával tölti fel előre a rácsot, kiindulási alapot adva a felhasználónak.
Ártáblázat
Egy összetettebb minta, amelyben a szülő közös üzleti logikát biztosít (például pénznemet és számlázási időszakot), amelyet a gyermekek a megjelenítésükhöz használnak. Ezzel elkerülhető, hogy ugyanazokat a mezőket minden díjcsomagban meg kelljen ismételni.
Szülő: Ártáblázat
{
"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" }
]
}
]
}
}
<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>
Gyermek: Díjcsomag
{
"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
$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">✓</span>
<?php echo esc_html( $feature['text'] ); ?>
</li>
<?php endforeach; ?>
</ul>
<?php endif; ?>
</div>
Mit szemléltet: A pénznem jele és a számlázási időszak egyszer szerepel az ártáblázatban, és minden díjcsomag örökli ezeket. Amikor a felhasználó USD-ről EUR-ra vált, mindhárom díjcsomag pénznemjele egyszerre frissül. Környezet nélkül minden díjcsomagban meg kellene ismételni a pénznemmezőt, és kézzel kellene szinkronban tartani őket.
Query cikluskörnyezete
A WordPress egy külön környezettípust is biztosít a Query blokkok ciklusain belül. Amikor egy blokk cikluson belül renderelődik, a $block['context'] (vagy a $b['context']) az aktuális iteráció bejegyzésadatait tartalmazza:
<?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>
Ez eltér a szülőblokk környezetétől ($context / $c). A cikluskörnyezetet a WordPress alapból biztosítja, és csak a postId és a postType értékeket tartalmazza. Ehhez nincs szükség usesContext-re a block.json fájlban. A Blockstudio automatikusan feliratkoztat minden blokkot a postId és a postType értékére.
Mire használható a cikluskörnyezet: egyéni bejegyzéskártyák Query blokkokban, bejegyzés-metaadatokat megjelenítő blokkok, illetve bármilyen blokk, amelynek ciklusban bejegyzésenként eltérően kell renderelődnie.
A cikluskörnyezettől függetlenül a külső oldal bejegyzésadatai is elérhetők:
$outer_post_id = $block['postId']; // always the current page
$loop_post_id = $block['context']['postId']; // current loop iteration
Beágyazott környezet
A környezet a teljes blokkhierarchián végighalad, nem csak egy szinten. Ha az A blokk tartalmazza a B blokkot, az pedig a C blokkot, akkor a C feliratkozhat az A környezetére. Ez azért működik, mert a WordPress minden InnerBlocks-szinten továbbadja a környezetet.
my-theme/section (theme: "dark")
└── core/columns
└── core/column
└── my-theme/section-heading (reads section context)
A címnek nem kell közvetlenül a szekció gyermekének lennie. Beágyazható alapblokkokba (oszlopokba, csoportokba stb.), és így is megkapja a szekció környezetét. A usesContext-ra való feliratkozás bármilyen mélységben működik.
Több szülő
Egy gyermek több szülőre is feliratkozhat:
{
"usesContext": ["my-theme/section", "my-theme/card-grid"]
}
<?php
$section = $context['my-theme/section'] ?? array();
$grid = $context['my-theme/card-grid'] ?? array();
$theme = $section['theme'] ?? 'light';
$cardStyle = $grid['cardStyle'] ?? 'elevated';
?>
Ha egy szülő nem található meg az ősök között, a kulcsa hiányzik a $context értékéből. A környezeti értékek beolvasásakor mindig használja a null összevonó operátort (??), vagy ellenőrizze a isset() értékét arra az esetre, ha a blokk a várt szülőn kívül szerepel.
Hibabiztos kódolás
A környezetet használó blokkoknak mindig kezelniük kell azt az esetet, amikor hiányzik a szülő. Előfordulhat, hogy a felhasználó a blokkot a neki szánt szülőn kívül illeszti be, vagy a szülőblokk egyik mezőjéhez nincs beállítva érték.
<?php
// Always provide defaults
$section = $context['my-theme/section'] ?? array();
$theme = $section['theme'] ?? 'light';
$spacing = $section['spacing'] ?? 'md';
?>
Ha azt szeretné kikényszeríteni, hogy egy gyermek csak a szülőjén belül jelenjen meg, adja hozzá a parent tulajdonságot:
{
"parent": ["my-theme/section"]
}
Ezzel eltávolítja a blokkot a beszúróból, ha a felhasználó nem egy my-theme/section blokkon belül van. A parent nélkül a blokk mindenhol megjelenik, és a sablon felelőssége, hogy megfelelően kezelje a hiányzó környezetet.
Használja a parent beállítást azoknál a blokkoknál, amelyek a tárolójukon kívül értelmetlenek (például díjcsomagoknál vagy kártyarács-elemeknél). Hagyja ki azoknál, amelyek önállóan is működnek, de a szülőtől extra stílust kapnak (például az önállóan is használható szekciócímeknél).
Tippek
A környezet csak olvasható. A gyermekek környezeten keresztül nem módosíthatják a szülő attribútumait. Az adatok lefelé haladnak, felfelé soha. Ha egy gyermeknek kommunikálnia kell a szülőjével, más megoldásra van szükség, például megosztott szerveroldali állapotra az Interactivity API segítségével vagy bejegyzés-metaadatokra.
Minden attribútum elérhető. A Blockstudio a szülőblokk minden attribútumát elérhetővé teszi, nem csak a kiválasztottakat. Ez azt jelenti, hogy a gyermek a szülő által meghatározott bármely mezőhöz hozzáférhet. Ha a szülő később új mezőt kap, a gyermekek automatikusan elérik, beállításmódosítás nélkül.
Átalakított értékek. A környezeti értékek áthaladnak a Blockstudio attribútumátalakítási folyamatán. A fájlmezők a teljes mellékletadatot tartalmazzák (url, alt, width, height), a választómezők figyelembe veszik a returnFormat beállítást, az ismétlők pedig rekurzívan kibontódnak. Ugyanazt az adatszerkezetet kapja, mint a szülősablon $a értéke.
Reaktivitás a szerkesztőben. Amikor a felhasználó módosít egy szülőmezőt a szerkesztőben, a gyermekblokkok automatikusan újrarenderelődnek. Ehhez a WordPress beépített környezet-továbbítása és egy React useEffect használatos, amely észleli a környezet változásait, majd kiváltja a gyermek szerveroldali újrarenderelését.
Tartsa karcsún a környezetet. Bár a Blockstudio automatikusan elérhetővé teszi az összes szülőattribútumot, a gyermekek csak a ténylegesen szükséges értékeket olvassák be. Ez nem teljesítménybeli, hanem a kód áttekinthetőségével kapcsolatos kérdés. Dokumentálja, mely szülőmezőktől függ egy gyermek, hogy a későbbi fejlesztők is értsék a kapcsolatot.
Következő lépések
- Környezetreferencia: sablonváltozók, cikluskörnyezet és a
$blockadatszerkezet. - InnerBlocks: a
<InnerBlocks />komponens, aallowedBlocks, a sablonok és az előtér burkolóelemének szűrője. - Interactivity útmutató: blokkok közötti, ügyféloldali reaktivitáshoz (az Interactivity API olyan eseteket kezel, amelyekre a környezet nem alkalmas: gyermek-szülő kommunikációt, blokkok közötti állapotot és felhasználó által kezdeményezett frissítéseket).