Bygga en anpassad fälttyp
Vissa värden består av mer än ett primitivt värde. Ett pris är ett belopp och en valuta. Med inbyggda fält modellerar du det som ett nummerfält och ett urvalsfält bredvid varandra, och varje block som visar ett pris upprepar paret, etiketterna och logiken som håller ihop dem. I inläggsmeta blir det två nycklar och i en upprepning två parallella listor.
En anpassad fälttyp gör paret till ett enda fält. Du registrerar en typ som
acme/price en gång, i PHP och i JavaScript, och använder den sedan i vilken
block.json som helst som ett inbyggt fält: på toppnivå, i grupper och
upprepningar, med lagring i inläggsmeta eller alternativ samt i mallar för PHP, Twig och Blade.
Blockstudio härleder attributet WordPress och lagringsschemat REST från registreringen.
Det här skiljer sig från ett anpassat fält.
En custom/{name}-referens återanvänder en grupp befintliga fält. En anpassad fälttyp
lägger till en ny kontroll med sin egen värdestruktur.
Den här guiden bygger acme/price från början till slut: registreringen av PHP, redigerarkontrollen,
ett prisblock som använder den både på toppnivå och inuti en upprepning,
lagring i inläggsmeta med ett strikt REST-schema samt den renderade utdata.
Registrera typen i PHP
PHP-sidan deklarerar attributtypen, standardvärdet, redigerarskriptet som levererar kontrollen och hur värdet lagras utanför blocket:
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 är attributtypen WordPress, här object. storage.type är
den värdetyp som används när fältet lagras i inläggsmeta eller alternativ, och
storage.rest_schema är schemat som WordPress validerar skrivningar av REST mot.
Utan en rest_schema får ett objektvärde ett tillåtande schema som godkänner
alla egenskaper.
Registrera på init med standardprioritet. Blockstudio hittar block sent
på init, och en typ som inte är registrerad då utelämnas från de
genererade blockattributen.
bs_register_field_type() returnerar true vid framgång och false när namnet
eller definitionen är ogiltig. Namn måste vara gemena, ha namnområde och använda bindestreck,
och två namnområden är reserverade:
| Namn | Resultat |
|---|---|
acme/price |
true |
Acme/Price |
false, inte gemener |
custom/price |
false, reserverat för återanvändbara fältgrupper |
blockstudio/price |
false, reserverat för Blockstudio-kärnan |
bs_unregister_field_type() tar bort en registrering igen, och filtret
blockstudio/field_types accepterar samma definitioner som en array med nycklar efter namn.
Bygg redigerarkontrollen
Skriptet som registrerades ovan tillhandahåller komponenten React. Den använder komponenterna WordPress som redan är inlästa i redigeraren, så den behöver inget byggsteg:
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 });
},
}),
),
);
},
});
Komponenten får alla egenskaper från fältdefinitionen, så nyckeln currencies som du anger i block.json kommer fram som props.currencies. Den får också stabila props: value, onChange, field, defaultValue,
attributes, block, clientId, disabled och inRepeater, med
repeaterId när den renderas inuti en upprepningsrad. onChange lagrar värdet
precis som det anges. Anpassade värden hoppar över den normalisering av alternativ som inbyggda fälten select, radio, color och gradient tillämpar.
Skydda mot värden som inte är objekt, precis som de första raderna gör. Ett block som sparats innan fältet fanns, eller med en annan struktur, ska fortfarande gå att öppna i redigeraren.
Blockstudio lägger till acme-field-price i blockredigeraren endast när ett block
som använder acme/price är registrerat. Om skriptet misslyckas med att registrera
kontrollen behåller redigeraren det sparade värdet och visar ett meddelande som inte går att redigera
i stället för fältet. Gränssnittet visar fortfarande värdet.
Använd det i ett block
Ett prisblock använder typen två gånger: en gång för ett startpris som ska kunna frågas efter utanför blocket, och en gång per rad i en upprepning med prisnivåer:
{
"$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"
}
}
]
}
]
}
}
Ett fältvärde i default har företräde framför registerstandardvärdet. Blockstudio gör båda
fälten till attribut av typen WordPress från registreringen. Den registrerade blocktypen har:
{
"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" }
}
]
}
}
Rendera värdet
I mallen är värdet en vanlig array. Kontrollera dess typ innan du använder det, eftersom ett lagrat värde bara är så pålitligt som det senaste som skrev till det:
<?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() är viktig. En upprepning utan rader når mallen som
false, inte som en tom array, och en fristående foreach över den ger en PHP-varning.
Raden @var förklaras under statisk analys nedan.
Rendera blocket med ett startpris och två prisnivåer:
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>
Utan data används fältets standardvärde, och blocket renderas som From 19.00 EUR utan prisnivåer. Twig och Blade läser samma värde som a.price.amount och $a['price']['amount'], och
mallar för tillägg kan adressera det som
{attributes.price.amount}.
Lagring och REST-schemat
Båda fälten deklarerar lagring i postMeta, så Blockstudio registrerar två metanycklar
när det bygger blocket. Toppnivåfältet använder det registrerade lagringsschemat som det är:
{
"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
}
}
}
Fältet inuti upprepningen lagrar ett värde per rad, så dess metanyckel är arraybaserad och samma schema blir objektschemat:
{
"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
}
}
}
}
När ett inlägg som innehåller blocket sparas synkas båda nycklarna. Med de två prisnivåerna ovan returnerar get_post_meta( $id, 'acme_price', true )
{"amount":19,"currency":"EUR"} och acme_tier_prices returnerar listan med
radpriser:
[
{ "amount": 19, "currency": "EUR" },
{ "amount": 49, "currency": "EUR" }
]
Båda nycklarna visas i inläggets svar från REST under meta, och skrivningar via REST valideras
mot schemat. En skrivning med en valutakod med gemener avvisas:
{
"code": "rest_invalid_pattern",
"message": "meta.acme_price[currency] does not match pattern ^[A-Z]{3}$.",
"data": { "status": 400 }
}
Meta är en kopia. Blockattributen i inläggsinnehållet är fortfarande källan,
och varje sparning synkar dem åter till de konfigurerade nycklarna. Därför ersätts ett värde som skrivits
direkt till meta nästa gång inlägget sparas. Lagring av alternativ fungerar
på samma sätt via register_setting(). Anpassade fälttyper, inklusive
arraybaserad lagring i upprepningar, har funnits sedan Blockstudio 7.5.0.
Statisk analys
Tillägget PHPStanextension känner till de inbyggda fälttyperna, men inte
dem som ett projekt registrerar vid körning. För ett block som använder acme/price
rapporterar det fälttypen som okänd och ger värdet typen mixed:
2 block.json field "price" has unknown type "acme/price" in
blockstudio/pricing/block.json
🪪 blockstudio.blockJson.type
Ignorera diagnostiken för dina egna typer i projektkonfigurationen,
och behåll typkontrollen i mallen. Den gör att PHPStan kan godta
värdet mixed på nivå max:
parameters:
level: max
ignoreErrors:
-
identifier: blockstudio.blockJson.type
message: '#unknown type "acme/price"#'
Med den konfigurationen och mallen ovan går analysen igenom. I 7.6 behöver mallen också raden @var, med mixed på platserna för de
anpassade fälten. I 7.7 härleder Blockstudio den strukturen på egen hand, så raden kan
tas bort. Se Kontrollerade mallar med PHPStan för
information om hur analysen körs.
Nästa steg
- Anpassade fälttyper: alla definitionsnycklar, filtret API och hela listan över komponentens props.
- Lagring: lagring i inläggsmeta och alternativ för alla fält.
- Receptbok för fältmönster: grupper, upprepningar och återanvändbara fältstrukturer.
- Anpassade fält: återanvändbara fältgrupper
via
custom/{name}.