Créer un type de champ personnalisé
Certaines valeurs comportent plusieurs éléments primitifs. Un prix comprend un montant et une devise. Avec les champs intégrés, vous le modélisez avec un champ numérique et un champ de sélection côte à côte, et chaque bloc qui affiche un prix répète la paire, les libellés et la logique qui les associe. Dans les métadonnées de publication, cela devient deux clés et, dans un répétiteur, deux listes parallèles.
Un type de champ personnalisé réunit ces éléments dans un seul champ. Vous enregistrez un type tel que
acme/price une fois, dans PHP et dans JavaScript, puis vous l’utilisez dans n’importe quel
block.json comme un champ natif : au niveau supérieur, dans des groupes et des répétiteurs, avec le stockage des métadonnées de publication ou des options, ainsi que dans les modèles PHP, Twig et Blade. Blockstudio déduit l’attribut WordPress et le schéma de stockage REST à partir de l’enregistrement.
Il s’agit d’autre chose qu’un champ personnalisé.
Une référence custom/{name} réutilise un groupe de champs existants. Un type de champ personnalisé ajoute un nouveau contrôle doté de sa propre forme de valeur.
Ce guide crée acme/price de bout en bout : l’enregistrement PHP, le contrôle de l’éditeur,
un bloc de tarification qui l’utilise au niveau supérieur et dans un répétiteur,
le stockage des métadonnées de publication avec un schéma REST strict et le rendu du résultat.
Enregistrer le type dans PHP
La partie PHP déclare le type d’attribut, la valeur par défaut, le script de l’éditeur qui fournit le contrôle et la façon dont la valeur est stockée hors du bloc :
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 est le type d’attribut WordPress, ici object. storage.type est
le type de valeur utilisé lorsque le champ est stocké dans les métadonnées de publication ou les options, et
storage.rest_schema est le schéma WordPress qui valide les écritures REST.
Sans rest_schema, une valeur objet reçoit un schéma permissif qui accepte
n’importe quelles propriétés.
Enregistrez-le sur init avec la priorité par défaut. Blockstudio découvre les blocs tardivement
sur init ; tout type qui n’est pas enregistré à ce moment-là est exclu des
attributs de bloc générés.
bs_register_field_type() renvoie true en cas de réussite et false si le nom
ou la définition est invalide. Les noms doivent être en minuscules, inclure un espace de noms et utiliser le format avec tirets ; deux espaces de noms sont réservés :
| Nom | Résultat |
|---|---|
acme/price |
true |
Acme/Price |
false, pas en minuscules |
custom/price |
false, réservé aux groupes de champs réutilisables |
blockstudio/price |
false, réservé au cœur de Blockstudio |
bs_unregister_field_type() supprime un enregistrement, et le filtre
blockstudio/field_types accepte les mêmes définitions sous forme de tableau indexé
par nom.
Créer le contrôle de l’éditeur
Le script enregistré ci-dessus fournit le composant React. Il utilise les composants WordPress déjà chargés dans l’éditeur ; aucune étape de compilation n’est donc nécessaire :
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 });
},
}),
),
);
},
});
Le composant reçoit toutes les propriétés de la définition du champ. La clé currencies indiquée dans block.json lui parvient donc sous le nom props.currencies. Il reçoit également les propriétés stables suivantes : value, onChange, field, defaultValue, attributes, block, clientId, disabled et inRepeater avec repeaterId lorsqu’il est affiché dans une ligne de répétiteur. onChange stocke la valeur telle quelle. Les valeurs personnalisées ignorent la normalisation des options appliquée aux champs natifs select, radio, color et gradient.
Vérifiez que les valeurs sont des objets, comme le font les premières lignes. Un bloc enregistré avant l’existence du champ ou avec une forme différente doit tout de même pouvoir s’ouvrir dans l’éditeur.
Blockstudio ajoute acme-field-price à l’éditeur de blocs uniquement lorsqu’un bloc
utilisant acme/price est enregistré. Si le script ne parvient pas à enregistrer le contrôle,
l’éditeur conserve la valeur enregistrée et affiche un avis non modifiable à la
place du champ ; l’interface publique affiche toujours la valeur.
Utiliser le champ dans un bloc
Un bloc de tarification utilise ce type à deux endroits : pour un prix de départ consultable hors du bloc, puis pour chaque ligne d’un répétiteur de paliers :
{
"$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"
}
}
]
}
]
}
}
Une valeur default au niveau du champ a priorité sur la valeur par défaut du registre. Blockstudio transforme les deux
champs en attributs WordPress issus de l’enregistrement. Le type de bloc enregistré contient :
{
"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" }
}
]
}
}
Afficher la valeur
Dans le modèle, la valeur est un tableau ordinaire. Vérifiez-en le type avant de l’utiliser, car sa fiabilité dépend uniquement du dernier élément qui l’a écrite :
<?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() est important. Un répétiteur sans ligne apparaît dans le modèle sous la forme false, et non d’un tableau vide ; une expression foreach sans vérification renvoie un avertissement PHP. La ligne @var est expliquée dans la section sur l’analyse statique ci-dessous.
Rendu du bloc avec un prix de départ et deux paliers :
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>
Sans aucune donnée, la valeur par défaut du champ s’applique et le bloc est affiché From 19.00 EUR sans palier. Twig et Blade lisent la même valeur que a.price.amount et $a['price']['amount'], et les modèles d’extension peuvent y accéder sous le nom {attributes.price.amount}.
Stockage et schéma REST
Les deux champs déclarent un stockage postMeta ; Blockstudio enregistre donc deux clés méta lors de la création du bloc. Le champ de niveau supérieur utilise tel quel le schéma de stockage enregistré :
{
"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
}
}
}
Le champ du répétiteur stocke une valeur par ligne ; sa clé méta repose donc sur un tableau et le même schéma devient le schéma des éléments :
{
"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
}
}
}
}
L’enregistrement d’une publication contenant le bloc synchronise les deux clés. Avec les deux paliers ci-dessus, get_post_meta( $id, 'acme_price', true ) renvoie
{"amount":19,"currency":"EUR"} et acme_tier_prices renvoie la liste des prix
des lignes :
[
{ "amount": 19, "currency": "EUR" },
{ "amount": 49, "currency": "EUR" }
]
Les deux clés apparaissent dans la réponse REST de la publication, sous meta, et les écritures de REST sont
validées par rapport au schéma. Une écriture avec une devise en minuscules est rejetée :
{
"code": "rest_invalid_pattern",
"message": "meta.acme_price[currency] does not match pattern ^[A-Z]{3}$.",
"data": { "status": 400 }
}
Les métadonnées sont une copie. Les attributs de bloc dans le contenu de la publication restent la source,
et chaque enregistrement les synchronise à nouveau avec les clés configurées. Une valeur directement écrite dans
les métadonnées est donc remplacée au prochain enregistrement de la publication. Le stockage des options fonctionne
de la même façon avec register_setting(). Les types de champs personnalisés, y compris le stockage fondé sur des tableaux dans les répétiteurs, sont disponibles depuis Blockstudio 7.5.0.
Analyse statique
L’extension PHPStan connaît les types de champs intégrés, mais pas
ceux enregistrés à l’exécution dans un projet. Pour un bloc qui utilise acme/price,
elle signale le type de champ comme inconnu et attribue à sa valeur le type mixed :
2 block.json field "price" has unknown type "acme/price" in
blockstudio/pricing/block.json
🪪 blockstudio.blockJson.type
Ignorez ce diagnostic pour vos propres types dans la configuration du projet et
conservez la vérification de type dans le modèle ; elle est nécessaire pour que PHPStan accepte la valeur mixed au niveau max :
parameters:
level: max
ignoreErrors:
-
identifier: blockstudio.blockJson.type
message: '#unknown type "acme/price"#'
Avec cette configuration et le modèle ci-dessus, l’analyse réussit. Dans la version 7.6,
le modèle a également besoin de la ligne @var, avec mixed aux emplacements des champs
personnalisés ; Blockstudio 7.7 déduit cette forme automatiquement, et la ligne peut être supprimée. Consultez Modèles vérifiés avec PHPStan pour exécuter l’analyse.
Étapes suivantes
- Types de champs personnalisés : chaque clé de définition, le filtre API et la liste complète des propriétés du composant.
- Stockage : stockage des métadonnées de publication et des options pour tous les champs.
- Recueil de modèles de champs : groupes, répétiteurs et structures de champs réutilisables.
- Champs personnalisés : groupes de champs réutilisables avec
custom/{name}.