Как добавить пользовательский JavaScript в темы WordPress

Вы хотите добавить пользовательский JavaScript в свою тему WordPress. Возможно, это эффект прокрутки, сторонний код отслеживания или интерактивная функциональность. Вы вставляете код в файл шаблона, и ничего не работает — или, что еще хуже, вы смешиваете PHP и JavaScript вместе и ломаете всё.

Это происходит постоянно. Решение простое: используйте встроенную систему управления скриптами WordPress вместо жесткого кодирования тегов <script>.

Почему следует ставить скрипты в очередь в WordPress

WordPress работает в сложной экосистеме тем и плагинов. Когда вы вставляете JavaScript напрямую в шаблоны, вы создаете проблемы:

• Дублированная загрузка: Несколько плагинов могут загружать одну и ту же библиотеку.
• Сбои зависимостей: Ваш скрипт выполняется до загрузки его зависимостей.
• Проблемы с кешированием: Браузеры не могут правильно кешировать встроенные скрипты.
• Конфликты: Скрипты мешают друг другу без координации.

Функция wp_enqueue_script решает эти проблемы, позволяя WordPress управлять порядком загрузки скриптов, зависимостями и местом вывода.

Правильный способ добавления JavaScript в WordPress

Шаг 1: Создайте файл JavaScript

Разместите ваш JavaScript в директории темы. Типичная структура:

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

Пишите чистый JavaScript без примеси PHP:

document.addEventListener('DOMContentLoaded', function() {
    // Ваш код здесь
});

Шаг 2: Поставьте скрипт в очередь в functions.php

Добавьте это в functions.php вашей темы:

function mytheme_enqueue_scripts() {
    wp_enqueue_script(
        'mytheme-custom',                              // Идентификатор
        get_template_directory_uri() . '/js/custom.js', // Источник
        array(),                                        // Зависимости
        '1.0.0',                                        // Версия
        array( 'in_footer' => true )                   // Загрузка в футере
    );
}
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_scripts' );

Для дочерних тем используйте get_stylesheet_directory_uri() вместо get_template_directory_uri().

Понимание параметров wp_enqueue_script

Функция принимает пять параметров:

Условная загрузка скриптов

Не загружайте скрипты везде, когда они нужны только на определенных страницах:

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' );

Стратегии загрузки с учетом производительности

WordPress 6.3 представил встроенную поддержку загрузки defer и async:

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

Defer выполняет скрипты после парсинга DOM, сохраняя их объявленный порядок. Async выполняет скрипты сразу после загрузки, без гарантированного порядка. Используйте defer в большинстве случаев и async для независимых скриптов, таких как аналитика.

Современный WordPress: модули скриптов и интеграция с блоками

WordPress продолжает развивать обработку JavaScript. Два важных нововведения:

API модулей скриптов: WordPress 6.5 представил wp_enqueue_script_module() для нативных ES-модулей. Это позволяет использовать современные паттерны JavaScript с правильным импортом модулей.

Блочные темы: Если вы создаете блоки, объявляйте скрипты в block.json, используя поля viewScript или viewScriptModule, вместо ручной постановки в очередь. WordPress автоматически обрабатывает загрузку при рендеринге блока.

Эти подходы работают наряду с традиционной постановкой в очередь — выбирайте в зависимости от потребностей вашего проекта.

Заключение

Добавление пользовательского JavaScript в темы WordPress требует использования системы постановки в очередь, а не жестко закодированных тегов скриптов. Создавайте отдельные файлы JavaScript, регистрируйте их с помощью wp_enqueue_script, правильно объявляйте зависимости и используйте условную загрузку, чтобы избежать ненужных запросов. Для лучшей производительности используйте стратегии defer и async, доступные с WordPress 6.3.

Паттерн прост: держите PHP и JavaScript раздельно, позвольте WordPress управлять загрузкой, и ваши скрипты будут надежно работать во всех темах и плагинах.

Часто задаваемые вопросы

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.