# apiVersion 3 et l’éditeur iframé : ce qui change pour vos blocs

> WordPress 6.3 généralise l'éditeur iframé et introduit l'apiVersion 3. Isolation des styles, compatibilité ascendante et pièges à anticiper sur vos blocs.

- Auteur : Clément Hadrot
- Publié le : 2023-09-07
- Mis à jour le : 2023-09-07
- Catégorie : Blocs Gutenberg
- URL : https://wpmoderne.dev.wordpress-developpement.fr/blocs/apiversion-3-editeur-iframe-blocs/

## L’essentiel

- L'éditeur de contenu s'exécute désormais dans un iframe isolé
- Les styles globaux ne fuitent plus entre l'admin et l'aperçu
- La migration vers apiVersion 3 se fait sans réécrire vos blocs

WordPress 6.3, sorti en août dernier, généralise à l'ensemble des types de contenus une évolution amorcée avec l'éditeur de site : le rendu du contenu dans un `<iframe>` isolé, plutôt que directement dans le DOM de la page d'administration. Ce changement, en grande partie invisible pour l'utilisateur final, a des conséquences bien réelles pour qui développe des blocs personnalisés.

Cet article explique ce que l'éditeur iframé change concrètement, ce que recouvre la nouvelle `apiVersion: 3`, et comment migrer un bloc existant sans mauvaise surprise.

## Pourquoi isoler l'éditeur dans un iframe

Avant cette évolution, l'éditeur de blocs partageait le même document HTML que le reste de l'interface d'administration. Concrètement, les styles globaux du thème (chargés pour donner un aperçu fidèle du rendu final) cohabitaient avec les styles de l'interface d'administration elle-même, dans la même feuille de styles cascadée. Des conflits de spécificité CSS apparaissaient régulièrement : une règle du thème pouvait accidentellement modifier l'apparence d'un bouton de la barre d'outils, ou inversement.

En plaçant le canevas d'édition dans un `<iframe>`, WordPress lui donne son propre document HTML, complètement étanche vis-à-vis du reste de l'administration. Les styles du thème s'appliquent exactement comme sur le site public, sans aucune interférence, et sans risque que les styles de l'admin ne viennent polluer l'aperçu.

## Ce que change apiVersion 3

> L'essentiel à retenir : L'éditeur de contenu s'exécute désormais dans un iframe isolé ; Les styles globaux ne fuitent plus entre l'admin et l'aperçu ; La migration vers apiVersion 3 se fait sans réécrire vos blocs

La valeur `apiVersion: 3` dans `block.json` signale à WordPress que le bloc est compatible avec ce rendu iframé. Pour la grande majorité des blocs, la migration se limite littéralement à changer ce chiffre :

```
{
  "apiVersion": 3,
  "name": "wpmoderne/bandeau-alerte",
  "title": "Bandeau d'alerte",
  "category": "widgets",
  "icon": "warning",
  "supports": {
    "color": {
      "background": true,
      "text": true
    }
  }
}
```

Concrètement, les blocs en `apiVersion: 2` continuent de fonctionner sans problème : WordPress les rend simplement en dehors de l'iframe, dans une zone dédiée qui reste compatible avec l'ancien comportement. Il n'y a donc aucune urgence à migrer tous ses blocs d'un coup, mais tout nouveau bloc devrait être créé directement en `apiVersion: 3`.

## Points de vigilance techniques

Le rendu iframé n'est pas totalement transparent pour tous les blocs. Certains points méritent une attention particulière lors de la migration :

- Les scripts qui manipulaient directement le `document` global de la page d'administration (par exemple pour injecter une modale ou lire une variable globale JavaScript) doivent désormais cibler le document de l'iframe, accessible via `window.frameElement` ou les API React fournies par `@wordpress/block-editor`.
- Les styles chargés uniquement pour l'éditeur (via `editorStyle` dans `block.json`) s'appliquent maintenant à l'intérieur de l'iframe, ce qui peut révéler des règles CSS qui dépendaient jusque-là, sans le vouloir, d'une classe globale de l'administration.
- Certains composants tiers qui affichent des popovers ou des tooltips positionnés en `fixed` peuvent nécessiter un ajustement, le calcul de position devant tenir compte du décalage introduit par l'iframe.

Dans la pratique, sur les blocs relativement simples (texte, image, mise en page avec `InnerBlocks`), la migration ne révèle aucun de ces problèmes. Ce sont surtout les blocs avec des interactions JavaScript avancées dans l'éditeur qui demandent une vérification attentive.

### Tester la compatibilité

La meilleure façon de vérifier la compatibilité d'un bloc reste de l'ouvrir dans l'éditeur après avoir simplement changé la valeur d'`apiVersion`, puis de tester l'ensemble des interactions prévues : ajout de contenu, changement d'attributs via l'inspecteur, glisser-déposer si le bloc l'autorise, et bien sûr un contrôle visuel de l'aperçu par rapport au rendu front réel.

## Compatibilité ascendante garantie

Un point rassurant : rien n'oblige à migrer tous les blocs d'un plugin en même temps. Un même thème ou plugin peut parfaitement faire cohabiter des blocs en `apiVersion: 2` et d'autres en `apiVersion: 3`, WordPress gérant chaque bloc indépendamment selon la version déclarée dans son propre `block.json`. Cela permet une migration progressive, bloc par bloc, au rythme des besoins réels du projet.

> Sur nos projets, on profite de chaque montée de version majeure d'un bloc existant pour passer à apiVersion 3 au passage, plutôt que de migrer tout le catalogue d'un coup un week-end. Le risque de régression baisse nettement.

## Faut-il migrer dès maintenant ?

Pour tout nouveau développement, la réponse est simple : oui, sans hésiter. Pour les blocs déjà en production et stables, la question mérite d'être posée projet par projet. Un bloc qui fonctionne parfaitement, sans plan de refonte proche, peut très bien rester en `apiVersion: 2` encore un moment sans risque particulier, WordPress n'ayant annoncé aucune date de dépréciation de cette version de l'API.

## En résumé

L'éditeur iframé, généralisé avec WordPress 6.3, améliore sensiblement la fidélité de l'aperçu et l'isolation entre les styles du thème et ceux de l'administration. La migration vers `apiVersion: 3` se limite le plus souvent à un simple changement de valeur dans `block.json`, avec une vérification attentive pour les blocs qui manipulent directement le DOM de l'éditeur. Aucune urgence à tout migrer d'un coup, mais un réflexe à adopter sur tout nouveau bloc.