Comment un développeur de blocs peut-il proposer un réglage de marge qui ressemble, au pixel près, à celui que WordPress affiche déjà pour les blocs natifs ? La réponse tient dans deux composants du paquet @wordpress/components : UnitControl et sa version composée à quatre côtés, BoxControl. Ce guide explique comment les assembler pour un contrôle d’espacement homogène, sans reproduire la gestion des attributs PHP qui l’accompagne côté serveur.
L’enjeu n’est pas seulement esthétique. Un champ numérique fait maison, sans gestion d’unité, oblige l’utilisateur à deviner si la valeur saisie s’exprime en pixels ou en pourcentage, et casse la cohérence visuelle du panneau latéral. Voici la marche à suivre, étape par étape.
Étape 1 : importer les bons composants
Le paquet @wordpress/components expose UnitControl pour une valeur unique et BoxControl pour quatre valeurs liées ou indépendantes (haut, droite, bas, gauche). Les deux se combinent facilement dans un InspectorControls :
import { InspectorControls } from '@wordpress/block-editor';
import { PanelBody, __experimentalBoxControl as BoxControl } from '@wordpress/components';Selon la version de WordPress, BoxControl peut encore être préfixé par __experimentalBoxControl ; il convient de vérifier, au moment de l’écriture du code, si le composant a déjà été stabilisé dans la version de @wordpress/components utilisée par le projet.
Étape 2 : déclarer l’attribut au bon format
WordPress attend un objet avec quatre clés pour représenter une marge à quatre côtés, chaque valeur combinant un nombre et une unité sous forme de chaîne :
{
"attributes": {
"margeBloc": {
"type": "object",
"default": {
"top": "0px",
"right": "0px",
"bottom": "0px",
"left": "0px"
}
}
}
}
Étape 3 : brancher BoxControl sur l’attribut
Une fois l’attribut déclaré, le composant se branche par ses props values et onChange, exactement comme n’importe quel champ contrôlé de React :
<PanelBody title="Espacement">
<BoxControl
label="Marge du bloc"
values={ attributes.margeBloc }
onChange={ ( margeBloc ) => setAttributes( { margeBloc } ) }
units={ [
{ value: 'px', label: 'px' },
{ value: 'em', label: 'em' },
{ value: 'rem', label: 'rem' },
{ value: '%', label: '%' },
] }
/>
</PanelBody>Ce composant gère seul l’icône de lien entre les quatre côtés : cliquée, elle synchronise les quatre valeurs sur celle du champ modifié.
Étape 4 : restituer la valeur en style inline ou en classe
Restituer l’attribut demande ensuite de générer soit un style inline via getBlockProps, soit une variable CSS personnalisée, à consommer dans la feuille de style du bloc :
const style = {
'--marge-haut': attributes.margeBloc.top,
'--marge-droite': attributes.margeBloc.right,
'--marge-bas': attributes.margeBloc.bottom,
'--marge-gauche': attributes.margeBloc.left,
};Étape 5 : vérifier la cohérence visuelle avec l’éditeur natif
Une fois le contrôle en place, il reste à comparer visuellement le panneau du bloc personnalisé avec celui d’un bloc natif comme le bloc Groupe : même hauteur de champ, même position de l’icône de lien, même liste d’unités disponibles. C’est cette cohérence, plus que la fonctionnalité brute, qui distingue un bloc bien intégré d’un bloc qui semble étranger à l’éditeur.
- Vérifier que le clavier permet d’incrémenter la valeur avec les flèches, comme dans les champs natifs.
- Confirmer que le changement d’unité ne réinitialise pas la valeur numérique saisie.
- Tester le contrôle avec une valeur négative si le contexte du bloc l’autorise, par exemple pour un décalage.
Un contrôle de réglage qui ne partage pas les mêmes unités que l’éditeur natif finit toujours par produire un contenu visuellement incohérent d’un bloc à l’autre : mieux vaut réutiliser les composants existants que réinventer un champ approximatif.
En résumé
UnitControl et BoxControl ne sont pas de simples raccourcis : ils garantissent qu’un bloc personnalisé propose la même expérience de réglage d’espacement que les blocs natifs, avec la même gestion d’unités et le même comportement de lien entre les côtés. Passer par ces composants plutôt que par un champ numérique maison évite une incohérence visible dès le premier réglage, et fait gagner un temps de développement réel sur chaque nouveau bloc à espacement configurable.
