useBlockProps et apiVersion 2 : ce qui change pour vos blocs

Un an après son introduction avec WordPress 5.6 en décembre 2020, apiVersion 2 a eu le temps de se stabiliser dans l’écosystème, et la plupart des blocs créés depuis l’utilisent par défaut via @wordpress/create-block. Reste que beaucoup de blocs plus anciens, écrits sous apiVersion 1, continuent de fonctionner sans avoir été migrés — ce qui pousse à se demander ce qui change concrètement, et si la migration est réellement nécessaire.

Ce que apiVersion 1 faisait automatiquement

Sous apiVersion 1 (la valeur implicite quand la clé n’est pas déclarée), Gutenberg enveloppait automatiquement le rendu d’un bloc dans un élément conteneur, en y ajoutant lui-même la classe wp-block-nom-du-bloc et les attributs d’accessibilité nécessaires. Le développeur n’avait aucun contrôle direct sur cette enveloppe : elle apparaissait toujours, qu’elle soit voulue ou non.

Ce que apiVersion 2 change

Avec apiVersion 2, cette enveloppe automatique disparaît. À la place, le développeur doit explicitement appeler le hook useBlockProps, qui renvoie l’ensemble des props (classe, attributs ARIA, référence) à répartir sur l’élément racine du bloc, à la fois dans edit et dans save.

{
	"apiVersion": 2,
	"name": "mon-projet/encart",
	...
}

// edit.js
import { useBlockProps } from '@wordpress/block-editor';

export default function Edit() {
	const blockProps = useBlockProps();
	return <div { ...blockProps }>Contenu de l'encart</div>;
}

// save.js
import { useBlockProps } from '@wordpress/block-editor';

export default function save() {
	const blockProps = useBlockProps.save();
	return <div { ...blockProps }>Contenu de l'encart</div>;
}

Notez la différence entre useBlockProps() côté edit et useBlockProps.save() côté save : le premier ajoute des props supplémentaires liées à l’interactivité de l’éditeur (référence DOM pour la sélection, notamment), le second reste volontairement minimal, cohérent avec un rendu statique final.

Pourquoi ce changement a du sens

Sous apiVersion 1, un bloc ne pouvait pas facilement contrôler sur quel élément portait réellement la classe de bloc, ni ajouter ses propres classes ou attributs sur ce même élément sans manipulation fragile. useBlockProps permet de fusionner ses propres props avec celles générées par Gutenberg, sans conflit :

const blockProps = useBlockProps( {
	className: 'mon-projet-encart--accentue',
} );

Ce mécanisme ouvre aussi la voie à des blocs dont l’élément racine n’est plus systématiquement un <div> : un <section>, un <figure>, ou toute balise sémantiquement plus adaptée, tant que useBlockProps y est correctement appliqué.

Migrer un bloc existant : la marche à suivre

1. Ajouter "apiVersion": 2 dans le block.json du bloc concerné.
2. Importer useBlockProps depuis @wordpress/block-editor dans edit.js et save.js.
3. Appeler le hook et répartir ses props sur l’élément racine, en fusionnant avec les props déjà existantes du bloc.
4. Ajouter une déprécation si le HTML sauvegardé change de structure, pour que le contenu déjà publié continue de se valider correctement.

Ce dernier point mérite une attention particulière : changer la structure du save() sans déprécation associée invalide le contenu déjà publié avec l’ancienne version, provoquant l’apparition d’un bloc marqué comme invalide dans l’éditeur pour tous les articles existants.

Faut-il migrer tous les blocs existants maintenant

• Un bloc stable, qui ne reçoit plus de développement actif, peut légitimement rester en apiVersion 1 tant qu’il fonctionne correctement : les deux versions coexistent sans conflit sur un même site.
• Un bloc en développement actif, ou dont le rendu doit évoluer, gagne à migrer dès maintenant pour bénéficier du contrôle plus fin sur l’élément racine.
• Un nouveau bloc doit systématiquement démarrer en apiVersion 2, ce que fait déjà @wordpress/create-block par défaut depuis plusieurs mois.

Une migration précipitée, sans déprécation associée, casse plus de contenu qu’elle n’en améliore : mieux vaut un bloc en apiVersion 1 stable qu’un bloc en apiVersion 2 mal migré.

Pour aller plus loin

D’autres évolutions de l’API des blocs sont attendues dans les prochaines versions majeures de WordPress, avec des changements plus profonds annoncés pour le rendu de l’éditeur lui-même. Cette page fera l’objet d’un suivi séparé le moment venu, sans attendre cette échéance pour tirer parti dès maintenant de ce que apiVersion 2 apporte.