Pielāgota lauka tipa izveide
Dažas vērtības sastāv no vairākiem elementiem. Cena ietver summu un valūtu. Izmantojot iebūvētos laukus, to modelē ar blakus novietotiem skaitļa un atlases laukiem, un katrā blokā, kurā attēlota cena, tiek atkārtots šis lauku pāris, to etiķetes un loģika, kas tos apvieno. Ziņas metadatos tie kļūst par divām atslēgām, bet atkārtotājā — par diviem paralēliem sarakstiem.
Pielāgota lauka tips apvieno pāri vienā laukā. Reģistrējiet tādu tipu kā acme/price vienreiz — PHP un JavaScript — un pēc tam izmantojiet to jebkurā block.json kā vietējo lauku: augšējā līmenī, grupās un atkārtotājos, ziņas metadatu vai opciju glabāšanā, kā arī veidnēs PHP, Twig un Blade. Blockstudio no reģistrācijas iegūst WordPress atribūtu un glabāšanas REST shēmu.
Tas atšķiras no pielāgota lauka. custom/{name} atsauce atkārtoti izmanto esošu lauku grupu. Pielāgota lauka tips pievieno jaunu vadīklu ar savu vērtības struktūru.
Šajā ceļvedī no sākuma līdz beigām tiek izveidots acme/price: PHP reģistrācija, redaktora vadīkla, cenu bloks, kas to izmanto augšējā līmenī un atkārtotājā, ziņas metadatu glabāšana ar stingru REST shēmu un attēlotais rezultāts.
Reģistrējiet tipu sadaļā PHP
PHP daļa deklarē atribūta tipu, noklusējuma vērtību, redaktora skriptu, kas nodrošina vadīklu, un to, kā vērtība tiek glabāta ārpus bloka:
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 ir WordPress atribūta tips; šeit tas ir object. storage.type ir vērtības tips, ko izmanto, glabājot lauku ziņas metadatos vai opcijās, un storage.rest_schema ir shēma, pēc kuras WordPress validē REST ierakstīšanas darbības. Ja nav rest_schema, objekta vērtībai tiek piešķirta pielaidīga shēma, kas pieņem jebkuras īpašības.
Reģistrējiet, izmantojot init, ar noklusējuma prioritāti. Blockstudio vēlāk atrod blokus, izmantojot init, un, ja tips līdz tam nav reģistrēts, tas netiek iekļauts ģenerētajos bloka atribūtos.
Ja izpilde izdodas, bs_register_field_type() atgriež true; ja nosaukums vai definīcija nav derīgi, tā atgriež false. Nosaukumiem jābūt rakstītiem ar mazajiem burtiem, jāsatur nosaukumvieta un jāizmanto defises; divas nosaukumvietas ir rezervētas:
| Nosaukums | Rezultāts |
|---|---|
acme/price |
true |
Acme/Price |
false, nav rakstīts ar mazajiem burtiem |
custom/price |
false, rezervēta atkārtoti izmantojamām lauku grupām |
blockstudio/price |
false, rezervēta Blockstudio kodolam |
bs_unregister_field_type() noņem reģistrāciju, bet filtrs blockstudio/field_types pieņem tās pašas definīcijas kā masīvu, kura atslēgas ir nosaukumi.
Redaktora vadīklas izveide
Iepriekš reģistrētais skripts nodrošina komponentu React. Tas izmanto redaktorā jau ielādētos komponentus WordPress, tāpēc izveides darbība nav nepieciešama:
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 });
},
}),
),
);
},
});
Komponents saņem visas lauka definīcijas īpašības, tāpēc block.json ievietotā atslēga currencies tiek saņemta kā props.currencies. Tas saņem arī stabilās rekvizītu vērtības: value, onChange, field, defaultValue, attributes, block, clientId, disabled un inRepeater ar repeaterId, kad tas tiek attēlots atkārtotāja rindā. onChange saglabā vērtību tieši tādu, kāda tā ir norādīta. Pielāgotajām vērtībām netiek piemērota opciju normalizēšana, ko veic iebūvētie lauki select, radio, color un gradient.
Kā tas darīts pirmajās koda rindās, apstrādājiet vērtības, kas nav objekti. Blokam, kas saglabāts pirms lauka izveides vai ar citu struktūru, joprojām jāatveras redaktorā.
Blockstudio pievieno rindai acme-field-price bloku redaktorā tikai tad, ja ir reģistrēts bloks, kurā izmantots acme/price. Ja skriptam neizdodas reģistrēt vadīklu, redaktorā saglabātā vērtība paliek un lauka vietā tiek parādīts nerediģējams paziņojums; priekšskatā vērtība joprojām tiek attēlota.
Izmantojiet to blokā
Cenu blokā šis tips tiek izmantots divreiz: sākuma cenai, kurai jābūt pieejamai vaicājumos ārpus bloka, un katrai pakāpju atkārtotāja rindai:
{
"$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"
}
}
]
}
]
}
}
Lauka līmeņa default ir prioritāte pār reģistra noklusējuma vērtību. Blockstudio padara abus laukus par WordPress atribūtiem no reģistrācijas. Reģistrētajam bloka tipam ir:
{
"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" }
}
]
}
}
Vērtības attēlošana
Veidnē vērtība ir parasts masīvs. Pirms lietošanas pārbaudiet tās tipu, jo saglabātā vērtība ir tik uzticama, cik pēdējais, kurš to ierakstīja:
<?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() ir svarīga. Ja atkārtotājam nav rindu, veidne saņem false, nevis tukšu masīvu, un vienkārša foreach izmantošana tam izraisa brīdinājumu PHP. Rinda @var ir izskaidrota zemāk sadaļā statiskā analīze.
Bloka attēlojums ar sākuma cenu un diviem cenu līmeņiem:
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>
Ja datu nav, tiek lietota lauka noklusējuma vērtība, un bloks attēlo From 19.00 EUR bez cenu līmeņiem. Twig un Blade nolasa to pašu vērtību, ko a.price.amount un $a['price']['amount'], un paplašinājuma veidnes var tai piekļūt kā {attributes.price.amount}.
Glabāšana un REST shēma
Abi lauki deklarē postMeta glabāšanu, tāpēc, veidojot bloku, Blockstudio reģistrē divas meta atslēgas. Augšējā līmeņa lauks izmanto reģistrēto glabāšanas shēmu tādu, kāda tā ir:
{
"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
}
}
}
Lauks atkārtotājā saglabā vienu vērtību katrā rindā, tāpēc tā meta atslēga izmanto masīvu, un tā pati shēma kļūst par elementa shēmu:
{
"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
}
}
}
}
Saglabājot ziņu, kurā ir šis bloks, tiek sinhronizētas abas atslēgas. Ar iepriekš minētajiem diviem cenu līmeņiem get_post_meta( $id, 'acme_price', true ) atgriež {"amount":19,"currency":"EUR"}, bet acme_tier_prices atgriež rindu cenu sarakstu:
[
{ "amount": 19, "currency": "EUR" },
{ "amount": 49, "currency": "EUR" }
]
Abas atslēgas ziņas REST atbildē ir zem meta, un REST ierakstīšanas darbības tiek validētas pēc shēmas. Ierakstīšana ar valūtu, kas norādīta ar mazajiem burtiem, tiek noraidīta:
{
"code": "rest_invalid_pattern",
"message": "meta.acme_price[currency] does not match pattern ^[A-Z]{3}$.",
"data": { "status": 400 }
}
Meta ir kopija. Bloka atribūti ziņas saturā joprojām ir avots, un katrā saglabāšanas reizē tie atkal tiek sinhronizēti ar konfigurētajām atslēgām. Tāpēc tieši metadatos ierakstītā vērtība tiek aizstāta nākamajā ziņas saglabāšanas reizē. Opciju glabāšana darbojas tāpat, izmantojot register_setting(). Pielāgoti lauku tipi, tostarp glabāšana ar masīvu atkārtotājos, ir pieejami kopš Blockstudio 7.5.0.
Statiskā analīze
Paplašinājums PHPStan pārzina iebūvētos lauku tipus, bet ne tos, ko projekts reģistrē izpildes laikā. Blokā, kurā izmantots acme/price, tas uzrāda nezināmu lauka tipu un piešķir tā vērtībai tipu mixed:
2 block.json field "price" has unknown type "acme/price" in
blockstudio/pricing/block.json
🪪 blockstudio.blockJson.type
Projekta konfigurācijā ignorējiet šo diagnostikas ziņojumu saviem tipiem, taču saglabājiet tipa pārbaudi veidnē. Tā vajadzīga, lai PHPStan pieņemtu mixed vērtību max līmenī:
parameters:
level: max
ignoreErrors:
-
identifier: blockstudio.blockJson.type
message: '#unknown type "acme/price"#'
Izmantojot šo konfigurāciju un iepriekš norādīto veidni, analīze tiek sekmīgi pabeigta. Versijā 7.6 veidnei vajadzīga arī rinda @var, kur pielāgoto lauku vietās ir mixed; Blockstudio versijā 7.7 šo struktūru nosaka automātiski, un rindu var izlaist. Norādījumi analīzes palaišanai pieejami sadaļā Veidņu pārbaude ar PHPStan.
Nākamās darbības
- Pielāgotu lauku tipi: visas definīciju atslēgas, filtrs API un pilns komponenta rekvizītu saraksts.
- Glabāšana: ziņu metadatu un opciju glabāšana jebkuram laukam.
- Lauku paraugu rokasgrāmata: grupas, atkārtotāji un atkārtoti izmantojamas lauku struktūras.
- Pielāgoti lauki: atkārtoti izmantojamas lauku grupas, izmantojot
custom/{name}.