Un même bloc sert souvent plusieurs usages. Prenez un encadré personnalisé : sur un site éditorial, on peut vouloir un encadré « astuce », un encadré « avertissement », un encadré « à retenir » et un encadré « citation source ». Techniquement, ces quatre usages partagent la même structure, les mêmes attributs, le même code de rendu. Seules changent quelques valeurs par défaut : la couleur de fond, l’icône, le libellé affiché dans l’inserteur.
Plutôt que de créer quatre blocs distincts avec du code dupliqué, Gutenberg propose depuis longtemps un mécanisme dédié à ce besoin : les variations de blocs, via la fonction registerBlockVariation(). Avec la sortie de WordPress 5.9 et l’arrivée de l’édition complète de site, ce mécanisme prend encore plus d’importance, puisque de nombreux blocs de mise en page du thème Twenty Twenty-Two s’appuient dessus. Voyons comment l’exploiter sur vos propres blocs.
Le principe d’une variation
Une variation de bloc n’est pas un nouveau bloc : c’est un jeu de valeurs par défaut (attributs, contenu interne, icône, titre, mots-clés) appliqué à un bloc existant au moment de son insertion. L’utilisateur voit plusieurs entrées dans l’inserteur, mais elles pointent toutes vers le même name de bloc en coulisses. Cela signifie que la logique de rendu, la fonction save, la fonction edit, tout reste commun.
Ce mécanisme est utilisé nativement par WordPress : le bloc core/embed propose ainsi des dizaines de variations (YouTube, Twitter, Vimeo, Spotify…), chacune définissant un providerNameSlug différent et une icône propre, tout en s’appuyant sur exactement le même composant d’édition.
Déclarer une variation côté JavaScript
Reprenons notre bloc encadré du précédent article, wpmoderne/encadre-conseil, et ajoutons-lui des variations. On utilise registerBlockVariation(), généralement dans un fichier séparé chargé après l’enregistrement du bloc :
import { registerBlockVariation } from '@wordpress/blocks';
import { __ } from '@wordpress/i18n';
registerBlockVariation( 'wpmoderne/encadre-conseil', {
name: 'avertissement',
title: __( 'Encadré avertissement', 'wpmoderne' ),
description: __( 'Pour signaler un point de vigilance.', 'wpmoderne' ),
icon: 'warning',
isDefault: false,
attributes: {
variante: 'avertissement',
couleurFond: '#fdf1e8',
},
scope: [ 'inserter' ],
} );
registerBlockVariation( 'wpmoderne/encadre-conseil', {
name: 'a-retenir',
title: __( 'Encadré à retenir', 'wpmoderne' ),
icon: 'star-filled',
attributes: {
variante: 'a-retenir',
couleurFond: '#e8f4fd',
},
} );
Les propriétés clés d’une variation
Chaque objet passé à registerBlockVariation() accepte plusieurs propriétés utiles à connaître.
name: un identifiant unique parmi les variations de ce bloc.titleetdescription: ce que l’utilisateur voit dans l’inserteur.icon: une icône Dashicons ou un SVG, affichée à la place de l’icône par défaut du bloc.attributes: les valeurs d’attributs appliquées automatiquement lors de l’insertion.innerBlocks: pour les blocs conteneurs, une structure de blocs enfants pré-remplie.isDefault: sitrue, cette variation devient la présentation par défaut du bloc dans l’inserteur, à la place du bloc « nu ».scope: contrôle où la variation apparaît : dans l’inserteur (inserter), dans la barre d’outils de transformation de bloc (block), ou les deux.
Pour un bloc conteneur, comme un bloc « Groupe » personnalisé, la propriété innerBlocks permet de pré-remplir une structure entière. Par exemple, une variation « Encadré avec bouton » pourrait insérer automatiquement un bloc paragraphe et un bloc bouton à l’intérieur, prêts à être édités :
registerBlockVariation( 'wpmoderne/encadre-conseil', {
name: 'avec-bouton',
title: __( 'Encadré avec bouton', 'wpmoderne' ),
innerBlocks: [
[ 'core/paragraph', { placeholder: 'Votre texte…' } ],
[ 'core/button', { text: 'En savoir plus' } ],
],
} );Déclarer une variation depuis block.json
Depuis la généralisation de block.json, il est également possible de déclarer des variations statiquement dans ce fichier, via la propriété variations, sans passer par du JavaScript pour les cas les plus simples :
{
"name": "wpmoderne/encadre-conseil",
"variations": [
{
"name": "avertissement",
"title": "Encadré avertissement",
"icon": "warning",
"attributes": {
"variante": "avertissement"
}
}
]
}Cette approche statique est pratique pour des variations simples, mais dès que la logique devient conditionnelle (afficher une variation seulement si une extension tierce est active, par exemple), il faut repasser par registerBlockVariation() en JavaScript, en la conditionnant côté PHP via wp_enqueue_script ou une vérification de fonctionnalité.
Retirer une variation existante
Il est également possible de retirer une variation qui ne correspond pas à votre charte éditoriale, avec unregisterBlockVariation(). C’est utile par exemple pour supprimer certains fournisseurs du bloc core/embed que vous ne souhaitez pas proposer à vos rédacteurs.
import { unregisterBlockVariation } from '@wordpress/blocks';
wp.domReady( () => {
unregisterBlockVariation( 'core/embed', 'tiktok' );
} );Quand préférer les variations à un bloc dédié
La question revient souvent : faut-il créer un nouveau bloc ou une variation ? La règle est simple. Si la structure de données et le rendu HTML restent identiques, et que seules changent des valeurs par défaut ou une présentation dans l’inserteur, la variation est la bonne réponse : elle évite la duplication de code et simplifie la maintenance. Si en revanche le comportement d’édition diffère réellement (des contrôles différents, une structure d’attributs différente), un bloc séparé reste préférable, quitte à factoriser le code commun dans des fonctions partagées.
Conseil maison : limitez-vous à quatre ou cinq variations visibles par bloc. Au-delà, l’inserteur devient difficile à parcourir pour vos rédacteurs, et l’effet « simplification » recherché se retourne contre vous.
En résumé
Les variations de blocs permettent de démultiplier l’usage d’un même bloc sans dupliquer une seule ligne de logique. Elles s’appuient sur un mécanisme simple : des attributs par défaut différents, une présentation différente dans l’inserteur, mais un seul et même bloc en coulisses. Sur un projet éditorial ambitieux, bien penser ses variations dès la conception du bloc fait souvent gagner un temps considérable, aussi bien pour l’équipe technique que pour les rédacteurs qui utilisent l’éditeur au quotidien.
