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é
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
- 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.
