wp_theme_has_theme_json() adapte une extension selon le thème actif

wp_theme_has_theme_json() — cette fonction du cœur de WordPress répond à une question précise et souvent négligée par les auteurs d’extensions : le thème actuellement actif définit-il ses propres réglages via un fichier theme.json, ou repose-t-il sur une configuration entièrement classique ? La réponse conditionne directement la façon dont une extension doit générer son balisage pour rester visuellement cohérente.

Sur une extension distribuée que je maintiens, ce point s’est posé concrètement : certains styles par défaut codés en dur juraient sur les thèmes qui exposaient une palette personnalisée via theme.json, tout en restant nécessaires pour les thèmes classiques qui n’exposaient rien. Voici comment cette fonction a permis de faire cohabiter les deux cas sans dupliquer tout le code de rendu.

La différence avec wp_is_block_theme()

wp_is_block_theme() répond à une question différente : le thème actif est-il un thème de blocs, avec des gabarits au format HTML plutôt que des fichiers PHP classiques ? Un thème classique peut très bien exposer un theme.json partiel — par exemple pour définir une palette de couleurs ou activer certaines fonctionnalités de l’éditeur — sans pour autant être un thème de blocs. C’est précisément ce cas intermédiaire que wp_theme_has_theme_json() permet de détecter.

var_dump( wp_is_block_theme() );        // false pour un thème classique avec theme.json partiel
var_dump( wp_theme_has_theme_json() );  // true si un fichier theme.json existe et est valide

Le cas d’usage : adapter le rendu d’un bloc de témoignages

L’extension en question ajoute un bloc de témoignages clients, avec un jeu de couleurs par défaut codé dans sa feuille de style. Sur un thème exposant une palette via theme.json, ce jeu de couleurs fixe entrait en contradiction visuelle avec l’identité définie par le thème. La solution : détecter la présence d’un theme.json actif et, dans ce cas, laisser le bloc hériter des couleurs du thème plutôt que d’appliquer ses propres valeurs par défaut.

function extension_temoignages_classe_couleur() {
    if ( wp_theme_has_theme_json() ) {
        return 'has-primary-background-color has-text-color';
    }

    return 'temoignages-couleur-defaut';
}

Charger une feuille de style conditionnelle

Au-delà des classes CSS, l’extension charge une feuille de style différente selon le résultat de la fonction, pour éviter d’imposer des règles CSS en conflit avec les variables générées par le moteur de styles du thème.

add_action( 'wp_enqueue_scripts', function () {
    $feuille = wp_theme_has_theme_json()
        ? 'temoignages-theme-json.css'
        : 'temoignages-classique.css';

    wp_enqueue_style(
        'extension-temoignages',
        plugins_url( 'assets/' . $feuille, __FILE__ ),
        array(),
        '2.3.0'
    );
} );

Un résultat mis en cache par le cœur

Un point rassurant sur le plan des performances : le résultat de wp_theme_has_theme_json() s’appuie sur les données déjà chargées et mises en cache par WP_Theme_JSON_Resolver lors de l’initialisation du thème. Appeler cette fonction plusieurs fois dans une même requête ne provoque donc pas de lecture répétée du fichier sur le disque.

• La fonction retourne un simple booléen, sans argument à fournir.
• Elle fonctionne aussi bien pour un thème parent que pour un thème enfant qui ne fournit pas son propre theme.json mais hérite de celui du parent.
• Elle ne dit rien sur le contenu du theme.json : pour aller plus loin, il faut ensuite interroger WP_Theme_JSON_Resolver::get_merged_data().

La limite à connaître

Cette fonction indique seulement l’existence d’un fichier valide, pas la richesse de son contenu. Un thème peut exposer un theme.json minimal, avec seulement une ou deux propriétés définies, et la fonction retournera tout de même true. Pour une extension qui a besoin de connaître précisément quelles propriétés sont définies (une palette de couleurs par exemple), une vérification complémentaire sur les données fusionnées reste nécessaire.

Sur une extension distribuée à un large public de thèmes différents, je considère cette fonction comme un aiguillage de premier niveau : elle évite d’imposer un rendu qui jurerait avec l’identité visuelle définie par le thème actif, sans prétendre remplacer une inspection complète des réglages exposés.

Notre verdict

wp_theme_has_theme_json() reste une fonction simple, mais elle change concrètement la façon de concevoir le rendu par défaut d’une extension destinée à cohabiter avec des thèmes très différents. Pour toute extension distribuée qui affiche des couleurs ou des styles par défaut, vérifier ce point avant de coder en dur une palette fixe évite bien des tickets de support liés à une identité visuelle incohérente.