Handle стилей в WordPress - что это и зачем он нужен
Handle - это уникальный идентификатор записи о таблице стилей в реестре WP_Styles, по нему WordPress отличает один стиль от другого, выстраивает зависимости и дает отключить или заменить файл без правки шаблона.
Проверка по документации показала: wp_enqueue_style() и wp_register_style() принимают handle первым параметром, документация требует его уникальности. Актуально на ноябрь 2026, сверено с developer.wordpress.org/reference/functions/wp_enqueue_style/.
Handle - не имя файла
Имя файла лежит на диске. Handle живет только в реестре - объекте WP_Styles. Один и тот же файл, подключенный под двумя handle, для WordPress - два разных стиля. Возможна и обратная ситуация: запись с $src = false вообще не имеет файла и работает как алиас для группы зависимостей.
Отсюда три следствия:
- повторный вызов с тем же handle не дублирует
<link>в шапке; - зависимости указываются не путями, а именами handle;
- отключение чужого CSS возможно только если известен его handle.
Регистрация и подключение
Регистрация описывает стиль. Подключение ставит его в очередь на вывод.
add_action( 'wp_enqueue_scripts', function() {
wp_enqueue_style(
'theme-main',
get_stylesheet_uri(),
array(),
'1.0.0'
);
} );
Здесь theme-main - handle. Второй параметр - источник. Третий - зависимости. Четвертый - версия для сброса кэша.
Разделение такое:
| Функция | Что делает | Когда нужна |
|---|---|---|
wp_register_style() | описывает стиль и кладет в реестр без вывода | файл нужен только на части страниц и подключается позже по условию |
wp_enqueue_style() | регистрирует, если передан $src, и ставит в очередь на вывод | стиль нужен всегда, стандартный путь для темы |
wp_dequeue_style() | убирает стиль из очереди, регистрация остается | отключить чужой CSS на конкретном шаблоне |
wp_deregister_style() | удаляет регистрацию полностью | заменить чужой файл своим с сохранением handle |
Нюанс из исходного кода: wp_enqueue_style() при переданном $src вызывает WP_Dependencies::add(), а тот возвращает false и ничего не делает, если handle уже занят. Повторная регистрация с тем же именем не перезаписывает первую. Поэтому переопределение через повторный wp_enqueue_style() не работает, сначала нужен wp_deregister_style().
Зависимости, версия и media
Зависимости - массив handle, а не URL:
wp_enqueue_style(
'theme-page',
get_template_directory_uri() . '/page.css',
array( 'theme-main' ),
'1.0.0'
);
Такая запись выстраивает порядок при условии, что оба handle зарегистрированы к моменту обработки очереди: зависимость не регистрирует отсутствующий стиль. Если theme-main не зарегистрирован, очередь не создаст его автоматически, порядок для него не выстраивается.
Версия работает так: строка добавляется к URL как ?ver= для сброса кэша, false подставляет текущую версию WordPress, null убирает параметр совсем. Для URL с собственной строкой запроса проверяйте итоговый HTML в исходном коде страницы: поведение зависит от версии ядра, при сомнениях null убирает добавление версии.
Параметр $media принимает all, print, screen или медиа-запрос вида (max-width: 640px).
Почему handle должен быть уникальным
Коллизия handle - тихая ошибка. Если тема и плагин используют main-style без префикса, вторая регистрация отклоняется: WP_Dependencies::add() видит занятое имя и возвращает false. В коде остается один <link> вместо двух, в консоли ошибок нет.
Правило одно: префикс темы или плагина в начале handle. theme-main вместо main, myplugin-admin вместо admin. Проверяется поиском по проекту: handle должен встречаться только в ваших вызовах register, enqueue, dequeue, deregister и style_is.
Если вы заменяете чужой файл своим, сохраняйте исходный handle, иначе разорвете чужие зависимости:
add_action( 'wp_enqueue_scripts', function() {
wp_deregister_style( 'plugin-slider' );
wp_enqueue_style(
'plugin-slider',
get_template_directory_uri() . '/css/slider.css',
array(),
'1.0.0'
);
}, 20 );
Приоритет 20 здесь нужен, чтобы ваш код сработал после регистрации оригинала на стандартном приоритете 10. Зависимости, которые ссылались на plugin-slider, сохранят порядок без правок.
Проверка состояния
Перед отключением или заменой проверьте состояние через wp_style_is():
if ( wp_style_is( 'theme-main', 'registered' ) ) {
// Стиль зарегистрирован.
}
if ( wp_style_is( 'theme-main', 'enqueued' ) ) {
// Стиль находится в очереди или подключен как зависимость.
}
Второй вызов полезен в условной логике шаблона: не ставить дубли и не снимать то, что не поставлено.
