Vytvoření vlastního typu pole
Některé hodnoty se skládají z více než jedné základní položky. Cena zahrnuje částku a měnu. S vestavěnými poli ji modelujete jako číselné pole a výběrové pole vedle sebe a každý blok, který zobrazuje cenu, znovu obsahuje tuto dvojici, popisky a logiku, jež je propojuje. V metadatech příspěvku z toho vzniknou dva klíče a uvnitř opakovače dva paralelní seznamy.
Vlastní typ pole spojí tuto dvojici do jednoho pole. Zaregistrujete typ, například
acme/price, jednou v PHP a v JavaScript, a pak ho použijete v libovolném
block.json jako nativní pole: na nejvyšší úrovni, ve skupinách i opakovačích, s ukládáním
v metadatech příspěvku nebo v nastaveních a také v šablonách PHP, Twig a Blade.
Blockstudio odvozuje atribut WordPress a schéma úložiště REST z registrace.
To se liší od vlastního pole.
Odkaz custom/{name} znovu používá skupinu existujících polí. Vlastní typ pole přidává
nový ovládací prvek s vlastním tvarem hodnoty.
Tento průvodce vytvoří celé acme/price: registraci PHP, ovládací prvek editoru,
cenový blok, který ho používá na nejvyšší úrovni i uvnitř opakovače, ukládání do metadat
příspěvku s přísným schématem REST a vykreslený výstup.
Registrace typu v PHP
Část PHP určuje typ atributu, výchozí hodnotu, skript editoru poskytující ovládací prvek a způsob ukládání hodnoty mimo blok:
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 atributu WordPress, zde object. storage.type je typ hodnoty používaný při ukládání
pole do metadat příspěvku nebo nastavení a storage.rest_schema je schéma, podle kterého WordPress ověřuje
zápisy REST. Bez rest_schema dostane hodnota objektu benevolentní schéma, které přijímá
libovolné vlastnosti.
Registraci proveďte v init s výchozí prioritou. Blockstudio objevuje bloky až pozdě
v průběhu init, a pokud do té doby typ není zaregistrován, vygenerované atributy bloku ho
nezahrnou.
bs_register_field_type() při úspěchu vrací true a při neplatném názvu nebo definici false.
Názvy musí být malými písmeny, obsahovat jmenný prostor a používat pomlčky; rezervovány
jsou dva jmenné prostory:
| Název | Výsledek |
|---|---|
acme/price |
true |
Acme/Price |
false, nikoli malými písmeny |
custom/price |
false, rezervováno pro opakovaně použitelné skupiny polí |
blockstudio/price |
false, rezervováno pro jádro Blockstudio |
bs_unregister_field_type() zruší registraci a filtr blockstudio/field_types přijímá stejné definice jako pole
asociované podle názvu.
Vytvoření ovládacího prvku editoru
Výše zaregistrovaný skript poskytuje komponentu React. Používá komponenty WordPress, které už jsou v editoru načtené, takže není potřeba žádný proces sestavení:
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 });
},
}),
),
);
},
});
Komponenta dostává všechny vlastnosti definice pole, takže klíč currencies zadaný v block.json
je dostupný jako props.currencies. Dostává také stabilní vlastnosti: value, onChange, field,
defaultValue, attributes, block, clientId, disabled a inRepeater s repeaterId,
když se vykresluje uvnitř řádku opakovače. onChange ukládá hodnotu přesně tak, jak byla předána.
U vlastních hodnot se přeskočí normalizace možností, kterou provádějí nativní pole
select, radio, color a gradient.
Ošetřete hodnoty, které nejsou objekty, jako to dělají první řádky. Blok uložený ještě před vznikem pole nebo s jiným tvarem hodnoty by se měl v editoru stále otevřít.
Blockstudio zařadí acme-field-price do fronty v editoru bloků pouze tehdy, když je zaregistrovaný blok
používající acme/price. Pokud se skriptu nepodaří ovládací prvek zaregistrovat, editor ponechá
uloženou hodnotu a místo pole zobrazí needitovatelné oznámení; na webu se hodnota stále vykreslí.
Použití v bloku
Cenový blok používá tento typ dvakrát: jednou pro výchozí cenu, kterou lze vyhledávat mimo blok, a podruhé pro každý řádek opakovače cenových ú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"
}
}
]
}
]
}
}
Nastavení default na úrovni pole má přednost před výchozí hodnotou registru. Blockstudio změní
obě pole na atributy WordPress podle registrace. 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" }
}
]
}
}
Vykreslení hodnoty
V šabloně je hodnota obyčejné pole. Před použitím ověřte její typ, protože uložené hodnotě lze důvěřovat jen do té míry jako poslednímu zápisu:
<?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(). Opakovač bez řádků se do šablony předá jako false, nikoli
jako prázdné pole; přímé použití foreach nad ním vyvolá varování PHP.
Řádek @var je vysvětlen níže v části statická analýza.
Vykreslení bloku s výchozí cenou a dvěma cenovými úrovněmi:
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>
Bez jakýchkoli dat se použije výchozí hodnota pole a blok se vykreslí jako From 19.00 EUR bez cenových úrovní.
Twig a Blade čtou stejnou hodnotu jako a.price.amount a $a['price']['amount'] a šablony
rozšíření ji mohou použít pod názvem {attributes.price.amount}.
Úložiště a schéma REST
Obě pole deklarují ukládání postMeta, takže Blockstudio při sestavení bloku zaregistruje dva klíče metadat.
Pole na nejvyšší úrovni používá schéma úložiště z registrace beze změny:
{
"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 uvnitř opakovače ukládá jednu hodnotu na řádek, takže jeho klíč metadat je založený na poli a stejné schéma se použije jako schéma 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í příspěvku obsahujícího tento blok synchronizuje oba klíče. Se dvěma výše uvedenými
cenovými úrovněmi vrací get_post_meta( $id, 'acme_price', true ) hodnotu {"amount":19,"currency":"EUR"} a acme_tier_prices vrací seznam
cen v jednotlivých řádcích:
[
{ "amount": 19, "currency": "EUR" },
{ "amount": 49, "currency": "EUR" }
]
Oba klíče se zobrazí v odpovědi REST příspěvku pod meta a zápisy REST se
ověřují podle schématu. Zápis s malými písmeny v označení měny se odmítne:
{
"code": "rest_invalid_pattern",
"message": "meta.acme_price[currency] does not match pattern ^[A-Z]{3}$.",
"data": { "status": 400 }
}
Metadata jsou kopie. Atributy bloku v obsahu příspěvku zůstávají zdrojem a při každém uložení
se znovu synchronizují do nakonfigurovaných klíčů, takže přímý zápis hodnoty do metadat se při
příštím uložení příspěvku přepíše. Stejně funguje i ukládání nastavení přes register_setting(). Vlastní typy
polí včetně ukládání hodnot v poli uvnitř opakovačů jsou dostupné od verze Blockstudio 7.5.0.
Statická analýza
Rozšíření PHPStan zná vestavěné typy polí, nikoli typy, které projekt registruje za běhu.
U bloku používajícího acme/price proto hlásí neznámý typ pole a typ jeho hodnoty označí jako mixed:
2 block.json field "price" has unknown type "acme/price" in
blockstudio/pricing/block.json
🪪 blockstudio.blockJson.type
V konfiguraci projektu ignorujte tuto diagnostiku pro vlastní typy a v šabloně ponechte kontrolu typu.
Díky ní může PHPStan přijmout hodnotu mixed na úrovni max:
parameters:
level: max
ignoreErrors:
-
identifier: blockstudio.blockJson.type
message: '#unknown type "acme/price"#'
S touto konfigurací a výše uvedenou šablonou analýza projde. Ve verzi 7.6 je v šabloně potřeba
řádek @var s mixed na pozicích vlastních polí; od verze 7.7 Blockstudio tento tvar odvodí samo,
takže řádek lze vypustit. Postup spuštění analýzy najdete v článku Kontrolované šablony s
PHPStan.
Další kroky
- Vlastní typy polí: všechny klíče definice, filtr API a úplný seznam vlastností komponent.
- Úložiště: ukládání libovolného pole do metadat příspěvku a nastavení.
- Kuchařka vzorů polí: skupiny, opakovače a opakovaně použitelné struktury polí.
- Vlastní pole: opakovaně použitelné skupiny polí prostřednictvím
custom/{name}.