Главная / Блог / Handle стилей в WordPress

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' ) ) {
  // Стиль находится в очереди или подключен как зависимость.
}

Второй вызов полезен в условной логике шаблона: не ставить дубли и не снимать то, что не поставлено.

Частые вопросы

Чтобы не пропустить новые материалы

Короткий дайджест вечером в понедельник. Без спама.

Выберите, что получать

Обсудим ваш проект

Расскажите о вашем бизнесе, покажите текущий сайт или просто опишите задачу в свободной форме. Я изучу вводные, предложу решение и сориентирую по срокам и смете.

Отвечаю в течение нескольких часов в рабочее время.

Защита от спама – Yandex SmartCaptcha

Если вам удобнее обсудить всё текстом без заполнения форм – напишите напрямую: в Telegram или на sergei@kruglov.net

Удобнее голосом? Напишите пару слов о задаче - договоримся об удобном времени созвона на 15-20 минут, и я пришлю свой номер телефона.