Tvorba vlastného typu poľa
Niektoré hodnoty pozostávajú z viacerých primitívnych hodnôt. Cena obsahuje sumu a menu. Pri vstavaných poliach ich modelujete samostatným číselným poľom a výberovým poľom, pričom každý blok zobrazujúci cenu opakuje túto dvojicu, popisky aj logiku, ktorá ich spája. V meta údajoch príspevku sa zmenia na dva kľúče a v opakovači na dva paralelné zoznamy.
Vlastný typ poľa zmení túto dvojicu na jedno pole. Typ, napríklad acme/price, zaregistrujete raz v PHP a v JavaScript a potom ho môžete použiť v ľubovoľnom block.json ako natívne pole: na najvyššej úrovni, v skupinách a opakovačoch, s ukladaním do meta údajov príspevku alebo možností a v šablónach PHP, Twig a Blade. Blockstudio odvodí atribút WordPress a schému ukladania REST z registrácie.
Toto sa líši od vlastného poľa.
Referencia custom/{name} znovu používa skupinu existujúcich polí. Vlastný typ poľa pridáva nový ovládací prvok s vlastným tvarom hodnoty.
Táto príručka vás prevedie tvorbou acme/price od začiatku do konca: registráciou PHP, ovládacím prvkom editora, cenovým blokom, ktorý ho používa na najvyššej úrovni aj v opakovači, ukladaním do meta údajov príspevku s prísnou schémou REST a vykresleným výstupom.
Registrácia typu v PHP
Časť PHP deklaruje typ atribútu, predvolenú hodnotu, skript editora, ktorý poskytuje ovládací prvok, a spôsob ukladania hodnoty mimo bloku:
add_action( 'init', function () {
wp_register_script(
'acme-field-price',
get_stylesheet_directory_uri() . '/fields/price.js',
array( 'blockstudio-blocks', 'wp-components', 'wp-element' ),
'1.0.0',
true
);
bs_register_field_type( 'acme/price', array(
'attribute' => 'object',
'default' => array(),
'editor_script' => 'acme-field-price',
'storage' => array(
'type' => 'object',
'rest_schema' => array(
'type' => 'object',
'properties' => array(
'amount' => array( 'type' => 'number', 'minimum' => 0 ),
'currency' => array( 'type' => 'string', 'pattern' => '^[A-Z]{3}$' ),
),
'additionalProperties' => false,
),
),
) );
} );
attribute je typ atribútu WordPress, v tomto prípade object. storage.type je typ hodnoty používaný pri ukladaní poľa do meta údajov príspevku alebo možností a storage.rest_schema je schéma, podľa ktorej WordPress overuje zápisy REST.
Bez rest_schema dostane objektová hodnota benevolentnú schému, ktorá povoľuje ľubovoľné vlastnosti.
Zaregistrujte ho v init s predvolenou prioritou. Blockstudio vyhľadáva bloky až neskôr
pri init, takže typ, ktorý dovtedy nie je zaregistrovaný, sa do vygenerovaných atribútov bloku nezahrnie.
bs_register_field_type() pri úspechu vráti true a pri neplatnom názve
alebo definícii false. Názvy musia byť malými písmenami, obsahovať menný priestor a používať pomlčky. Dva menné priestory sú rezervované:
| Názov | Výsledok |
|---|---|
acme/price |
true |
Acme/Price |
false, nie je malými písmenami |
custom/price |
false, rezervované pre opakovane použiteľné skupiny polí |
blockstudio/price |
false, rezervované pre jadro Blockstudio |
bs_unregister_field_type() odstráni registráciu a filter blockstudio/field_types prijíma rovnaké definície ako pole asociatívne s názvami.
Vytvorenie ovládacieho prvku editora
Skript zaregistrovaný vyššie poskytuje komponent React. Používa komponenty WordPress, ktoré sú už načítané v editore, takže nevyžaduje zostavenie:
const { createElement: el } = wp.element;
const { Flex, FlexBlock, FlexItem, SelectControl, TextControl } = wp.components;
window.blockstudio.registerFieldType('acme/price', {
component(props) {
const value =
props.value && typeof props.value === 'object' && !Array.isArray(props.value)
? props.value
: {};
const currencies = props.currencies || ['EUR'];
return el(
Flex,
{ align: 'flex-end' },
el(
FlexBlock,
{},
el(TextControl, {
label: props.label,
type: 'number',
min: 0,
step: 0.01,
disabled: props.disabled,
value: value.amount ?? '',
onChange(next) {
props.onChange({ ...value, amount: next === '' ? 0 : Number(next) });
},
}),
),
el(
FlexItem,
{},
el(SelectControl, {
label: 'Currency',
hideLabelFromVision: true,
disabled: props.disabled,
value: value.currency || currencies[0],
options: currencies.map((code) => ({ label: code, value: code })),
onChange(next) {
props.onChange({ ...value, currency: next });
},
}),
),
);
},
});
Komponent dostáva všetky vlastnosti definície poľa, takže kľúč currencies zadaný v block.json sa mu odovzdá ako props.currencies. Dostáva aj stabilné vlastnosti: value, onChange, field, defaultValue, attributes, block, clientId, disabled a inRepeater s repeaterId, keď sa vykresľuje v riadku opakovača. onChange ukladá hodnotu presne tak, ako je zadaná. Pri vlastných hodnotách sa nepoužíva normalizácia možností, ktorú uplatňujú natívne polia select, radio, color a gradient.
Ošetrite hodnoty, ktoré nie sú objektmi, ako v prvých riadkoch. Blok uložený pred vytvorením poľa alebo s iným tvarom hodnoty by sa mal v editore stále otvoriť.
Blockstudio zaradí acme-field-price do fronty editora bloku iba vtedy, keď je zaregistrovaný blok používajúci acme/price. Ak sa skript nepodarí zaregistrovať ovládací prvok, editor zachová uloženú hodnotu a namiesto poľa zobrazí upozornenie, ktoré nemožno upravovať. Frontend bude hodnotu naďalej vykresľovať.
Použitie v bloku
Cenový blok používa tento typ dvakrát: raz pre východiskovú cenu, ktorú treba vedieť vyhľadávať mimo bloku, a raz pre každý riadok opakovača úrovní:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/pricing",
"title": "Pricing",
"blockstudio": {
"attributes": [
{
"id": "price",
"type": "acme/price",
"label": "Starting price",
"currencies": ["EUR", "USD"],
"default": { "amount": 19, "currency": "EUR" },
"storage": {
"type": "postMeta",
"postMetaKey": "acme_price"
}
},
{
"id": "tiers",
"type": "repeater",
"label": "Tiers",
"min": 0,
"max": 4,
"attributes": [
{ "id": "name", "type": "text", "label": "Name", "default": "" },
{
"id": "price",
"type": "acme/price",
"label": "Price",
"currencies": ["EUR", "USD"],
"default": { "amount": 0, "currency": "EUR" },
"storage": {
"type": "postMeta",
"postMetaKey": "acme_tier_prices"
}
}
]
}
]
}
}
Nastavenie default na úrovni poľa má prednosť pred predvoleným nastavením registra. Blockstudio zmení obe polia na atribúty WordPress z registrácie. Zaregistrovaný typ bloku obsahuje:
{
"price": {
"blockstudio": true,
"type": "object",
"field": "acme/price",
"id": "price",
"default": { "amount": 19, "currency": "EUR" },
"storage": { "type": "postMeta", "postMetaKey": "acme_price" }
},
"tiers": {
"blockstudio": true,
"type": "array",
"field": "repeater",
"id": "tiers",
"attributes": [
{ "blockstudio": true, "type": "string", "field": "text", "default": "", "id": "name" },
{
"blockstudio": true,
"type": "object",
"field": "acme/price",
"id": "price",
"default": { "amount": 0, "currency": "EUR" },
"storage": { "type": "postMeta", "postMetaKey": "acme_tier_prices" }
}
]
}
}
Vykreslenie hodnoty
V šablóne je hodnota obyčajné pole. Pred použitím obmedzte jej typ, pretože uložená hodnota je len taká dôveryhodná, ako je dôveryhodný posledný zápis:
<?php
/** @var array{price: mixed, tiers: array<int, array{name: string, price: mixed}>} $a */
$format = static function ( mixed $price ): string {
if ( ! is_array( $price ) ) {
return '';
}
$amount = is_numeric( $price['amount'] ?? null ) ? (float) $price['amount'] : 0.0;
$currency = is_string( $price['currency'] ?? null ) ? $price['currency'] : '';
return number_format_i18n( $amount, 2 ) . ' ' . $currency;
};
?>
<section useBlockProps class="acme-pricing">
<p>From <?php echo esc_html( $format( $a['price'] ) ); ?></p>
<?php foreach ( $a['tiers'] ?: array() as $tier ) : ?>
<div class="acme-tier">
<h3><?php echo esc_html( $tier['name'] ); ?></h3>
<p><?php echo esc_html( $format( $tier['price'] ?? null ) ); ?></p>
</div>
<?php endforeach; ?>
</section>
Dôležitá je ?: array(). Ak opakovač nemá žiadne riadky, šablóna dostane false, nie prázdne pole, a priame použitie foreach nad ním vyvolá upozornenie PHP. Riadok @var je vysvetlený nižšie v časti statická analýza.
Vykreslenie bloku s východiskovou cenou a dvoma úrovňami:
echo bs_block( array(
'name' => 'acme/pricing',
'data' => array(
'price' => array( 'amount' => 19, 'currency' => 'EUR' ),
'tiers' => array(
array( 'name' => 'Starter', 'price' => array( 'amount' => 19, 'currency' => 'EUR' ) ),
array( 'name' => 'Team', 'price' => array( 'amount' => 49, 'currency' => 'EUR' ) ),
),
),
) );
<!--blockstudio/acme/pricing--><section class="acme-pricing wp-block-acme-pricing">
<p>From 19.00 EUR</p>
<div class="acme-tier">
<h3>Starter</h3>
<p>19.00 EUR</p>
</div>
<div class="acme-tier">
<h3>Team</h3>
<p>49.00 EUR</p>
</div>
</section>
Ak chýbajú všetky údaje, použije sa predvolená hodnota poľa a blok sa vykreslí ako From 19.00 EUR bez úrovní. Twig a Blade čítajú rovnakú hodnotu ako a.price.amount a $a['price']['amount'] a šablóny rozšírenia extension ju môžu používať ako {attributes.price.amount}.
Ukladanie a schéma REST
Obe polia deklarujú ukladanie postMeta, takže Blockstudio pri zostavení bloku zaregistruje dva meta kľúče. Pole na najvyššej úrovni používa registrovanú schému ukladania bez úprav:
{
"type": "object",
"single": true,
"show_in_rest": {
"schema": {
"type": "object",
"properties": {
"amount": { "type": "number", "minimum": 0 },
"currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
},
"additionalProperties": false
}
}
}
Pole v opakovači ukladá jednu hodnotu na každý riadok, takže jeho meta kľúč je založený na poli a rovnaká schéma sa stáva schémou položky:
{
"type": "array",
"single": true,
"show_in_rest": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"amount": { "type": "number", "minimum": 0 },
"currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
},
"additionalProperties": false
}
}
}
}
Uložením príspevku obsahujúceho tento blok sa synchronizujú oba kľúče. Pri dvoch vyššie uvedených úrovniach get_post_meta( $id, 'acme_price', true ) vráti {"amount":19,"currency":"EUR"} a acme_tier_prices vráti zoznam cien jednotlivých riadkov:
[
{ "amount": 19, "currency": "EUR" },
{ "amount": 49, "currency": "EUR" }
]
Oba kľúče sa objavia v odpovedi REST príspevku pod meta a zápisy REST sa overujú podľa schémy. Zápis s menou zapísanou malými písmenami sa odmietne:
{
"code": "rest_invalid_pattern",
"message": "meta.acme_price[currency] does not match pattern ^[A-Z]{3}$.",
"data": { "status": 400 }
}
Meta údaje sú kópiou. Zdrojom zostávajú atribúty bloku v obsahu príspevku a každé uloženie ich znova synchronizuje s nakonfigurovanými kľúčmi. Hodnotu zapísanú priamo do meta údajov preto nahradí ďalšie uloženie príspevku. Ukladanie možností funguje rovnako prostredníctvom register_setting(). Vlastné typy polí vrátane ukladania založeného na poli v opakovačoch sú dostupné od Blockstudio 7.5.0.
Statická analýza
Rozšírenie PHPStanextension pozná vstavané typy polí, nie tie, ktoré projekt registruje počas behu. Pri bloku používajúcom acme/price preto označí typ poľa ako neznámy a jeho hodnotu určí ako mixed:
2 block.json field "price" has unknown type "acme/price" in
blockstudio/pricing/block.json
🪪 blockstudio.blockJson.type
V konfigurácii projektu ignorujte toto upozornenie pre vlastné typy a ponechajte obmedzenie typu v šablóne. To umožňuje nástroju PHPStan prijať hodnotu mixed na úrovni max:
parameters:
level: max
ignoreErrors:
-
identifier: blockstudio.blockJson.type
message: '#unknown type "acme/price"#'
Pri tejto konfigurácii a vyššie uvedenej šablóne analýza prejde. Vo verzii 7.6 šablóna potrebuje aj riadok @var, pričom na miestach vlastných polí sa použije mixed. Od verzie 7.7 Blockstudio túto štruktúru odvodí samo a riadok možno odstrániť. Informácie o spustení analýzy nájdete v časti Kontrola šablón pomocou PHPStan.
Ďalšie kroky
- Vlastné typy polí: každý kľúč definície, filter API a úplný zoznam vlastností komponentu.
- Ukladanie: ukladanie do meta údajov príspevku a možností pre ľubovoľné pole.
- Príručka vzorov polí: skupiny, opakovače a opakovane použiteľné štruktúry polí.
- Vlastné polia: opakovane použiteľné skupiny polí prostredníctvom
custom/{name}.