Главная » Разработка Битрикс » Вёрстка и шаблоны » Подключение CSS и JS в Битрикс правильно

Подключение CSS и JS в Битрикс правильно

Обновлено: 2026 • Раздел: Вёрстка и шаблоны • Просмотров: 13

Схема подключения стилей и скриптов в Битрикс: файлы шаблона проходят через API и попадают в объединение

ОглавлениеАвтоматическое подключение Методы подключения стилей Методы подключения скриптов Сводная таблица Стили внутри компонентов Объединение и сжатие файлов Перенос скриптов в конец страницы Библиотеки ядра Кеширование версий Частые ошибки Итог

Подключить стиль или скрипт в 1С-Битрикс можно пятью разными способами, и они не равнозначны. От выбора зависит, попадёт ли файл в объединение и сжатие, в каком порядке загрузится и не сломается ли вёрстка при включении оптимизации.

Разберём все методы API, объясним, чем SetAdditionalCSS отличается от AddHeadString, и покажем, что делать со сторонними скриптами, которые ядро норовит перенести в конец страницы.

Автоматическое подключение

Два файла в корне шаблона подключаются сами, без единой строки кода:

Файл	Что делает
`template_styles.css`	Основные стили шаблона
`script.js`	Основной скрипт шаблона

Это самый надёжный способ: файлы автоматически участвуют в объединении и сжатии, их не нужно нигде прописывать. Если стилей немного, держите всё в template_styles.css и не усложняйте.

Методы подключения стилей

SetAdditionalCSS

Основной способ подключить дополнительный CSS-файл:

<?php
$APPLICATION->SetAdditionalCSS(SITE_TEMPLATE_PATH . '/assets/css/swiper.css');

Файл попадает в общий пул стилей и участвует в объединении. Именно этот метод стоит использовать по умолчанию.

AddHeadString

Вставляет произвольную строку в <head>:

<?php
$APPLICATION->AddHeadString(
    '<link rel="preload" href="/fonts/inter.woff2" as="font" crossorigin>'
);

Нужен для того, что не является обычным подключением: preload, preconnect, метатеги верификации, favicon. Для обычных стилей использовать не стоит — такой файл не попадёт в объединение.

Помощь по 1С-Битрикс

Возникли проблемы с 1С-Битрикс? Поможем разобраться.

Исправим ошибки, доработаем функционал, ускорим работу сайта или просто подскажем правильное решение. Оставьте номер телефона — свяжемся с вами в ближайшее время.

Методы подключения скриптов

AddHeadScript

<?php
$APPLICATION->AddHeadScript(SITE_TEMPLATE_PATH . '/assets/js/swiper.js');

Подключает JS-файл и включает его в объединение. Обратите внимание: несмотря на название, современные версии Битрикс выносят такие скрипты в конец страницы, если включена соответствующая оптимизация.

AddString

Аналог AddHeadString, но для произвольного HTML в любом месте:

<?php
$APPLICATION->AddString('<script>window.SITE_ID = "s1";</script>');

Сводная таблица

Метод	Для чего	Участвует в объединении
`template_styles.css`	Основные стили шаблона	Да
`script.js`	Основной скрипт шаблона	Да
`SetAdditionalCSS()`	Дополнительные CSS-файлы	Да
`AddHeadScript()`	Дополнительные JS-файлы	Да
`AddHeadString()`	preload, метатеги, favicon	Нет
`AddString()`	Произвольный HTML и инлайн-код	Нет

Стили внутри компонентов

У шаблонов компонентов работает то же правило автоматического подключения. Файлы style.css и script.js в папке шаблона компонента подключаются сами, когда компонент выводится на странице:

/local/templates/main/components/bitrix/news.list/main/
    template.php
    style.css      <- подключится автоматически
    script.js      <- подключится автоматически

Это удобно: стили конкретного блока грузятся только там, где блок есть. Общие механики шаблонов компонентов разобраны в статье Создание компонента в Битрикс.

Объединение и сжатие файлов

В настройках главного модуля включается объединение CSS и JS: все подключённые через API файлы склеиваются в один и отдаются с кешированием. Это заметно сокращает число запросов.

Что важно знать перед включением:

Порядок файлов сохраняется, но относительные пути внутри CSS пересчитываются относительно новой папки. Если в стилях есть url(../img/bg.png), после объединения путь может сломаться. Надёжнее использовать абсолютные пути от корня сайта.
Инлайн-стили и скрипты не объединяются. Всё, что добавлено через AddHeadString, остаётся как есть.
После изменения стилей нужно сбросить кеш. Иначе будет отдаваться старая склейка, и правки не увидите.

Влияние этих настроек на скорость загрузки подробно разобрано в материале Как ускорить сайт на Битрикс для PageSpeed Insights.

Перенос скриптов в конец страницы

Битрикс умеет автоматически переносить JavaScript в конец <body> — это ускоряет отрисовку. Но со сторонними скриптами возникает проблема: код, рассчитанный на выполнение в конкретном месте страницы, после переноса ломается.

Классические жертвы — виджеты чатов, счётчики и формы сторонних сервисов.

Решение — атрибут, запрещающий перенос конкретного блока:

<script data-skip-moving="true">
    /* этот скрипт останется на своём месте */
</script>

Механика подробно разобрана в статье Как отключить перенос JavaScript в подвал страницы.

Библиотеки ядра

Прежде чем подключать стороннюю библиотеку, проверьте, нет ли её в ядре. Битрикс поставляется с набором готовых расширений, которые подключаются одной строкой:

<?php
\Bitrix\Main\UI\Extension::load('ui.buttons');
\Bitrix\Main\UI\Extension::load('ui.notification');

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

Кеширование версий

Браузер кеширует CSS и JS, и после обновления стилей посетитель может видеть старую версию. Битрикс при объединении добавляет к файлу метку версии автоматически. Для файлов, подключённых напрямую через AddHeadString, метку придётся добавлять самому:

<?php
$cssPath = SITE_TEMPLATE_PATH . '/assets/css/style.css';
$version = filemtime($_SERVER['DOCUMENT_ROOT'] . $cssPath);

$APPLICATION->AddHeadString(
    '<link rel="stylesheet" href="' . $cssPath . '?v=' . $version . '">'
);

Частые ошибки

Подключение тегом <link> напрямую в вёрстке. Файл не попадает в объединение, а при включении оптимизации может продублироваться.
Относительные пути в CSS. После объединения файлов url(../img/…) начинает указывать не туда.
Забытый ShowHead() в шаблоне. Ни один вызов SetAdditionalCSS не сработает — выводить стили просто некуда.
Сторонний скрипт без data-skip-moving. Работает до включения оптимизации и ломается после.
Подключение jQuery поверх того, что уже есть в ядре. Две версии библиотеки на странице приводят к трудноуловимым конфликтам.
Правки не видны из-за кеша. После изменения стилей при включённом объединении обязательно сбрасывайте кеш.

Итог

По умолчанию держите основные стили в template_styles.css, а скрипты — в script.js: они подключаются сами и участвуют в объединении. Дополнительные файлы подключайте через SetAdditionalCSS() и AddHeadScript(), а AddHeadString() оставьте для preload, метатегов и favicon.

Два правила, которые предотвращают большинство проблем: используйте абсолютные пути внутри CSS и помечайте сторонние скрипты атрибутом data-skip-moving="true", чтобы оптимизация не переносила их и не ломала.