Éditeur iframé et CSS qui ne s’applique plus après apiVersion 3

Une mise à jour de routine d’une extension maison, passant simplement l’apiVersion déclarée de 2 à 3 dans block.json pour bénéficier de useInnerBlocksProps, a suffi à faire disparaître la moitié des styles visuels d’un bloc directement dans l’éditeur, alors que le rendu front restait parfaitement identique. Aucune erreur dans la console, aucune ligne de CSS supprimée par erreur : le fichier de style n’avait pas changé d’un octet. Le symptôme pointait ailleurs, vers un changement structurel plus profond introduit précisément par cette montée de version d’API.

La cause tient à un changement majeur introduit avec l’apiVersion 3 : le contenu de l’éditeur de blocs s’exécute désormais à l’intérieur d’un élément iframe isolé, un document HTML totalement distinct de la page d’administration qui l’englobe. Tout style injecté directement dans le head du document parent, une pratique fréquente avant ce changement pour certains chargements CSS non conventionnels, n’atteint tout simplement plus l’intérieur de cet iframe.

Pourquoi WordPress a isolé l’éditeur dans un iframe

Cette isolation répond à un objectif de fidélité visuelle : en exécutant le contenu de l’éditeur dans son propre document, les styles du thème actif du site s’appliquent naturellement, sans entrer en collision avec les styles de l’interface d’administration elle-même. Avant ce changement, obtenir un rendu fidèle dans l’éditeur nécessitait souvent des astuces de spécificité CSS complexes pour éviter que les styles d’administration ne parasitent l’aperçu du contenu.

Le symptôme précis à reconnaître

Le signe distinctif de ce problème est la coexistence de deux faits en apparence contradictoires : le CSS fonctionne parfaitement sur le front du site, et l’inspection du DOM confirme que les classes CSS attendues sont bien présentes sur les éléments du bloc dans l’éditeur, mais sans qu’aucun style ne leur soit appliqué visuellement. C’est le signe que la feuille de style existe bien, mais qu’elle n’a simplement jamais été chargée à l’intérieur du document de l’iframe.

La cause fréquente : un chargement manuel hors convention

Le cas le plus courant concerne un CSS chargé via un hook générique comme admin_head ou admin_enqueue_scripts, sans dépendance explicite sur wp-edit-post, une pratique qui fonctionnait avant l’iframe car tout partageait le même document, mais qui échoue silencieusement une fois l’éditeur isolé.

// Ne fonctionne plus correctement une fois l'éditeur en iframe
function styles_admin_generiques() {
    wp_enqueue_style( 'mon-agence-editeur', plugins_url( 'editor.css', __FILE__ ) );
}
add_action( 'admin_head', 'styles_admin_generiques' );

La correction : passer par editorStyle

La solution consiste à revenir au canal prévu pour ce cas précis, la propriété editorStyle de block.json, que WordPress se charge d’injecter correctement à l’intérieur du document de l’iframe, quelle que soit l’apiVersion utilisée par ailleurs.

{
  "editorStyle": "file:./editor.css"
}

Pour un chargement plus ponctuel hors du système de blocs, l’action enqueue_block_editor_assets reste également fiable, WordPress se chargeant d’acheminer correctement la feuille de style enregistrée jusqu’à l’intérieur du bon document.

function mon_agence_style_editeur_correct() {
    wp_enqueue_style( 'mon-agence-editeur', plugins_url( 'editor.css', __FILE__ ) );
}
add_action( 'enqueue_block_editor_assets', 'mon_agence_style_editeur_correct' );

Vérifier rapidement l’hypothèse

• Ouvrir les outils de développement du navigateur et inspecter l’élément : est-il bien à l’intérieur d’un iframe nommé editor-canvas ou similaire ?
• Vérifier dans l’onglet réseau si le fichier CSS attendu apparaît deux fois, une pour le document parent, aucune pour l’iframe.
• Confirmer que le rendu front, non concerné par cette isolation, reste correct pendant toute l’investigation.

Un style absent uniquement dans l’éditeur, jamais sur le front, doit immédiatement faire suspecter un problème de canal de chargement lié à l’iframe, avant même d’envisager une erreur de syntaxe CSS.

En résumé

Le passage à l’éditeur iframé avec apiVersion 3 a amélioré la fidélité visuelle de l’éditeur, mais il a aussi rendu obsolètes certaines pratiques de chargement CSS non conventionnelles qui fonctionnaient par accident plutôt que par conception. Un CSS d’éditeur toujours déclaré via editorStyle ou enqueue_block_editor_assets reste, dans tous les cas, la façon la plus sûre de traverser cette isolation sans mauvaise surprise au prochain changement de version d’API.