# Ajouter une prévisualisation du thème sombre directement dans l’éditeur

> Basculer l'aperçu de l'éditeur entre variante claire et sombre du thème, sans ouvrir un nouvel onglet, fait gagner un aller-retour à chaque vérification.

- Auteur : Clément Hadrot
- Publié le : 2026-02-05
- Mis à jour le : 2026-02-05
- Catégorie : Tips
- URL : https://wpmoderne.dev.wordpress-developpement.fr/tips/previsualisation-theme-sombre-directement-editeur/

## L’essentiel

- L'éditeur de blocs s'affiche dans un iframe nommé editor-canvas depuis WordPress 6.3
- Un bouton de barre d'outils bascule une classe sur le document de l'iframe
- Aucune duplication de styles nécessaire si theme.json déclare déjà les deux variantes

Une agence de communication avait construit, pour un client du secteur culturel, un thème avec une variante de style sombre déclarée dans `theme.json`, pensée pour les visiteurs qui naviguent en soirée sur les pages d'événements nocturnes. Le problème remonté par la rédactrice en charge des contenus : pour vérifier le rendu d'un article dans les deux variantes, elle devait publier ou prévisualiser, ouvrir un nouvel onglet, basculer le thème du système d'exploitation, puis revenir à l'éditeur pour continuer à travailler — un aller-retour répété à chaque modification.

Depuis que l'éditeur de blocs affiche son contenu dans un iframe dédié (une évolution du cœur de WordPress introduite avec la version 6.3, nommée `editor-canvas`), il devient possible de manipuler directement le document de cet iframe pour y basculer une classe, sans jamais quitter l'écran d'édition.

## Comprendre l'iframe de l'éditeur

Depuis WordPress 6.3, le contenu de l'éditeur de blocs (la zone où s'affichent les blocs eux-mêmes, avec les styles du thème actif) est rendu à l'intérieur d'un `<iframe>` distinct du reste de l'interface d'administration, ce qui garantit que les styles du thème ne viennent jamais interférer avec ceux de l'administration elle-même. Cet iframe porte l'attribut `name="editor-canvas"`, ce qui permet de le cibler précisément depuis un script :

```
function obtenirDocumentEditeur() {
    const iframe = document.querySelector( 'iframe[name="editor-canvas"]' );
    return iframe ? iframe.contentDocument : document;
}
```

La fonction de repli sur `document` couvre le cas, plus rare mais existant, d'un éditeur configuré sans iframe (certaines personnalisations poussées désactivent ce comportement), pour que le script ne casse pas silencieusement dans ce contexte.

## Ajouter un bouton de bascule dans la barre d'outils

> L'essentiel à retenir : L'éditeur de blocs s'affiche dans un iframe nommé editor-canvas depuis WordPress 6.3 ; Un bouton de barre d'outils bascule une classe sur le document de l'iframe ; Aucune duplication de styles nécessaire si theme.json déclare déjà les deux variantes

```
const { registerPlugin } = wp.plugins;
const { PluginMoreMenuItem } = wp.editPost;
const { useState } = wp.element;

function BasculeThemeSombre() {
    const [ sombre, setSombre ] = useState( false );

    const basculer = () => {
        const doc = obtenirDocumentEditeur();
        const racine = doc.documentElement;

        if ( sombre ) {
            racine.removeAttribute( 'data-theme-preview' );
        } else {
            racine.setAttribute( 'data-theme-preview', 'sombre' );
        }

        setSombre( ! sombre );
    };

    return wp.element.createElement(
        PluginMoreMenuItem,
        { icon: 'admin-appearance', onClick: basculer },
        sombre ? 'Revenir au style clair' : 'Prévisualiser le style sombre'
    );
}

registerPlugin( 'bascule-theme-sombre', { render: BasculeThemeSombre } );
```

L'attribut `data-theme-preview="sombre"` posé sur la racine du document de l'iframe sert de simple interrupteur pour du CSS ciblé, sans jamais modifier réellement les réglages du thème enregistrés en base : c'est une prévisualisation locale, purement visuelle, qui disparaît au rechargement de la page.

### Relier l'attribut à la variante de style déclarée dans theme.json

Si le thème déclare déjà sa variante sombre comme un style global alternatif dans `styles/sombre.json`, le plus simple consiste à répliquer les mêmes règles CSS ciblées sur l'attribut, plutôt que de dupliquer entièrement le fichier de styles :

```
[data-theme-preview="sombre"] {
    background-color: #101013;
    color: #f2f2f2;
}

[data-theme-preview="sombre"] a {
    color: #8ab4ff;
}
```

Cette feuille de style ciblée doit être chargée à la fois dans l'iframe de l'éditeur (via `enqueue_block_editor_assets`, en s'assurant qu'elle atteigne bien l'intérieur de l'iframe, ce qui est le comportement par défaut de cette action) et sur le site public, si l'on souhaite proposer la même bascule aux visiteurs.

## Charger le script avec les bonnes dépendances

```
add_action( 'enqueue_block_editor_assets', function () {
    wp_enqueue_script(
        'bascule-theme-sombre',
        get_theme_file_uri( 'inc/js/bascule-theme-sombre.js' ),
        array( 'wp-plugins', 'wp-edit-post', 'wp-element' ),
        wp_get_theme()->get( 'Version' ),
        true
    );

    wp_enqueue_style(
        'bascule-theme-sombre-preview',
        get_theme_file_uri( 'inc/css/apercu-sombre.css' )
    );
} );
```

## Ce que cette technique ne fait pas

Ce mécanisme reste une prévisualisation d'appoint, pas un véritable système de gestion de thème sombre pour les visiteurs du site : il ne modifie ni les réglages enregistrés, ni le rendu affiché en dehors de l'éditeur. Si le site doit proposer une vraie bascule claire/sombre aux visiteurs, cette logique séparée mérite son propre traitement, avec une préférence mémorisée côté visiteur, ce qui sort du cadre de cet aperçu interne à l'équipe éditoriale.

- Testez systématiquement la bascule après une mise à jour majeure du cœur : la structure interne de l'iframe de l'éditeur peut évoluer d'une version à l'autre.
- Ne vous appuyez jamais sur cette classe de prévisualisation dans du code de production destiné aux visiteurs : elle est pensée pour l'éditeur uniquement.
- Documentez la variante de style attendue avec des captures d'écran de référence pour l'équipe éditoriale, l'attribut seul ne suffisant pas à garantir la cohérence visuelle sans validation humaine.

> Sur les thèmes qui proposent une variante de style sombre, je recommande de toujours donner à l'équipe éditoriale un moyen rapide de vérifier le rendu dans les deux variantes avant publication : un contraste insuffisant en mode sombre passe facilement inaperçu si seul le mode clair est vérifié en pratique.

## Ce que ça change au quotidien

Ce petit ajout supprime un aller-retour répétitif entre l'éditeur et un onglet de prévisualisation externe, pour un coût de développement modeste une fois l'existence de l'iframe `editor-canvas` bien comprise. C'est un exemple concret de la façon dont l'architecture technique récente de l'éditeur de blocs ouvre des possibilités d'interface qui n'existaient simplement pas avec les versions antérieures à WordPress 6.3.