# Transforms de blocs : convertir un bloc en un autre sans perte de contenu

> from, to, block, raw, shortcode, prefix : panorama des transformations disponibles, avec leurs cas d'usage réels et les pièges de conversion d'attributs.

- Auteur : Clément Hadrot
- Publié le : 2020-11-13
- Mis à jour le : 2020-11-13
- Catégorie : Blocs Gutenberg
- URL : https://wpmoderne.dev.wordpress-developpement.fr/blocs/transforms-de-blocs-convertir-sans-perte/

## L’essentiel

- from et to définissent le sens de la conversion
- Le type prefix déclenche une transformation en tapant un caractère
- Une transformation mal écrite tronque silencieusement le contenu

Un attribut appelé `content` dans un bloc, un attribut appelé `text` dans un autre : voilà la cause la plus fréquente d'un bug classique après transformation de bloc, où le texte disparaît purement et simplement au moment de la conversion. Les transforms de blocs sont pourtant l'une des fonctionnalités les plus élégantes de Gutenberg quand elles sont bien écrites — elles méritent qu'on comprenne leur mécanique avant de les utiliser en production.

## Le principe : from et to

La propriété `transforms` d'un bloc se déclare dans son fichier JavaScript d'enregistrement (elle n'a pas d'équivalent direct dans `block.json` avant les versions récentes de WordPress) et contient deux tableaux : `from`, qui liste les sources depuis lesquelles ce bloc peut être créé, et `to`, qui liste les blocs vers lesquels il peut se transformer.

```
transforms: {
	from: [ /* transformations entrantes */ ],
	to: [ /* transformations sortantes */ ],
}
```

## Type block : convertir un bloc en un autre bloc

Le cas le plus courant : transformer un bloc Citation maison en bloc Citation natif, ou l'inverse.

```
transforms: {
	to: [
		{
			type: 'block',
			blocks: [ 'core/quote' ],
			transform: ( attributes ) => {
				return createBlock( 'core/quote', {
					value: `<p>${ attributes.texte }</p>`,
					citation: attributes.auteur,
				} );
			},
		},
	],
},
```

La fonction `transform` reçoit les attributs du bloc d'origine et doit renvoyer un nouveau bloc construit avec `createBlock`, en mappant explicitement chaque attribut vers son équivalent dans le bloc cible. C'est précisément à cette étape que la perte de contenu survient si un attribut est oublié dans le mappage.

## Type raw : récupérer du HTML collé

> L'essentiel à retenir : from et to définissent le sens de la conversion ; Le type prefix déclenche une transformation en tapant un caractère ; Une transformation mal écrite tronque silencieusement le contenu

Quand un utilisateur colle du HTML brut dans l'éditeur (depuis un autre CMS, par exemple), Gutenberg cherche un bloc capable de le reconnaître via une transformation de type `raw`, basée sur un sélecteur CSS ou une fonction `isMatch` :

```
transforms: {
	from: [
		{
			type: 'raw',
			selector: 'blockquote.pull-quote',
			transform: ( node ) => {
				return createBlock( 'mon-projet/citation-encadree', {
					texte: node.textContent,
				} );
			},
		},
	],
},
```

## Type shortcode : reconnaître un ancien shortcode

Pour une migration progressive d'un site qui utilisait des shortcodes avant l'arrivée des blocs, une transformation `shortcode` reconnaît automatiquement le motif dans le contenu collé ou importé :

```
transforms: {
	from: [
		{
			type: 'shortcode',
			tag: 'produit_vedette',
			attributes: {
				productId: {
					type: 'number',
					shortcode: ( { named: { id } } ) => parseInt( id, 10 ),
				},
			},
		},
	],
},
```

## Type prefix : un raccourci de saisie

Une transformation `prefix` déclenche automatiquement la création d'un bloc dès qu'un caractère donné est tapé en début de ligne dans un paragraphe vide, sur le même principe que `#` pour un titre ou `>` pour une citation :

```
transforms: {
	from: [
		{
			type: 'prefix',
			prefix: '??',
			transform: () => createBlock( 'mon-projet/question-frequente' ),
		},
	],
},
```

## Cas d'usage réels rencontrés en projet

- Convertir un bloc Liste en bloc Colonnes pour transformer une énumération en mise en page visuelle.
- Reconnaître un shortcode `[gallery]` historique et le convertir en bloc Galerie natif lors d'une migration.
- Proposer une transformation entre un bloc « Accordéon simple » maison et le bloc natif Détails, pour laisser le choix à l'utilisateur selon le besoin d'interactivité.

## Le piège principal : les attributs qui ne se correspondent pas

Deux blocs rarement partagent exactement la même structure d'attributs. Une transformation qui copie un attribut de type tableau vers un attribut de type chaîne, sans conversion explicite, produit un contenu illisible ou une erreur silencieuse en console. La règle à retenir : toujours écrire la fonction `transform` comme un mappage explicite, attribut par attribut, jamais comme une simple fusion d'objets.

> Une transformation de bloc qui fonctionne sur un contenu de test vide doit systématiquement être revérifiée sur un contenu réel, avec des caractères spéciaux et des paragraphes multiples : c'est là que les pertes silencieuses apparaissent.

## En résumé

Bien maîtrisées, les transforms de blocs offrent une fluidité de migration et de composition que peu d'éditeurs concurrents proposent nativement. Leur fiabilité tient entièrement à la rigueur du mappage d'attributs écrit dans chaque fonction `transform`, jamais à la magie du système lui-même.