Opbygning af en brugerdefineret felttype
Nogle værdier består af mere end én primitiv værdi. En pris er et beløb og en valuta. Med indbyggede felter modellerer du den som et talfelt og et valgfelt side om side, og hver blok, der viser en pris, gentager parret, etiketterne og logikken, der holder dem sammen. I indlægsmeta bliver det til to nøgler, og i et gentagelsesfelt til to parallelle lister.
En brugerdefineret felttype samler parret i ét felt. Du registrerer en type som
acme/price én gang i PHP og i JavaScript og bruger den derefter i enhver
block.json som et indbygget felt: på øverste niveau, i grupper og gentagelsesfelter,
med lagring i indlægsmeta eller indstillinger samt i skabelonerne PHP, Twig og Blade.
Blockstudio udleder attributten WordPress og lagringsskemaet REST fra registreringen.
Dette er noget andet end et brugerdefineret felt.
En custom/{name}-reference genbruger en gruppe af eksisterende felter. En brugerdefineret felttype
tilføjer en ny styring med sin egen værdistruktur.
Denne vejledning opbygger acme/price fra start til slut: registreringen af PHP,
editorstyringen, en prisblok, der bruger den på øverste niveau og i et gentagelsesfelt,
lagring i indlægsmeta med et strengt REST-skema og det viste output.
Registrér typen i PHP
PHP-delen angiver attributtypen, standardværdien, editorscriptet, der leverer styringen, og hvordan værdien gemmes uden for blokken:
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 er attributtypen for WordPress, her object. storage.type er
dataværditypen, der bruges, når feltet gemmes i indlægsmeta eller indstillinger, og
storage.rest_schema er det skema, som WordPress validerer REST-skrivninger imod.
Uden en rest_schema får en objektværdi et lempeligt skema, der accepterer
alle egenskaber.
Registrér på init med standardprioriteten. Blockstudio finder blokke sent
på init, og en type, der ikke er registreret inden da, udelades fra de
genererede blokattributter.
bs_register_field_type() returnerer true ved succes og false, hvis navnet
eller definitionen er ugyldig. Navne skal være med små bogstaver, have et navnerum og bruge bindestreger,
og to navnerum er reserveret:
| Navn | Resultat |
|---|---|
acme/price |
true |
Acme/Price |
false, ikke små bogstaver |
custom/price |
false, reserveret til genbrugelige feltgrupper |
blockstudio/price |
false, reserveret til Blockstudio-kernen |
bs_unregister_field_type() fjerner en registrering igen, og filteret blockstudio/field_types accepterer de samme definitioner som et array indekseret efter navn.
Byg editorstyringen
Scriptet, der blev registreret ovenfor, leverer komponenten React. Det bruger komponenterne WordPress, der allerede er indlæst i editoren, så det kræver intet byggetrin:
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 modtager alle egenskaber fra feltdefinitionen, så nøglen currencies, du angiver i block.json, modtages som props.currencies. Den modtager også stabile props: value, onChange, field, defaultValue,
attributes, block, clientId, disabled og inRepeater med
repeaterId, når den vises i en række i et gentagelsesfelt. onChange gemmer værdien
præcis som angivet. Brugerdefinerede værdier springer den normalisering af indstillinger over, som indbyggede felter af typerne
select, radio, color og gradient udfører.
Kontrollér, at værdierne er objekter, som de første linjer gør. En blok, der blev gemt, før feltet fandtes, eller med en anden struktur, skal stadig kunne åbnes i editoren.
Blockstudio indlæser acme-field-price i blokeditoren kun, når en blok,
der bruger acme/price, er registreret. Hvis scriptet ikke registrerer styringen,
beholder editoren den gemte værdi og viser en ikke-redigerbar besked i stedet for feltet,
og frontend viser stadig værdien.
Brug den i en blok
En prisblok bruger typen to gange: én gang til en startpris, der skal kunne forespørges på uden for blokken, og én gang for hver række i et gentagelsesfelt med prisniveauer:
{
"$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"
}
}
]
}
]
}
}
Et feltværdiniveau default har forrang over standardværdien i registret. Blockstudio gør begge
felter til WordPress-attributter fra registreringen. Den registrerede bloktype indeholder:
{
"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" }
}
]
}
}
Vis værdien
I skabelonen er værdien et almindeligt array. Begræns typen, før du bruger den, for en gemt værdi er kun så pålidelig som det seneste sted, der skrev til den:
<?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() er vigtig. Et gentagelsesfelt uden rækker kommer til skabelonen som
false, ikke som et tomt array, og et ubetinget foreach over det udløser en PHP-advarsel.
Linjen @var forklares under statisk
analyse nedenfor.
Sådan vises blokken med en startpris og to prisniveauer:
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>
Uden data anvendes feltets standardværdi, og blokken vises som From 19.00 EUR uden prisniveauer. Twig og Blade læser den samme værdi som a.price.amount og $a['price']['amount'], og
skabeloner med extension kan tilgå den som
{attributes.price.amount}.
Lagring og skemaet REST
Begge felter angiver lagring i postMeta, så Blockstudio registrerer to metanøgler,
når blokken oprettes. Feltet på øverste niveau bruger lagringsskemaet fra registreringen uændret:
{
"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
}
}
}
Feltet i gentagelsesfeltet gemmer én værdi pr. række, så dets metanøgle er arraybaseret, og det samme skema bliver elementschemaet:
{
"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 et indlæg, der indeholder blokken, gemmes, synkroniseres begge nøgler. Med de to prisniveauer ovenfor returnerer get_post_meta( $id, 'acme_price', true )
{"amount":19,"currency":"EUR"}, og acme_tier_prices returnerer listen med priser for rækkerne:
[
{ "amount": 19, "currency": "EUR" },
{ "amount": 49, "currency": "EUR" }
]
Begge nøgler vises i indlæggets svar fra REST under meta, og skrivninger til REST valideres mod skemaet. En skrivning med en valuta med små bogstaver afvises:
{
"code": "rest_invalid_pattern",
"message": "meta.acme_price[currency] does not match pattern ^[A-Z]{3}$.",
"data": { "status": 400 }
}
Meta er en kopi. Blokattributterne i indlæggets indhold forbliver kilden,
og hver lagring synkroniserer dem igen med de konfigurerede nøgler. Derfor erstattes en værdi, der skrives direkte til
meta, næste gang indlægget gemmes. Lagring i indstillinger fungerer på samme måde via register_setting(). Brugerdefinerede felttyper, herunder
arraybaseret lagring i gentagelsesfelter, har været tilgængelige siden Blockstudio 7.5.0.
Statisk analyse
Udvidelsen PHPStan kender de indbyggede felttyper, men ikke dem,
et projekt registrerer ved kørsel. For en blok, der bruger acme/price,
rapporterer den felttypen som ukendt og angiver værditypen som mixed:
2 block.json field "price" has unknown type "acme/price" in
blockstudio/pricing/block.json
🪪 blockstudio.blockJson.type
Ignorér denne diagnosticering for dine egne typer i projektkonfigurationen, og
behold typebegrænsningen i skabelonen, som PHPStan skal bruge for at acceptere
værdien mixed på niveau max:
parameters:
level: max
ignoreErrors:
-
identifier: blockstudio.blockJson.type
message: '#unknown type "acme/price"#'
Med denne konfiguration og skabelonen ovenfor består analysen. På 7.6
kræver skabelonen også linjen @var med mixed på pladserne for de
brugerdefinerede felter. Fra og med 7.7 udleder Blockstudio selv den struktur, så linjen
kan fjernes. Se Kontrollerede skabeloner med PHPStan for
at køre analysen.
Næste trin
- Brugerdefinerede felttyper: alle definitionsnøgler, filteret API og den fulde liste over komponentprops.
- Lagring: lagring i indlægsmeta og indstillinger for alle felter.
- Felttypeopskrifter: grupper, gentagelsesfelter og genbrugelige feltstrukturer.
- Brugerdefinerede felter: genbrugelige feltgrupper via
custom/{name}.