Как добавить пользовательский 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

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

Параметр	Назначение	Пример
$handle	Уникальный идентификатор	'mytheme-custom'
$src	URL файла	get_template_directory_uri() . '/js/file.js'
$deps	Необходимые скрипты, которые должны загрузиться первыми	array( 'jquery' )
$ver	Строка версии для сброса кеша	'1.0.0'
$args	Стратегия загрузки и расположение	array( 'in_footer' => true, 'strategy' => 'defer' )

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

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

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 управлять загрузкой, и ваши скрипты будут надежно работать во всех темах и плагинах.

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

Могу ли я использовать wp_enqueue_script для загрузки внешних скриптов из CDN?

Да. Вместо передачи пути к локальному файлу в качестве источника укажите полный URL внешнего скрипта. Например, используйте https://cdn.example.com/library.min.js в качестве второго параметра. WordPress выведет тег скрипта с этим URL. Вы по-прежнему можете устанавливать зависимости, версионность и стратегию загрузки как обычно.

Что происходит, если я дважды поставлю в очередь один и тот же идентификатор скрипта?

WordPress игнорирует повторные регистрации. После того как идентификатор поставлен в очередь, все последующие вызовы с тем же идентификатором пропускаются. Это предотвращает многократную загрузку одного и того же скрипта, что является одним из главных преимуществ системы постановки в очередь перед ручным добавлением тегов скриптов в шаблоны.

Как передать данные PHP в файл JavaScript, поставленный в очередь?

Используйте функцию wp_localize_script или более новую функцию wp_add_inline_script. wp_localize_script создает JavaScript-объект с вашими данными PHP и прикрепляет его к определенному идентификатору скрипта. Это позволяет передавать значения, такие как URL для AJAX, токены nonce или настройки темы из PHP в ваш JavaScript без смешивания двух языков.

Следует ли мне по-прежнему использовать jQuery в WordPress или переключиться на чистый JavaScript?

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