useBlockProps()

Définition : useBlockProps() est un hook du paquet @wordpress/block-editor qui fournit les propriétés de l’élément racine d’un bloc dans l’éditeur. Il contribue aux classes, aux interactions et aux supports configurés.

Comprendre et utiliser

À quoi cela sert ?

Il aide WordPress à identifier correctement la zone éditable et à appliquer les comportements visuels attendus. L’enveloppe du bloc n’est pas seulement une décoration HTML.

Comment cela fonctionne ?

Appeler le hook dans le composant edit et déployer ses propriétés sur l’élément englobant du bloc. Il fonctionne avec les conventions modernes des versions de Block API.

Dans quel contexte l’utiliser ?

Utiliser ce hook lors du développement de nouveaux blocs, particulièrement lorsqu’on ajoute des classes CSS personnalisées ou des réglages de couleur et d’espacement.

Cas concret : ATOOLPHA

Le bloc « Résumé » ATOOLPHA possède une bordure propre tout en restant sélectionnable normalement dans l’éditeur.

Exemple de code commenté

Extrait documentaire : le contexte WordPress du plugin/éditeur et les dépendances décrites sont nécessaires ; ne pas coller dans le contenu d’une page.

const { useBlockProps } = wp.blockEditor;
const { createElement } = wp.element;
function EditSummary() {
    const props = useBlockProps( { className: 'atoolpha-summary' } );
    return createElement( 'div', props, 'Résumé technique' );
}

Décryptage de l’exemple

Le hook restitue un objet de propriétés d’enveloppe que l’élément div reçoit directement. La classe personnalisée complète les propriétés fournies par WordPress.

Résultat attendu

L’éditeur peut reconnaître, sélectionner et styliser normalement le bloc. Le code reste un composant à raccorder à une définition de bloc complète.

Atelier pratique de vérification

Créer un bloc d’exemple qui utilise useBlockProps() sur son élément racine. Vérifier la sélection du bloc et la présence des classes automatiques. Retirer temporairement le déploiement des propriétés dans une copie puis constater les différences. Restaurer enfin le comportement attendu et tester au clavier.

Précautions et limites

Ne pas appeler useBlockProps() hors d’un composant prévu pour l’éditeur. Il faut aussi vérifier la fonction save et les styles lorsque le bloc est statique.

Contrôle avant intégration dans un plugin

Vérifier la présence des classes et attributs de support en inspectant le DOM éditorial. Une enveloppe incorrecte peut causer des défauts de sélection et d’accessibilité sans produire immédiatement une erreur visible.

À ne pas confondre

useBlockProps() s’emploie dans edit ; useBlockProps.save() construit les propriétés correspondantes dans save pour le HTML persisté.

Diagnostic et dépannage avancés

Si la sélection du bloc est instable ou que les classes attendues manquent, inspecter l’élément racine du composant edit et vérifier qu’il reçoit les props du hook.