apiVersion 3 et l’éditeur iframé : ce qui change pour 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

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.