# useBlockProps et apiVersion 2 : ce qui change pour vos blocs

> WordPress 5.6 a introduit apiVersion 2 et le hook useBlockProps. Un an plus tard, l'impact réel sur les blocs existants et la marche à suivre pour migrer.

- Auteur : Clément Hadrot
- Publié le : 2021-12-30
- Mis à jour le : 2021-12-30
- Catégorie : Blocs Gutenberg
- URL : https://wpmoderne.dev.wordpress-developpement.fr/blocs/useblockprops-apiversion-2-blocs/

## L’essentiel

- apiVersion 2 retire l'enveloppe automatique du bloc
- useBlockProps doit être appelé dans edit et save
- La migration reste locale à chaque bloc, sans effet de bord global

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

> L'essentiel à retenir : apiVersion 2 retire l'enveloppe automatique du bloc ; useBlockProps doit être appelé dans edit et save ; La migration reste locale à chaque bloc, sans effet de bord global

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.