Comment ajouter du JavaScript personnalisé aux thèmes WordPress

Vous souhaitez ajouter du JavaScript personnalisé à votre thème WordPress. Il peut s’agir d’un effet de défilement, d’un snippet de suivi tiers ou d’une fonctionnalité interactive. Vous collez le code dans votre fichier de template, et rien ne fonctionne — ou pire, vous mélangez PHP et JavaScript et tout se casse.

Cela arrive constamment. La solution est simple : utilisez le système de gestion de scripts intégré à WordPress au lieu de coder en dur des balises <script>.

Pourquoi vous devriez mettre en file d’attente les scripts dans WordPress

WordPress fonctionne sur un écosystème complexe de thèmes et d’extensions. Lorsque vous insérez du JavaScript directement dans les templates, vous créez des problèmes :

• Chargement en double : Plusieurs extensions peuvent charger la même bibliothèque.
• Échecs de dépendances : Votre script s’exécute avant le chargement de ses dépendances.
• Problèmes de cache : Les navigateurs ne peuvent pas mettre en cache correctement les scripts inline.
• Conflits : Les scripts interfèrent les uns avec les autres sans coordination.

La fonction wp_enqueue_script résout ces problèmes en permettant à WordPress de gérer l’ordre de chargement des scripts, les dépendances et l’emplacement de sortie.

La méthode correcte pour ajouter du JavaScript à WordPress

Étape 1 : Créer votre fichier JavaScript

Placez votre JavaScript dans le répertoire de votre thème. Une structure courante :

your-theme/
├── js/
│   └── custom.js
├── functions.php
└── style.css

Écrivez du JavaScript propre sans mélanger de PHP :

document.addEventListener('DOMContentLoaded', function() {
    // Your code here
});

Étape 2 : Mettre le script en file d’attente dans functions.php

Ajoutez ceci au fichier functions.php de votre thème :

function mytheme_enqueue_scripts() {
    wp_enqueue_script(
        'mytheme-custom',                              // Handle
        get_template_directory_uri() . '/js/custom.js', // Source
        array(),                                        // Dependencies
        '1.0.0',                                        // Version
        array( 'in_footer' => true )                   // Load in footer
    );
}
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_scripts' );

Pour les thèmes enfants, utilisez get_stylesheet_directory_uri() au lieu de get_template_directory_uri().

Comprendre les paramètres de wp_enqueue_script

La fonction accepte cinq paramètres :

Chargement conditionnel des scripts

Ne chargez pas les scripts partout lorsqu’ils ne sont nécessaires que sur des pages spécifiques :

function mytheme_enqueue_scripts() {
    if ( is_singular( 'post' ) ) {
        wp_enqueue_script( 'mytheme-post-scripts', /* ... */ );
    }

    if ( is_page( 'contact' ) ) {
        wp_enqueue_script( 'mytheme-contact-form', /* ... */ );
    }
}
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_scripts' );

Stratégies de chargement axées sur les performances

WordPress 6.3 a introduit la prise en charge native du chargement defer et async :

wp_enqueue_script(
    'mytheme-analytics',
    get_template_directory_uri() . '/js/analytics.js',
    array(),
    '1.0.0',
    array(
        'in_footer' => true,
        'strategy'  => 'defer'
    )
);

Defer exécute les scripts après l’analyse du DOM tout en maintenant leur ordre déclaré. Async exécute les scripts immédiatement une fois téléchargés, sans ordre garanti. Utilisez defer dans la plupart des cas et async pour les scripts indépendants comme les outils d’analyse.

WordPress moderne : modules de scripts et intégration de blocs

WordPress continue de faire évoluer sa gestion du JavaScript. Deux développements méritent d’être notés :

API Script Modules : WordPress 6.5 a introduit wp_enqueue_script_module() pour les modules ES natifs. Cela permet des modèles JavaScript modernes avec des imports de modules appropriés.

Thèmes basés sur les blocs : Si vous créez des blocs, déclarez les scripts dans block.json en utilisant les champs viewScript ou viewScriptModule plutôt que la mise en file d’attente manuelle. WordPress gère le chargement automatiquement lorsque le bloc est rendu.

Ces approches fonctionnent parallèlement à la mise en file d’attente traditionnelle — choisissez en fonction des besoins de votre projet.

Conclusion

L’ajout de JavaScript personnalisé aux thèmes WordPress nécessite l’utilisation du système de mise en file d’attente, et non des balises script codées en dur. Créez des fichiers JavaScript séparés, enregistrez-les avec wp_enqueue_script, déclarez correctement les dépendances et utilisez le chargement conditionnel pour éviter les requêtes inutiles. Pour de meilleures performances, exploitez les stratégies defer et async disponibles depuis WordPress 6.3.

Le modèle est simple : gardez PHP et JavaScript séparés, laissez WordPress gérer le chargement, et vos scripts fonctionneront de manière fiable à travers les thèmes et les extensions.

FAQ

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.