Blokų kontekstas ir komunikacija
Dauguma blokų yra savarankiški. Jie turi savo laukus, savo šabloną ir jiems nerūpi, kas yra aplink. Tačiau kai kurie komponentai natūraliai sudaro hierarchiją: kortelių tinklelis, kuriame pirminis blokas valdo stulpelių skaičių ir tarpą, kainų lentelė, kurioje pirminis blokas nustato valiutą, arba sekcijos apvalkalas, nurodantis antriniams blokams, naudoti šviesią ar tamsią temą.
WordPress tam suteikia blokų konteksto API. Pirminis blokas pateikia dalį savo duomenų, o antriniai blokai prie jų prisijungia. Kai pirminis blokas pasikeičia, antriniai atnaujinami automatiškai. Blockstudio tai gerokai supaprastina: jums visai nereikia konfigūruoti providesContext. Kiekvienas Blockstudio blokas automatiškai pateikia visus savo atributus kaip kontekstą. Antriniams blokams tereikia vienos eilutės block.json, kad galėtų prie jo prisijungti.
Šiame vadove kuriami keturi realūs komponentų šablonai, naudojantys kontekstą. Kiekvienas jų parodo skirtingą komunikacijos poreikį.
Kaip veikia kontekstas Blockstudio
Standartiniame WordPress kiekvieną pirminio bloko atributą turite aiškiai susieti su konteksto raktu providesContext, tada išvardyti tuos raktus antrinio bloko usesContext. Blockstudio visiškai panaikina pirmąjį veiksmą.
Pirminis blokas: konfigūruoti nereikia. Kiekvienas Blockstudio blokas automatiškai pateikia visus savo atributus savo bloko pavadinimu.
Antrinis blokas: pridėkite usesContext su pirminio bloko pavadinimu:
{
"usesContext": ["my-theme/parent-block"]
}
Antrinio bloko šablonas: pasiekite pirminio bloko atributus per $context (arba trumpinį $c):
<?php $parent = $context['my-theme/parent-block']; ?>
<p>Parent says: <?php echo esc_html( $parent['message'] ); ?></p>
Tai ir visa sąranka. Pirminiame bloke nereikia providesContext, atributų susiejimo ar registracijos kodo. Antrinis blokas gauna visus transformuotus pirminio bloko atributus: medijos laukai išsprendžiami į priedų duomenis, pasirinkimo laukai atsižvelgia į returnFormat, o kartotuvai visiškai išskleidžiami.
Dviejų tipų kontekstas
Blockstudio šablonuose pateikia du konteksto kintamuosius, kurie naudojami skirtingiems tikslams:
| Kintamasis | Turinys | Paskirtis |
|---|---|---|
$context / $c |
Pirminio bloko atributai (per usesContext) |
Komponentų komunikacija |
$block['context'] / $b['context'] |
WordPress ciklo duomenys (postId, postType) |
Užklausos bloko ciklai |
Pirmasis skirtas blokų komunikacijai su pirminiais blokais. Antrasis naudojamas blokams, esantiems užklausos cikle, kai jiems reikia žinoti, kokį įrašą jie atvaizduoja. Šiame vadove aptariamas pirmasis tipas.
Palaikymas redaktoriuje
Redaktoriuje konteksto atnaujinimai vyksta reaktyviai. Kai naudotojas pakeičia pirminio bloko lauko reikšmę, visi antriniai blokai, prisijungę prie to pirminio bloko konteksto, automatiškai atvaizduojami iš naujo su nauja reikšme. Rankiniu būdu atnaujinti nereikia.
Sekcijos apvalkalas
Dažniausiai naudojamas konteksto šablonas: apvalkalo blokas, pateikiantis antriniams blokams temos nustatymus. Pirminis blokas turi fono spalvos, teksto spalvos ir paraščių laukus. Antriniai blokai perskaito šias reikšmes, kad jų stilius būtų nuoseklus.
Pirminis: sekcija
{
"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>
Antrinis: sekcijos antraštė
{
"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>
Ką tai parodo: antraštė neturi savo spalvos lauko. Ji iš konteksto nuskaito sekcijos reikšmę theme ir prie jos prisitaiko. Kai naudotojas redaktoriuje pakeičia sekcijos temą iš „Šviesi“ į „Tamsi“, antraštės teksto spalva atnaujinama iškart.
parent savybė vaiko block.json apriboja, kur galima įterpti bloką. Ji rodoma įterpimo priemonėje tik tada, kai naudotojas yra my-theme/section bloke. Ši savybė neprivaloma, bet rekomenduojama blokams, kurie prasmingi tik konkretaus pirminio bloko viduje.
Antrinis: sekcijos tekstas
{
"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>
Dabar ir antraštė, ir tekstas reaguoja į sekcijos temą. Naudotojas vieną kartą pasirenka pirminio bloko temą, o visi antriniai blokai prie jos prisitaiko.
Kortelių tinklelis
Tinklelio pirminis blokas valdo kortelių antrinių blokų išdėstymo nustatymus. Jis apibrėžia stulpelius ir tarpą. Antriniai blokai naudoja šias reikšmes savo išdėstymo kontekstui suprasti ir atitinkamai koreguoja stilių.
Pirminis: kortelių tinklelis
{
"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>
Antrinis: kortelė
{
"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>
Ką tai parodo: kortelė neturi savo stiliaus lauko. Ji nuskaito cardStyle iš pirminio tinklelio bloko. Kai naudotojas pakeičia tinklelio stilių iš „Su šešėliu“ į „Su kontūru“, visos tinklelio kortelės atnaujinamos iškart. Taip kortelių išvaizda išlieka nuosekli ir naudotojui nereikia atnaujinti kiekvienos atskirai.
<InnerBlocks> atributas template iš anksto užpildo tinklelį trimis kortelėmis, kad naudotojas turėtų nuo ko pradėti.
Kainų lentelė
Sudėtingesnis šablonas, kuriame pirminis blokas pateikia bendrą verslo logiką (valiutą, atsiskaitymo laikotarpį), kurią antriniai blokai naudoja rodydami informaciją. Taip nereikia kartoti tų pačių laukų kiekviename kainų lygyje.
Pirminis: kainų lentelė
{
"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>
Antrinis: kainų lygis
{
"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>
Ką tai parodo: valiutos simbolis ir atsiskaitymo laikotarpis apibrėžiami vieną kartą kainų lentelėje ir paveldimi kiekvieno lygio. Kai naudotojas pakeičia USD į EUR, visų trijų lygių valiutos simbolis atnaujinamas vienu metu. Be konteksto valiutos lauką reikėtų dubliuoti kiekviename lygyje ir sinchronizuoti rankiniu būdu.
Užklausos ciklo kontekstas
Yra atskiras konteksto tipas, kurį WordPress pateikia užklausos blokų cikluose. Kai blokas atvaizduojamas cikle, $block['context'] (arba $b['context']) yra dabartinės iteracijos įrašo duomenys:
<?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>
Tai skiriasi nuo pirminio bloko konteksto ($context / $c). Ciklo kontekstą pateikia pagrindinis WordPress, jame yra tik postId ir postType. Tam nereikia usesContext jūsų block.json. Blockstudio automatiškai prijungia kiekvieną bloką prie postId ir postType.
Kur naudingas ciklo kontekstas: tinkinti įrašų kortelių blokai užklausos blokuose, įrašo metaduomenis rodantys blokai arba bet kuris blokas, kurį cikle reikia atvaizduoti skirtingai kiekvienam įrašui.
Taip pat galite pasiekti išorinio puslapio įrašo duomenis, nepriklausomai nuo ciklo konteksto:
$outer_post_id = $block['postId']; // always the current page
$loop_post_id = $block['context']['postId']; // current loop iteration
Įdėtasis kontekstas
Kontekstas perduodamas per visą blokų medį, o ne tik vienu lygiu. Jei bloke A yra blokas B, o jame — blokas C, blokas C gali prisijungti prie A konteksto. Tai veikia, nes WordPress perduoda kontekstą per kiekvieną InnerBlocks lygį.
my-theme/section (theme: "dark")
└── core/columns
└── core/column
└── my-theme/section-heading (reads section context)
Antraštė nebūtinai turi būti tiesioginis sekcijos antrinis blokas. Ji gali būti įdėta į pagrindinius blokus (stulpelius, grupes ir kt.) ir vis tiek gauti sekcijos kontekstą. usesContext prenumerata veikia bet kuriame gylyje.
Keli pirminiai blokai
Antrinis blokas gali prisijungti prie kelių pirminių blokų:
{
"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';
?>
Jei protėvių medyje pirminis blokas nerandamas, jo rakto $context nebus. Skaitydami konteksto reikšmes visada naudokite null sujungimo operatorių (??) arba patikrinkite isset(), jei blokas naudojamas ne numatytame pirminiame bloke.
Apsauginis programavimas
Kontekstą naudojantys blokai visada turėtų numatyti atvejį, kai pirminio bloko nėra. Naudotojas gali įterpti bloką ne į jam skirtą pirminį bloką arba pirminio bloko konkretus laukas gali neturėti nustatytos reikšmės.
<?php
// Always provide defaults
$section = $context['my-theme/section'] ?? array();
$theme = $section['theme'] ?? 'light';
$spacing = $section['spacing'] ?? 'md';
?>
Jei norite užtikrinti, kad antrinis blokas būtų rodomas tik pirminiame bloke, pridėkite parent savybę:
{
"parent": ["my-theme/section"]
}
Taip blokas pašalinamas iš įterpimo lango, kai naudotojas nėra my-theme/section bloke. Be parent blokas rodomas visur, todėl šablonas turi tinkamai apdoroti trūkstamą kontekstą.
Naudokite parent blokams, kurie be savo konteinerio neturi prasmės (kainų lygiai, kortelių tinklelio elementai). Nenaudokite jos blokams, kurie veikia savarankiškai, bet gali įgyti papildomą pirminio bloko stilių (sekcijų antraštėms, kurias galima naudoti ir atskirai).
Patarimai
Kontekstas yra tik skaitomas. Antriniai blokai negali keisti pirminio bloko atributų per kontekstą. Duomenys perduodami žemyn, niekada aukštyn. Jei antrinis blokas turi perduoti informaciją pirminiam, reikia kito būdo (pvz., bendros serverio būsenos per Interactivity API arba įrašo metaduomenų).
Pateikiami visi atributai. Blockstudio pateikia visus pirminio bloko atributus, o ne tik pasirinktus. Taigi antrinis blokas gali pasiekti bet kurį pirminio bloko apibrėžtą lauką. Jei pirminį bloką papildysite lauku, antriniai blokai jį galės pasiekti automatiškai, nieko papildomai nekonfigūruojant.
Transformuotos reikšmės. Konteksto reikšmės apdorojamos per Blockstudio atributų transformavimo grandinę. Failų laukuose pateikiami visi priedų duomenys (url, alt, width, height), pasirinkimo laukuose atsižvelgiama į returnFormat, o kartotuvai išskleidžiami rekursyviai. Gaunate tokią pačią duomenų struktūrą kaip $a pirminio bloko šablone.
Reaktyvumas redaktoriuje. Kai naudotojas redaktoriuje pakeičia pirminio bloko lauką, antriniai blokai automatiškai atvaizduojami iš naujo. Tam naudojamas WordPress įtaisytasis konteksto perdavimas ir React useEffect, kuris aptinka konteksto pakeitimus ir inicijuoja antrinio bloko atvaizdavimą iš naujo serveryje.
Kontekstas turi būti glaustas. Nors Blockstudio automatiškai pateikia visus pirminio bloko atributus, antriniai blokai turėtų skaityti tik jiems reikalingas reikšmes. Tai nėra našumo klausimas (duomenys jau pateikti), o kodo aiškumo klausimas. Dokumentuokite, nuo kurių pirminio bloko laukų priklauso antrinis blokas, kad būsimi kūrėjai suprastų šį ryšį.
Tolesni žingsniai
- Konteksto nuoroda: šablonų kintamieji, ciklo kontekstas ir
$blockduomenų struktūra. - InnerBlocks: komponentas
<InnerBlocks />,allowedBlocks, šablonai ir išorinės sąsajos apvalkalo filtras. - Interactivity vadovas: kliento pusės reaktyvumui tarp blokų (Interactivity API atlieka tai, ko negali kontekstas: perduoda informaciją iš antrinio bloko pirminiam, valdo bendrą blokų būseną ir naudotojo inicijuojamus atnaujinimus).