L’API selectors de block.json : cibler le CSS généré par vos supports

Un bloc « Carte info » développé en interne posait un problème récurrent : la couleur de fond choisie dans l’inspecteur (via le support color.background) s’appliquait sur le conteneur racine du bloc, alors que le design demandait qu’elle ne colore que le bandeau supérieur interne. La solution habituelle avant WordPress 6.3 consistait à surcharger la classe générée en CSS, avec un sélecteur plus spécifique qui annulait le style inline injecté par l’éditeur — fragile, et perdu dès qu’une nouvelle version de WordPress changeait légèrement la structure de classes.

La clé selectors de block.json, introduite dans WordPress 6.3 (août 2023), règle ce problème à la source : elle indique explicitement à Gutenberg où injecter le CSS généré par chaque support, sans devoir deviner ni surcharger quoi que ce soit après coup.

Le comportement par défaut, et sa limite

Sans selectors, tous les styles générés par les supports (couleur, typographie, marges, bordures) s’appliquent sur l’élément racine du bloc, celui qui reçoit les classes et attributs de useBlockProps() côté éditeur et le wrapper équivalent côté rendu serveur. Pour un bloc simple à un seul niveau de balisage, c’est exactement ce qu’il faut. Pour un bloc au balisage interne plus riche — une carte avec en-tête, corps et pied, par exemple — ce comportement uniforme devient une contrainte de design.

Déclarer des sélecteurs par fonctionnalité

La clé selectors se déclare au niveau racine de block.json, avec une entrée par groupe de support (color, typography, spacing, border…), et peut même descendre au niveau d’une sous-fonctionnalité précise comme color.background ou color.text :

{
    "apiVersion": 3,
    "name": "agence/carte-info",
    "title": "Carte info",
    "supports": {
        "color": {
            "background": true,
            "text": true
        },
        "spacing": {
            "padding": true
        }
    },
    "selectors": {
        "color": {
            "background": ".agence-carte-info__bandeau",
            "text": ".agence-carte-info__corps"
        },
        "spacing": {
            "padding": ".agence-carte-info__corps"
        }
    }
}

Avec cette déclaration, choisir une couleur de fond dans l’inspecteur génère désormais une règle CSS ciblant .agence-carte-info__bandeau, tandis que le padding s’applique à .agence-carte-info__corps — deux éléments distincts du même bloc, chacun stylé indépendamment par les réglages natifs de l’éditeur.

Adapter le rendu PHP en conséquence

Côté render.php, il faut que le balisage produit contienne effectivement ces classes aux bons emplacements. selectors ne génère aucun HTML : il indique seulement où le CSS doit s’appliquer, à charge pour le développeur de faire correspondre le balisage.

<?php
$wrapper_attributes = get_block_wrapper_attributes();
?>
<div <?php echo $wrapper_attributes; ?>>
    <div class="agence-carte-info__bandeau">
        <?php echo esc_html( $attributes['titre'] ?? '' ); ?>
    </div>
    <div class="agence-carte-info__corps">
        <?php echo wp_kses_post( $attributes['contenu'] ?? '' ); ?>
    </div>
</div>

Sélecteurs racine explicites

Une entrée root permet aussi de rediriger l’ensemble du wrapper généré par useBlockProps vers un sélecteur personnalisé, utile quand le bloc a besoin d’un élément racine qui n’est pas le div attendu par défaut :

{
    "selectors": {
        "root": ".agence-carte-info"
    }
}

Ce que selectors ne remplace pas

Cette API concerne uniquement le CSS généré automatiquement par les supports déclarés dans block.json — couleurs, typographie, espacement, bordures, ombres. Elle ne remplace pas les classes de blocs génériques (wp-block-agence-carte-info), toujours présentes, ni les styles personnalisés écrits à la main dans une feuille CSS du bloc, qui continuent de cibler les sélecteurs de leur choix indépendamment. selectors ne s’applique pas non plus aux propriétés issues de theme.json pour les éléments génériques (liens, boutons) : cette clé reste circonscrite aux supports d’un bloc donné.

Vérifier le résultat

Pour valider la configuration, on inspecte simplement l’attribut style injecté sur le bloc dans l’éditeur après avoir changé une couleur : avant 6.3 il apparaît sur le conteneur racine, après une déclaration selectors correcte il apparaît en attribut style sur une règle CSS générée ciblant la classe indiquée (WordPress injecte une feuille de style dédiée avec un sélecteur basé sur l’ID du bloc, pas un style inline direct, ce qui permet la spécificité voulue).

Un piège rencontré sur ce projet : oublier de mettre à jour le balisage du save() côté JavaScript pour les blocs statiques, en ne corrigeant que le render.php. Résultat, l’aperçu dans l’éditeur ne correspondait plus au rendu front tant que les deux fichiers n’étaient pas alignés.

En résumé

La clé selectors de block.json transforme un problème auparavant résolu à coups de CSS de contournement en une simple déclaration structurée, alignée avec le balisage réel du bloc. Dès qu’un bloc a plusieurs niveaux de structure interne et que les supports natifs doivent cibler des éléments différents, cette API évite des heures de débogage de spécificité CSS — à condition de garder le rendu edit() et render.php parfaitement synchronisés.