Изграждане на тип персонализирано поле
Някои стойности съдържат повече от един примитив. Цената включва сума и валута. С вградените полета я моделирате като числово поле и поле за избор едно до друго, а всеки блок, който показва цена, повтаря тази двойка, етикетите и логиката, която ги държи заедно. В метаданните на публикацията това стават два ключа, а в повтарящо се поле — два паралелни списъка.
Персонализираният тип поле превръща двойката в едно поле. Регистрирате тип като
acme/price веднъж, в PHP и в JavaScript, след което го използвате във всеки
block.json като вградено поле: на най-горно ниво, в групи и
повтарящи се полета, със съхранение в метаданните на публикация или в опции, както и в шаблони PHP, Twig и Blade.
Blockstudio извежда атрибута WordPress и схемата за съхранение REST
от регистрацията.
Това е различно от персонализирано поле.
Препратката custom/{name} използва повторно група съществуващи полета. Персонализираният тип поле
добавя нов контрол със собствена форма на стойността.
Това ръководство изгражда acme/price от начало до край: регистрацията PHP, редакторския
контрол, блок за ценообразуване, който го използва на най-горно ниво и в повтарящо се поле,
съхранението в метаданните на публикацията със строга схема REST и визуализирания резултат.
Регистриране на типа в PHP
Частта PHP задава типа на атрибута, стойността по подразбиране, скрипта за редактора, който предоставя контрола, и начина на съхранение на стойността извън блока:
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 е типът на атрибута WordPress, тук object. storage.type е
типът на стойността, когато полето се съхранява в метаданните на публикация или в опции, а
storage.rest_schema е схема, която валидира записите на WordPress спрямо REST.
Без rest_schema стойност от тип обект получава разрешителна схема, която приема
произволни свойства.
Регистрирайте го в init с приоритет по подразбиране. Blockstudio открива блоковете късно
в init и тип, който дотогава не е регистриран, няма да бъде включен в
генерираните атрибути на блока.
bs_register_field_type() връща true при успех и false, когато името
или дефиницията са невалидни. Имената трябва да са с малки букви, да имат пространство от имена и тирета,
като две пространства от имена са запазени:
| Име | Резултат |
|---|---|
acme/price |
true |
Acme/Price |
false, не е с малки букви |
custom/price |
false, запазено за групи полета за повторна употреба |
blockstudio/price |
false, запазено за основните компоненти на Blockstudio |
bs_unregister_field_type() премахва регистрация, а филтърът
blockstudio/field_types приема същите дефиниции като масив с ключове по име.
Създаване на редакторския контрол
Скриптът, регистриран по-горе, предоставя компонента React. Той използва вече заредените в редактора компоненти WordPress, затова не изисква стъпка за компилация:
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 });
},
}),
),
);
},
});
Компонентът получава всяко свойство от дефиницията на полето, така че ключът currencies, зададен в block.json, пристига като props.currencies. Получава и стабилни свойства: value, onChange, field, defaultValue,
attributes, block, clientId, disabled и inRepeater с
repeaterId, когато се визуализира в ред на повтарящо се поле. onChange съхранява стойността
точно както е подадена. Персонализираните стойности пропускат нормализирането на опциите, което вградените полета select, radio, color и gradient прилагат.
Проверявайте дали стойностите са обекти, както е направено в първите редове. Блок, записан преди съществуването на полето или с различна структура, пак трябва да се отваря в редактора.
Blockstudio добавя acme-field-price в редактора на блокове само когато е регистриран блок,
който използва acme/price. Ако скриптът не успее да регистрира
контрола, редакторът запазва записаната стойност и показва известие, което не може да се редактира,
на мястото на полето, а интерфейсът за посетители продължава да визуализира стойността.
Използване в блок
Блокът за ценообразуване използва типа два пъти: веднъж за начална цена, която трябва да може да се заявява извън блока, и веднъж за всеки ред в повтарящото се поле за ценови нива:
{
"$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"
}
}
]
}
]
}
}
Стойността default на ниво поле има предимство пред стандартната в регистъра. Blockstudio превръща и двете
полета в атрибути WordPress от регистрацията. Регистрираният тип на блока съдържа:
{
"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" }
}
]
}
}
Визуализиране на стойността
В шаблона стойността е обикновен масив. Проверете типа ѝ, преди да я използвате, защото съхранената стойност е толкова надеждна, колкото и последният запис, който я е създал:
<?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>
?: array() е важен. Ако повтарящото се поле няма редове, в шаблона то пристига като
false, а не като празен масив, и директно foreach над него предизвиква предупреждение PHP.
Редът @var е обяснен по-долу в раздела за статичен
анализ.
Визуализиране на блока с начална цена и две ценови нива:
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>
Без никакви данни се прилага стойността по подразбиране на полето и блокът се визуализира
From 19.00 EUR без ценови нива. Twig и Blade четат същата стойност като
a.price.amount и $a['price']['amount'], а шаблоните за разширение могат да я достъпят като
{attributes.price.amount}.
Съхранение и схема REST
И двете полета задават съхранение postMeta, затова Blockstudio регистрира два мета ключа
при изграждането на блока. Полето от най-горно ниво използва схемата за съхранение от регистрацията
без промени:
{
"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
}
}
}
Полето в повтарящото се поле съхранява по една стойност на ред, затова неговият мета ключ се базира на масив, а същата схема става схемата за елементите:
{
"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
}
}
}
}
Записването на публикация, съдържаща блока, синхронизира и двата ключа. С двете ценови нива от
по-горе get_post_meta( $id, 'acme_price', true ) връща
{"amount":19,"currency":"EUR"}, а acme_tier_prices връща списъка с
цени по редове:
[
{ "amount": 19, "currency": "EUR" },
{ "amount": 49, "currency": "EUR" }
]
И двата ключа се показват в отговора на публикацията от REST под meta, а записите на REST се
валидираt спрямо схемата. Запис с валута, изписана с малки букви, се отхвърля:
{
"code": "rest_invalid_pattern",
"message": "meta.acme_price[currency] does not match pattern ^[A-Z]{3}$.",
"data": { "status": 400 }
}
Метаданните са копие. Атрибутите на блока в съдържанието на публикацията остават източникът,
а всяко записване синхронизира стойностите им с конфигурираните ключове отново, така че стойност,
записана директно в метаданните, се заменя при следващото записване на публикацията. Съхранението в опции работи
по същия начин чрез register_setting(). Персонализираните типове полета, включително
съхранение на база масив вътре в повтарящи се полета, са налични от Blockstudio 7.5.0.
Статичен анализ
Разширението PHPStan познава вградените типове полета, но не и тези,
регистрирани от проекта по време на изпълнение. За блок, който използва acme/price,
то отчита типа на полето като неизвестен и задава тип mixed на стойността му:
2 block.json field "price" has unknown type "acme/price" in
blockstudio/pricing/block.json
🪪 blockstudio.blockJson.type
Игнорирайте тази диагностика за собствените си типове в конфигурацията на проекта,
и запазете проверката на типа в шаблона — тя е нужна на PHPStan, за да приеме
стойността mixed на ниво max:
parameters:
level: max
ignoreErrors:
-
identifier: blockstudio.blockJson.type
message: '#unknown type "acme/price"#'
С тази конфигурация и шаблона по-горе анализът преминава. Във версия 7.6
шаблонът също изисква реда @var, с mixed на местата на
персонализираните полета; Blockstudio 7.7 извежда тази структура автоматично и редът може
da бъде премахнат. Вижте Проверени шаблони с PHPStan за
изпълнението на анализа.
Следващи стъпки
- Персонализирани типове полета: всички ключове в дефиницията, филтърът API и пълният списък със свойства на компонента.
- Съхранение: съхранение в метаданните на публикации и в опции за всякакви полета.
- Наръчник с модели за полета: групи, повтарящи се полета и структури от полета за повторна употреба.
- Персонализирани полета: групи полета за повторна употреба
чрез
custom/{name}.