# 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 laisse le rédacteur choisir à l'aveugle. BlockPreview restitue un vrai rendu miniature du bloc.

- Auteur : WordPress Développement
- Publié le : 2023-04-23
- Mis à jour le : 2026-09-30
- Catégorie : Blocs Gutenberg
- URL : https://www.wpmoderne.fr/blocs/blockpreview-apercu-miniature-variations/

## L’essentiel

- Rend un vrai aperçu, pas une icône statique
- Fonctionne à partir d'un objet bloc complet
- S'intègre à un sélecteur ou une grille personnalisée

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>
	);
}
```

> L'essentiel à retenir : Rend un vrai aperçu, pas une icône statique ; Fonctionne à partir d'un objet bloc complet ; S'intègre à un sélecteur ou une grille personnalisée

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