Створення власного типу поля
Деякі значення складаються з кількох примітивів. Ціна — це сума та валюта. За допомогою вбудованих полів ви моделюєте її окремими числовим полем і полем зі списком, а кожен блок із ціною повторює цю пару, мітки й логіку, що поєднує їх. У метаданих запису це перетворюється на два ключі, а в повторювачі — на два паралельні списки.
Власний тип поля об’єднує цю пару в одне поле. Ви реєструєте такий тип, як
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. Він також
отримує стабільні props: 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 стоять на місцях користувацьких полів; у версії 7.7 ця структура визначається автоматично, і рядок можна прибрати. Див. Перевірені шаблони з PHPStanBlockstudio, щоб запустити аналіз.
Наступні кроки
- Власні типи полів: усі ключі визначення, фільтр API і повний перелік props компонента.
- Збереження: збереження метаданих запису й параметрів для будь-якого поля.
- Збірник шаблонів полів: групи, повторювачі та повторно використовувані структури полів.
- Власні поля: повторно використовувані групи полів через
custom/{name}.