BlockPreview affiche un aperçu miniature fidèle dans un sélecteur de variations

Un sélecteur de variations qui n’affiche que des libellés texte ou des icônes génériques oblige le rédacteur à choisir à l’aveugle, puis à corriger après coup s’il s’est trompé de mise en page. C’est un défaut d’ergonomie fréquent quand un bloc propose plusieurs variations visuellement très différentes : une galerie en grille contre une galerie en carrousel, par exemple, se distinguent mal avec la même icône.

Le composant BlockPreview, exposé par @wordpress/block-editor, corrige ce problème en rendant un véritable aperçu miniature du bloc tel qu’il apparaîtra une fois inséré, à partir de sa structure réelle plutôt que d’une image statique préparée à l’avance.

Ce que BlockPreview rend réellement

Contrairement à une capture d’écran figée, BlockPreview prend en entrée un tableau d’objets bloc (au format retourné par createBlock ou stocké dans une variation) et exécute un rendu React complet dans un cadre isolé, à échelle réduite. Le résultat suit donc fidèlement toute évolution du bloc source : si le style par défaut change, l’aperçu change avec lui, sans qu’il soit nécessaire de régénérer la moindre image.

Utilisation dans un sélecteur de variations personnalisé

1. Définir les variations dans block.json ou via registerBlockVariation, avec leurs attributs et éventuellement leurs innerBlocks par défaut.
2. Construire, pour chaque variation, un objet bloc avec createBlock( nomDuBloc, attributs, innerBlocks ).
3. Passer cet objet (ou un tableau contenant cet objet) à la propriété blocks de BlockPreview.
4. Envelopper le composant dans un conteneur de taille fixe, car BlockPreview applique une mise à l’échelle relative à son parent.

import { BlockPreview } from '@wordpress/block-editor';
import { createBlock } from '@wordpress/blocks';

function AperçuVariation( { nom, attributs, innerBlocks } ) {
	const bloc = createBlock( nom, attributs, innerBlocks );

	return (
		<div className="apercu-variation">
			<BlockPreview blocks={ bloc } viewportWidth={ 800 } /></blockpreview>
		</div>
	);
}

Le rôle de viewportWidth

La propriété viewportWidth détermine la largeur virtuelle utilisée pour calculer le rendu avant réduction, indépendamment de la taille réelle du conteneur qui l’affiche. Une valeur proche de la largeur habituelle du contenu (souvent entre 600 et 900 pixels selon le thème) donne un aperçu proportionné ; une valeur trop petite écrase la mise en page et fausse la lecture visuelle de la variation, en particulier pour des blocs pensés pour un affichage large.

Un point d’attention sur la performance

Chaque instance de BlockPreview effectue un rendu React à part entière, ce qui a un coût réel dès qu’un sélecteur affiche simultanément une dizaine de variations ou plus. Sur un inserteur personnalisé proposant de nombreuses variations d’un même bloc complexe, il est préférable de ne monter les aperçus visibles à l’écran (via un défilement virtualisé, par exemple) plutôt que l’ensemble de la liste d’un coup.

Différence avec le rendu natif de l’inserteur de blocs

L’inserteur natif de WordPress utilise déjà BlockPreview en interne pour afficher les vignettes de blocs et de variations dans son panneau latéral : rien à faire de particulier pour en bénéficier si les variations sont déclarées via registerBlockVariation avec une propriété example correctement renseignée. Le recours manuel au composant devient utile lorsqu’on construit une interface de sélection sur mesure, en dehors de l’inserteur standard (un panneau de choix de mise en page à l’ouverture d’un modèle, par exemple).

• Variations déclarées avec example : l’inserteur natif gère l’aperçu sans code supplémentaire.
• Interface de sélection personnalisée : BlockPreview doit être appelé explicitement.
• Grand nombre de variations affichées ensemble : prévoir un rendu progressif pour préserver la fluidité de l’éditeur.

Ce que BlockPreview ne fait pas

Le composant ne gère ni l’interaction (clic pour insérer, survol pour agrandir), ni la génération des variations elles-mêmes : il se contente de rendre visuellement un objet bloc déjà construit. La logique de sélection, l’insertion effective via insertBlock et la définition des variations restent entièrement à la charge du développeur qui construit l’interface autour de lui.

En résumé

BlockPreview transforme un choix abstrait entre plusieurs libellés en un choix visuel appuyé sur le rendu réel du bloc. Le gain d’ergonomie est net dès que les variations diffèrent sensiblement à l’œil, au prix d’une vigilance sur le nombre d’instances rendues simultanément. Pour un inserteur personnalisé, c’est l’un des rares composants qui rapproche vraiment l’expérience de sélection de ce que verra ensuite le rédacteur.