Создание пользовательского типа поля
Некоторые значения состоят из нескольких простых частей. Цена включает сумму и валюту. Для встроенных полей её можно представить полем числа и полем выбора рядом, но тогда каждый блок с ценой повторяет эту пару, подписи и логику, которая их связывает. В метаданных записи это превращается в два ключа, а в повторителе — в два параллельных списка.
Пользовательский тип поля объединяет эту пару в одно поле. Зарегистрируйте тип, например
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
проверяются по схеме. Операция записи валюты в нижнем регистре отклоняется:
{
"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 эта структура определяется автоматически, и строку можно удалить. Инструкции по запуску анализа см. в разделе Проверенные шаблоны с PHPStan.
Следующие шаги
- Пользовательские типы полей: все ключи определения, фильтр API и полный список свойств компонента.
- Хранение: хранение любых полей в метаданных записи и параметрах.
- Сборник примеров полей: группы, повторители и повторно используемые структуры полей.
- Пользовательские поля: повторно используемые группы полей через
custom/{name}.