Tworzenie własnego typu pola
Niektóre wartości składają się z czegoś więcej niż jeden typ prosty. Cena obejmuje kwotę i walutę. Przy wbudowanych polach modelujesz ją za pomocą pola liczbowego i pola wyboru umieszczonych obok siebie. Każdy blok wyświetlający cenę powiela tę parę, etykiety oraz logikę, która je łączy. W metadanych wpisu cena staje się dwoma kluczami, a w repeaterze — dwiema równoległymi listami.
Własny typ pola łączy tę parę w jedno pole. Rejestrujesz typ, taki jak
acme/price, raz w PHP i w JavaScript, a następnie używasz go w dowolnym
block.json jak pola wbudowanego: na najwyższym poziomie, w grupach i repeaterach,
z zapisem w metadanych wpisu lub opcjach, a także w szablonach PHP, Twig i Blade.
Blockstudio wyprowadza atrybut WordPress i schemat przechowywania REST na podstawie rejestracji.
To coś innego niż własne pole.
Odwołanie custom/{name} ponownie wykorzystuje grupę istniejących pól. Własny typ pola dodaje nową kontrolkę z własnym formatem wartości.
Ten przewodnik opisuje cały proces tworzenia acme/price: rejestrację PHP,
kontrolkę edytora, blok z cenami używający jej na najwyższym poziomie i w repeaterze,
zapis w metadanych wpisu z rygorystycznym schematem REST oraz renderowanie wyniku.
Rejestrowanie typu w PHP
Część PHP określa typ atrybutu, wartość domyślną, skrypt edytora dostarczający kontrolkę oraz sposób przechowywania wartości poza blokiem:
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 to typ atrybutu WordPress, tutaj object. storage.type to typ wartości używany,
gdy pole jest przechowywane w metadanych wpisu lub opcjach, a storage.rest_schema to schemat,
według którego WordPress sprawdza zapisy REST.
Bez rest_schema wartość obiektu otrzymuje liberalny schemat, który akceptuje dowolne właściwości.
Zarejestruj typ w init z domyślnym priorytetem. Blockstudio wykrywa bloki późno
na init, a typ, który nie zostanie do tego czasu zarejestrowany, nie trafia
do generowanych atrybutów bloków.
bs_register_field_type() zwraca true w razie powodzenia i false, gdy nazwa
lub definicja jest nieprawidłowa. Nazwy muszą być zapisane małymi literami,
mieć przestrzeń nazw i łączniki; dwie przestrzenie nazw są zarezerwowane:
| Nazwa | Wynik |
|---|---|
acme/price |
true |
Acme/Price |
false, nie jest zapisana małymi literami |
custom/price |
false, zarezerwowana dla grup pól wielokrotnego użytku |
blockstudio/price |
false, zarezerwowana dla rdzenia Blockstudio |
bs_unregister_field_type() ponownie usuwa rejestrację, a filtr blockstudio/field_types przyjmuje te same definicje jako tablicę indeksowaną nazwami.
Tworzenie kontrolki edytora
Zarejestrowany wyżej skrypt udostępnia komponent React. Korzysta on z komponentów WordPress już załadowanych w edytorze, więc nie wymaga kompilacji:
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 otrzymuje wszystkie właściwości definicji pola, więc klucz currencies
umieszczony w block.json jest dostępny jako props.currencies. Otrzymuje też stabilne właściwości:
value, onChange, field, defaultValue, attributes, block, clientId,
disabled i inRepeater wraz z repeaterId, gdy renderuje się wewnątrz wiersza repeatera.
onChange zapisuje wartość dokładnie w podanej postaci. Własne wartości pomijają
normalizację opcji stosowaną przez wbudowane pola select, radio, color i gradient.
Zabezpiecz się przed wartościami, które nie są obiektami, tak jak w pierwszych liniach przykładu. Blok zapisany przed dodaniem pola lub z inną strukturą nadal powinien otwierać się w edytorze.
Blockstudio dodaje do kolejki acme-field-price w edytorze bloków tylko wtedy, gdy zarejestrowano blok
korzystający z acme/price. Jeśli skrypt nie zarejestruje kontrolki, edytor zachowuje
zapisaną wartość i wyświetla zamiast pola nieedytowalne powiadomienie; frontend
nadal renderuje wartość.
Używanie pola w bloku
Blok z cenami używa tego typu dwukrotnie: raz dla ceny początkowej, którą trzeba udostępnić do wyszukiwania poza blokiem, i raz dla każdego wiersza repeatera z progami cenowymi:
{
"$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"
}
}
]
}
]
}
}
Wartość default na poziomie pola ma pierwszeństwo przed domyślną wartością rejestru.
Blockstudio zmienia oba pola w atrybuty WordPress na podstawie rejestracji. Zarejestrowany
typ bloku ma następujące właściwości:
{
"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" }
}
]
}
}
Renderowanie wartości
W szablonie wartość jest zwykłą tablicą. Przed użyciem zawęź jej typ, ponieważ zaufanie do zapisanej wartości zależy od tego, co ją ostatnio zapisało:
<?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>
Znaczenie ma ?: array(). Repeater bez wierszy trafia do szablonu jako false,
a nie jako pusta tablica, a zwykłe foreach na tej wartości powoduje ostrzeżenie PHP.
Wyjaśnienie wiersza @var znajduje się poniżej w części analiza statyczna.
Renderowanie bloku z ceną początkową i dwoma progami:
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>
Gdy nie ma żadnych danych, stosowana jest domyślna wartość pola, a blok renderuje
From 19.00 EUR bez progów cenowych. Twig i Blade odczytują tę samą wartość co
a.price.amount i $a['price']['amount'], a szablony rozszerzenia szablonów mogą odwołać się do niej jako do {attributes.price.amount}.
Zapis i schemat REST
Oba pola deklarują zapis postMeta, więc Blockstudio rejestruje podczas tworzenia bloku dwa klucze meta. Pole na najwyższym poziomie używa zarejestrowanego schematu zapisu bez zmian:
{
"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 wewnątrz repeatera zapisuje jedną wartość w każdym wierszu, więc jego klucz meta jest oparty na tablicy, a ten sam schemat staje się schematem elementu:
{
"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
}
}
}
}
Zapisanie wpisu zawierającego blok synchronizuje oba klucze. Przy dwóch progach
cenowych z przykładu get_post_meta( $id, 'acme_price', true ) zwraca {"amount":19,"currency":"EUR"}, a acme_tier_prices zwraca listę cen wierszy:
[
{ "amount": 19, "currency": "EUR" },
{ "amount": 49, "currency": "EUR" }
]
Oba klucze pojawiają się w odpowiedzi REST wpisu pod meta, a zapisy REST
są sprawdzane według schematu. Zapis waluty małymi literami zostanie odrzucony:
{
"code": "rest_invalid_pattern",
"message": "meta.acme_price[currency] does not match pattern ^[A-Z]{3}$.",
"data": { "status": 400 }
}
Metadane są kopią. Atrybuty bloków w treści wpisu pozostają źródłem danych,
a każdy zapis ponownie synchronizuje je ze skonfigurowanymi kluczami. Dlatego
wartość zapisana bezpośrednio w metadanych zostanie zastąpiona przy następnym
zapisaniu wpisu. Zapis w opcjach działa tak samo przez register_setting(). Własne typy pól,
w tym zapis oparty na tablicy wewnątrz repeaterów, są dostępne od wersji
Blockstudio 7.5.0.
Analiza statyczna
Rozszerzenie PHPStan zna wbudowane typy pól, ale nie te rejestrowane
przez projekt w czasie działania. W bloku korzystającym z acme/price zgłasza
nieznany typ pola i określa typ jego wartości jako mixed:
2 block.json field "price" has unknown type "acme/price" in
blockstudio/pricing/block.json
🪪 blockstudio.blockJson.type
Zignoruj ten komunikat dla własnych typów w konfiguracji projektu, ale pozostaw
zawężanie typu w szablonie — jest ono potrzebne, aby PHPStan zaakceptował wartość
mixed na poziomie max:
parameters:
level: max
ignoreErrors:
-
identifier: blockstudio.blockJson.type
message: '#unknown type "acme/price"#'
Przy tej konfiguracji i powyższym szablonie analiza przechodzi poprawnie. W wersji
7.6 szablon wymaga też wiersza @var z mixed w miejscach pól własnych.
Od wersji 7.7 Blockstudio samodzielnie wywnioskuje tę strukturę i wiersz można usunąć.
Informacje o uruchamianiu analizy znajdziesz w Szablonach sprawdzanych za pomocą PHPStan.
Następne kroki
- Własne typy pól: wszystkie klucze definicji, filtr API i pełna lista właściwości komponentu.
- Zapis: zapis dowolnego pola w metadanych wpisu i opcjach.
- Zbiór wzorców pól: grupy, repeatery i struktury pól wielokrotnego użytku.
- Pola własne: grupy pól wielokrotnego użytku za pomocą
custom/{name}.