Aller au contenu
Thèmes

Les styles du thème enfant WordPress ne se chargent pas

Le style.css de votre thème enfant ne se charge pas parce que WordPress ne le met pas en file d'attente à votre place. La feuille de styles du thème enfant doit être enregistrée à la main dans le

Publié

Le style.css de votre thème enfant ne se charge pas parce que WordPress ne le met pas en file d’attente à votre place. La feuille de styles du thème enfant doit être enregistrée à la main dans le functions.php du thème enfant, et cet enqueue comporte presque toujours l’un de deux défauts : soit il est carrément absent, soit il se charge sans déclarer la feuille de styles du parent comme dépendance, si bien que vos règles atterrissent au mauvais endroit dans la cascade et se font écraser. Corrigez l’enqueue et les styles reviennent. La vieille astuce @import que vous avez probablement copiée d’un tutoriel de 2013 n’est pas la bonne solution.

Pourquoi ça arrive

Un thème enfant classique se compose de deux fichiers obligatoires : un style.css avec un bloc d’en-tête nommant le parent, et un functions.php. La ligne Template: de l’en-tête indique à WordPress de quel parent hériter les templates. C’est la seule chose que WordPress fait automatiquement. Il lit l’en-tête, met en place le fallback des templates, et s’arrête là. Il ne met jamais en file d’attente votre style.css enfant sur le front-end.

Le thème parent, de son côté, met en file d’attente sa feuille de styles depuis son functions.php, accroché à wp_enqueue_scripts. Votre functions.php enfant s’exécute en premier, puis celui du parent, puis tout ce qui est sur ce hook se déclenche. Si votre thème enfant n’appelle jamais wp_enqueue_style pour son propre fichier, le navigateur ne le demande jamais. La page ressemble au thème parent brut parce que c’est exactement ce qu’elle est.

Le second échec est plus subtil. Vous mettez en file d’attente la feuille de styles enfant, elle se charge, mais vos surcharges ne font rien. C’est un problème d’ordre de chargement. Quand deux règles ont la même spécificité, c’est celle qui se charge en dernier qui l’emporte. Si votre CSS enfant se charge avant celui du parent, le parent gagne à chaque égalité. C’est le tableau de dépendances de wp_enqueue_style qui force l’ordre.

Encore une chose que les gens confondent : get_template_directory_uri() pointe vers le dossier du thème parent, et get_stylesheet_directory_uri() pointe vers le dossier du thème actif (l’enfant). Intervertissez-les et vous mettez en file d’attente le style.css du parent une deuxième fois sans jamais toucher à celui de l’enfant.

La solution, dans l’ordre

D’abord, confirmez ce qui se charge réellement. Ouvrez la page cassée, affichez le code source, et cherchez le nom du dossier de votre thème enfant. WordPress rend les styles mis en file d’attente sous la forme <link id="handle-css" href="..."> — le id, c’est votre handle suivi de -css. Si votre style.css enfant n’est pas du tout dans le <head>, c’est que l’enqueue ne s’exécute pas. S’il est là mais que les styles ne s’appliquent pas, c’est un problème de dépendance ou d’ordre. Cette seule vérification vous dit lequel des deux défauts vous avez.

Ensuite, trouvez le vrai handle du parent. La plupart des thèmes modernes (Astra, GeneratePress, les thèmes Twenty-*) mettent déjà en file d’attente leur propre feuille de styles sous un handle précis — astra-theme-css, generate-style-css, twenty-twenty-four-style, et ainsi de suite. Il vous faut cette chaîne exacte. Faites un grep sur le thème parent, ou lisez-la depuis le <link id="...-css"> dans le code source (retirez le -css final).

Puis, écrivez l’enqueue. Dans le cas courant où le parent charge déjà sa propre feuille de styles, vous ne remettez pas le parent en file d’attente. Vous ne mettez que l’enfant en file d’attente, et vous listez le handle du parent comme dépendance pour que le vôtre se charge après lui :

<?php
add_action( 'wp_enqueue_scripts', 'child_enqueue_styles', 20 );

function child_enqueue_styles() {
    wp_enqueue_style(
        'child-style',
        get_stylesheet_directory_uri() . '/style.css',
        array( 'astra-theme-css' ), // <-- the parent's REAL handle
        wp_get_theme()->get( 'Version' )
    );
}

Si le thème parent ne met pas en file d’attente sa propre feuille de styles (certains thèmes plus anciens ou minimalistes s’appuient sur @import), alors mettez les deux en file d’attente, et faites dépendre l’enfant du parent :

<?php
add_action( 'wp_enqueue_scripts', 'child_enqueue_styles' );

function child_enqueue_styles() {
    wp_enqueue_style(
        'parent-style',
        get_template_directory_uri() . '/style.css'
    );
    wp_enqueue_style(
        'child-style',
        get_stylesheet_directory_uri() . '/style.css',
        array( 'parent-style' ),
        wp_get_theme()->get( 'Version' )
    );
}

L’argument wp_get_theme()->get('Version') est votre cache-buster. Incrémentez la ligne Version: dans l’en-tête du style.css enfant et les navigateurs rechargent le fichier. Omettez-le et vous modifierez le CSS en jurant que rien ne change alors que c’est juste du cache.

Si functions.php contient une erreur de syntaxe, tout le fichier plante silencieusement et aucun de vos enqueues ne s’exécute — ce qui se présente exactement comme « les styles ne se chargent pas ». Activez WP_DEBUG, ou collez votre debug.log dans notre décodeur de journal d’erreurs WordPress pour repérer l’erreur critique rapidement.

Ce qu’il ne faut pas faire

N’utilisez pas @import. Le conseil de l’époque du Codex était de mettre @import url("../parenttheme/style.css"); en haut du style.css enfant. Ça marche, mais c’est lent — le navigateur ne peut pas commencer à télécharger le CSS du parent tant qu’il n’a pas analysé le CSS de l’enfant, donc les deux requêtes s’enchaînent en série au lieu de tourner en parallèle. Le propre manuel de WordPress le déconseille depuis des années. Si votre tutoriel vous a dit de faire ça, c’est ce tutoriel qui explique pourquoi vos styles sont bancals.

Ne codez pas en dur le handle 'parent-style' en mettant le fichier parent en file d’attente à l’aveugle. Le fameux snippet du Codex fait exactement ça, et c’est faux pour tout thème qui enregistre déjà sa feuille de styles sous un handle différent. Vous finissez par charger le CSS du parent deux fois et votre dépendance pointe vers un handle qui n’existe peut-être pas.

N’appelez pas wp_enqueue_style au niveau supérieur de functions.php. Il doit s’exécuter à l’intérieur d’une fonction accrochée à wp_enqueue_scripts. Appelé trop tôt, il ne fait rien.

Ne copiez pas tout le functions.php du parent dans l’enfant. Les deux se chargent ; celui de l’enfant s’exécute en premier. Le copier provoque des déclarations de fonctions en double et une erreur critique.

Une réserve : tout ceci concerne les thèmes classiques (à templates PHP). Si votre parent est un thème de blocs, le style passe surtout par theme.json et l’éditeur de site, et les surcharges de style.css se comportent différemment — là, je me méfierais davantage et je testerais directement plutôt que de supposer que cet enqueue est la solution.

Toujours bloqué ?

Vérifiez que la ligne Template: de l’en-tête du style.css enfant correspond exactement au nom du dossier du parent, en respectant la casse — pas au nom d’affichage du parent. Réexaminez ensuite le code source : handle présent, chargé après le parent, chaîne de requête de version incrémentée. Si le <link> est là, chargé en dernier, et que le CSS ne s’applique toujours pas, ce n’est plus un problème d’enqueue — c’est de la spécificité, et la solution se déplace vers les règles elles-mêmes.