Mukautetun kenttätyypin rakentaminen
Jotkin arvot koostuvat useammasta kuin yhdestä alkeisarvosta. Hinta muodostuu summasta ja valuutasta. Sisäänrakennetuilla kentillä mallinnat sen rinnakkain numero- ja valintakenttinä, ja jokainen hintaa näyttävä lohko toistaa kenttäparin, otsakkeet ja niiden yhteisen logiikan. Artikkelin metatiedoissa siitä tulee kaksi avainta ja toistimessa kaksi rinnakkaista luetteloa.
Mukautettu kenttätyyppi kokoaa parin yhdeksi kentäksi. Rekisteröit esimerkiksi tyypin acme/price kerran kohteissa PHP ja JavaScript, minkä jälkeen voit käyttää sitä missä tahansa block.json-kohteessa natiivikentän tavoin: ylimmällä tasolla, ryhmissä ja toistimissa, artikkelin metatietojen tai asetusten tallennuksessa sekä malleissa PHP, Twig ja Blade. Blockstudio johtaa rekisteröinnistä WordPress-attribuutin ja tallennuksen REST-skeeman.
Tämä eroaa mukautetusta kentästä. custom/{name}-viittaus käyttää uudelleen olemassa olevien kenttien ryhmää. Mukautettu kenttätyyppi lisää uuden ohjaimen, jolla on oma arvorakenteensa.
Tässä oppaassa rakennetaan acme/price alusta loppuun: PHP-rekisteröinti, editorin ohjaus, hinnoittelulohko, joka käyttää kenttää sekä ylimmällä tasolla että toistimessa, artikkelin metatietojen tallennus tiukalla REST-skeemalla ja tulostettu sisältö.
Rekisteröi tyyppi kohteessa PHP
PHP-puoli määrittää attribuutin tyypin, oletusarvon, ohjaimen tarjoavan editoriskriptin ja tavan, jolla arvo tallennetaan lohkon ulkopuolelle:
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 on attribuutin WordPress-tyyppi, tässä tapauksessa object. storage.type on arvotyyppi, jota käytetään, kun kenttä tallennetaan artikkelin metatietoihin tai asetuksiin. storage.rest_schema on skeema, jota vasten WordPress validoi REST-kirjoitukset. Ilman rest_schema-määritystä oliot saavat sallivan skeeman, joka hyväksyy kaikki ominaisuudet.
Rekisteröi kohteessa init oletusprioriteetilla. Blockstudio löytää lohkot myöhään kohteessa init, ja tyyppi, jota ei ole siihen mennessä rekisteröity, jää pois luoduista lohkoattribuuteista.
bs_register_field_type() palauttaa arvon true onnistuessaan ja false, jos nimi tai määritys on virheellinen. Nimien on oltava pienaakkosilla kirjoitettuja, nimiavaruudellisia ja tavuviivamuotoisia. Kaksi nimiavaruutta on varattu:
| Nimi | Tulos |
|---|---|
acme/price |
true |
Acme/Price |
false, ei pienaakkosilla |
custom/price |
false, varattu uudelleenkäytettäville kenttäryhmille |
blockstudio/price |
false, varattu Blockstudio-ytimelle |
bs_unregister_field_type() poistaa rekisteröinnin, ja blockstudio/field_types-suodatin hyväksyy samat määritykset nimillä avaimiksi järjestettynä taulukkona.
Rakenna editorin ohjaus
Edellä rekisteröity skripti tarjoaa komponentin React. Se käyttää editorissa jo ladattuja WordPress-komponentteja, joten koontivaihetta ei tarvita:
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 });
},
}),
),
);
},
});
Komponentti saa kaikki kentän määrityksen ominaisuudet, joten kohteeseen block.json lisäämäsi avain currencies välittyy sille arvona props.currencies. Se saa myös vakaat ominaisuudet: value, onChange, field, defaultValue, attributes, block, clientId, disabled ja inRepeater sekä arvon repeaterId, kun se piirretään toistimen rivin sisällä. onChange tallentaa arvon täsmälleen annetussa muodossa. Mukautetut arvot ohittavat normalisoinnin, jota natiivikentät select, radio, color ja gradient käyttävät.
Kuten ensimmäisillä riveillä tehdään, varmista, etteivät arvot ole muita kuin olioita. Ennen kentän olemassaoloa tallennetun tai rakenteeltaan erilaisen lohkon pitäisi silti avautua editorissa.
Blockstudio ottaa acme-field-price-skriptin käyttöön lohkoeditorissa vain, jos kohdetta acme/price käyttävä lohko on rekisteröity. Jos ohjaimen rekisteröinti epäonnistuu, editori säilyttää tallennetun arvon ja näyttää kentän sijaan ilmoituksen, jota ei voi muokata. Käyttöliittymässä arvo näkyy silti.
Käytä sitä lohkossa
Hinnoittelulohko käyttää tyyppiä kahdesti: kerran aloitushintaan, jota voi hakea lohkon ulkopuolelta, ja kerran jokaisella porrastoistimen rivillä:
{
"$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"
}
}
]
}
]
}
}
Kenttätason default ohittaa rekisterin oletusarvon. Blockstudio muuttaa molemmat kentät rekisteröinnin mukaisiksi WordPress-attribuuteiksi. Rekisteröity lohkotyyppi sisältää:
{
"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" }
}
]
}
}
Tulosta arvo
Arvo on mallissa tavallinen taulukko. Rajaa se ennen käyttöä, sillä tallennettu arvo on vain yhtä luotettava kuin viimeisin siihen kirjoittanut toiminto:
<?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() on tärkeä. Kun toistimessa ei ole rivejä, malli saa arvoksi false eikä tyhjää taulukkoa, ja paljas foreach sen päällä aiheuttaa PHP-varoituksen. @var-rivi selitetään alla kohdassa staattinen analyysi.
Hinnoittelulohkon tulostus aloitushinnalla ja kahdella hintaportaalla:
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>
Kun tietoja ei ole lainkaan, kentän oletusarvo tulee voimaan ja lohko tulostetaan ilman portaita arvolla From 19.00 EUR. Twig ja Blade lukevat saman arvon kuin a.price.amount ja $a['price']['amount'], ja laajennus-malleissa siihen pääsee käsiksi arvona {attributes.price.amount}.
Tallennus ja REST-skeema
Molemmissa kentissä on postMeta-tallennus, joten Blockstudio rekisteröi lohkoa rakentaessaan kaksi meta-avainta. Ylimmän tason kenttä käyttää rekisteröityä tallennusskeemaa sellaisenaan:
{
"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
}
}
}
Toistimen sisällä oleva kenttä tallentaa yhden arvon riviä kohden, joten sen meta-avain perustuu taulukkoon ja samasta skeemasta tulee alkioskeema:
{
"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
}
}
}
}
Lohkon sisältävän artikkelin tallentaminen synkronoi molemmat avaimet. Edellä mainittujen kahden hintaportaan kanssa get_post_meta( $id, 'acme_price', true ) palauttaa arvon {"amount":19,"currency":"EUR"} ja acme_tier_prices palauttaa rivihintojen luettelon:
[
{ "amount": 19, "currency": "EUR" },
{ "amount": 49, "currency": "EUR" }
]
Molemmat avaimet näkyvät artikkelin REST-vastauksessa kohteessa meta, ja REST-kirjoitukset validoidaan skeemaa vasten. Pienillä kirjaimilla kirjoitettu valuutta hylätään:
{
"code": "rest_invalid_pattern",
"message": "meta.acme_price[currency] does not match pattern ^[A-Z]{3}$.",
"data": { "status": 400 }
}
Meta on kopio. Artikkelin sisällön lohkoattribuutit pysyvät lähteenä, ja jokainen tallennus synkronoi ne uudelleen määritettyihin avaimiin. Siksi suoraan metaan kirjoitettu arvo korvataan, kun artikkeli tallennetaan seuraavan kerran. Asetusten tallennus toimii samalla tavoin kohteen register_setting() kautta. Mukautetut kenttätyypit, myös toistimien taulukkomuotoinen tallennus, ovat käytettävissä versiosta Blockstudio 7.5.0 lähtien.
Staattinen analyysi
PHPStan-laajennus tuntee sisäänrakennetut kenttätyypit, mutta ei projektissa suorituksen aikana rekisteröityjä tyyppejä. Kun lohko käyttää tyyppiä acme/price, laajennus ilmoittaa kenttätyypin tuntemattomaksi ja määrittää sen arvon tyypiksi mixed:
2 block.json field "price" has unknown type "acme/price" in
blockstudio/pricing/block.json
🪪 blockstudio.blockJson.type
Ohita tämä diagnostiikkailmoitus projektin omien tyyppien osalta projektin määrityksissä ja säilytä mallin rajaus. Sitä tarvitaan, jotta PHPStan hyväksyy mixed-arvon tasolla max:
parameters:
level: max
ignoreErrors:
-
identifier: blockstudio.blockJson.type
message: '#unknown type "acme/price"#'
Näillä määrityksillä ja edellä esitetyllä mallilla analyysi onnistuu. Versiossa 7.6 malli tarvitsee myös rivin @var, jossa mukautettujen kenttien kohdilla käytetään arvoja mixed. Blockstudio 7.7 päättelee rakenteen itse, joten rivin voi poistaa. Katso Tarkistetut mallit kohteella PHPStan-analyysin suorittamisesta.
Seuraavat vaiheet
- Mukautetut kenttätyypit: kaikki määritysavaimet, suodatin API ja täydellinen luettelo komponentin ominaisuuksista.
- Tallennus: artikkelin metatietojen ja asetusten tallennus kaikille kentille.
- Kenttämallien keittokirja: ryhmät, toistimet ja uudelleenkäytettävät kenttärakenteet.
- Mukautetut kentät: uudelleenkäytettävät kenttäryhmät kohteen
custom/{name}kautta.