RichText dans un bloc Gutenberg : formats, placeholder et multiline maîtrisés

La confusion la plus fréquente chez les développeurs qui découvrent Gutenberg : croire que RichText est un simple champ de saisie de texte enrichi, alors qu’il s’agit en réalité d’un composant à deux visages, l’un pour l’édition, l’autre pour la sauvegarde, qui doivent rester rigoureusement synchronisés.

Le duo RichText et RichText.Content

Côté edit, RichText est le composant interactif, celui que l’utilisateur voit et manipule dans l’éditeur. Côté save, RichText.Content ne fait que reproduire le HTML final à partir de la même valeur, sans aucune interactivité — c’est un composant de rendu pur.

// edit
import { RichText } from '@wordpress/block-editor';

<RichText
	tagName="p"
	value={ attributes.content }
	onChange={ ( content ) => setAttributes( { content } ) }
	placeholder="Écrivez votre texte…"
/>

// save
import { RichText } from '@wordpress/block-editor';

export default function save( { attributes } ) {
	return <RichText.Content tagName="p" value={ attributes.content } />;
}

Le tagName doit être identique des deux côtés : c’est lui qui détermine la balise HTML générée (p, h3, li…). Un décalage entre les deux, même minime, produit une différence de structure entre ce que l’éditeur affiche et ce que le front rend réellement.

Restreindre les formats disponibles

Par défaut, un champ RichText autorise tous les formats inline enregistrés sur le site : gras, italique, lien, et tout format personnalisé ajouté via registerFormatType. Pour un champ qui ne doit accepter, par exemple, que du gras et des liens, allowedFormats restreint la liste sans désactiver le mécanisme de formatage lui-même :

<RichText
	tagName="span"
	value={ attributes.legende }
	onChange={ ( legende ) => setAttributes( { legende } ) }
	allowedFormats={ [ 'core/bold', 'core/link' ] }
	placeholder="Légende de l'image…"
/>

Un tableau vide (allowedFormats={ [] }) désactive tout formatage inline, ce qui convient à un champ de type titre court ou légende technique où la mise en forme n’a pas de sens.

Gérer plusieurs paragraphes avec multiline

Par défaut, un RichText refuse les sauts de paragraphe : appuyer sur Entrée insère un saut de ligne simple ou ne fait rien, selon la configuration. Pour un champ qui doit accepter plusieurs paragraphes dans un seul attribut (plutôt que de forcer une structure d’InnerBlocks), la prop multiline change ce comportement :

<RichText
	tagName="div"
	multiline="p"
	value={ attributes.description }
	onChange={ ( description ) => setAttributes( { description } ) }
/>

Avec multiline="p", chaque appui sur Entrée crée un nouveau <p> à l’intérieur du conteneur div. Cette approche reste plus légère qu’InnerBlocks quand le besoin se limite à du texte structuré, sans qu’aucun de ces paragraphes n’ait besoin d’être un bloc à part entière avec ses propres réglages.

Le placeholder, un détail qui compte

Un placeholder vide ou générique (« Texte… ») laisse l’utilisateur deviner ce qui est attendu. Un placeholder contextuel, qui décrit le rôle exact du champ dans le bloc, réduit nettement les questions de support sur des blocs par ailleurs bien conçus.

• Préférer un placeholder qui donne un exemple concret plutôt qu’une description abstraite du champ.
• Ne jamais utiliser le placeholder comme unique explication d’un champ complexe : un texte d’aide sous le champ, dans l’inspecteur, reste plus visible une fois le champ rempli.

Un piège classique : oublier value au niveau racine

Si l’attribut lié à un RichText n’a pas de type rich-text ou de source html correctement déclarée dans block.json, le contenu peut se dupliquer ou disparaître après un enregistrement. Le type d’attribut et le composant doivent être pensés ensemble, jamais l’un sans l’autre.

Sur les blocs à champ unique, la tentation est grande de sauter RichText pour un simple <p> avec le texte en dur : cela fonctionne jusqu’au jour où un client demande à pouvoir mettre un mot en gras, et il faut alors tout reprendre.

En résumé

Maîtriser la paire RichText / RichText.Content, ainsi que allowedFormats et multiline, couvre la quasi-totalité des besoins de texte éditable dans un bloc. La création de formats personnalisés supplémentaires reste un sujet distinct, à traiter une fois cette base bien assimilée.