Правильное подключение стилей и скриптов в 1С Битрикс

Кратко: Если вы подключаете CSS и JS через обычные <link> и <script>, вы вручную лишаете себя главного преимущества Битрикс — автоматического объединения, сжатия и кеширования ресурсов. Правильный способ — использовать API системы: Asset::getInstance() для глобальных файлов и $this->addExternalCss/JS() для компонентов.

Почему «по-старинке» — плохо

Многие интеграторы, получая готовую вёрстку, переносят её в Битрикс «как есть»:

<link href="/file.css" rel="stylesheet">
<script src="/file.js"></script>

Это работает, но ставит крест на оптимизации. Битрикс в этом случае просто не видит ваши файлы и не может их объединить или сжать.

Реальный кейс: Один интернет-магазин на 500+ страниц каталога после миграции на правильное подключение через Asset сократил количество запросов CSS/JS с 47 до 3. Время загрузки главной упало с 4,2 до 1,8 секунды — только за счёт объединения и сжатия.

До D7: старый добрый API

До выхода ядра D7 (а в старых проектах — до сих пор) использовались методы объекта $APPLICATION:

// Подключение скриптов
$APPLICATION->AddHeadScript(SITE_TEMPLATE_PATH . "/js/file.js");

// Подключение CSS
$APPLICATION->SetAdditionalCSS(SITE_TEMPLATE_PATH . "/css/file.css", true);

// Подключение мета-тегов или сторонних файлов
$APPLICATION->AddHeadString("<meta name='yandex-verification' content='62be9ea1' />");

Важный нюанс: эти методы работают только если в header.php есть вызов $APPLICATION->ShowHead(). Без него файлы просто не появятся в HTML . Это одна из самых частых ошибок новичков.

Современный способ: Asset (D7)

С версии D7 правильный путь — класс Bitrix\Main\Page\Asset

use Bitrix\Main\Page\Asset;

// Подключение CSS
Asset::getInstance()->addCss("/bitrix/css/main/bootstrap.min.css");

// Подключение JS
Asset::getInstance()->addJs(SITE_TEMPLATE_PATH . "/js/myscripts.js");

// Мета-теги, favicon, шрифты
Asset::getInstance()->addString("<link rel='shortcut icon' href='/local/images/favicon.ico' />");

Asset — это Singleton, поэтому Asset::getInstance() всегда возвращает один и тот же объект. Порядок подключения сохраняется: файлы выстраиваются в том порядке, в котором вы их добавили.

Обратная совместимость: старый и новый методы работают параллельно. Можно использовать оба — принципиальной разницы нет.

Главный бонус: объединение и сжатие

Весь смысл правильного подключения раскрывается в настройках Главного модуля:

Настройки → Настройки модулей → Главный модуль → Оптимизация CSS

Включаем:

• Объединять CSS файлы

• Объединять JS файлы

• Создавать сжатую копию объединённых CSS и JS файлов

Что происходит на практике: В идеале на странице подключается 3 CSS и 3 JS файла:

Тип	Что содержит
kernel/styles.css	CSS ядра (Bootstrap, UI-библиотеки) — уникален для шаблона, накапливается по мере открытия страниц
template_xxx/styles.css	CSS шаблона (header + footer)
page_xxx/styles.css	CSS рабочей области (конкретной страницы)

Живой пример: Каталог с фильтрами подключает CSS для слайдера цен, а страница статьи — CSS для галереи. Благодаря разделению на «kernel / template / page», пользователь скачивает только то, что нужно на текущей странице. После «прогрева» кеша — один раз для всего сайта.

Подключение внутри компонентов

Если слайдер на базе списка новостей тянет за собой 200 KB CSS и 150 KB JS, подключать его глобально ко всему сайту — преступление против производительности.

С версии 15.5.1 у шаблонов компонентов есть «волшебные» методы:

// В файле template.php компонента
$this->addExternalCss("/local/slider.css");
$this->addExternalJS("/local/libs.js");

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

Кейс с форумов: Разработчик жаловался, что AddHeadScript в шаблоне компонента не работает — скрипт не появляется в HTML. Ответ оказался прост: в header.php не было ShowHead(). После добавления — всё заработало. С addExternalCss/JS такой проблемы нет, они не зависят от ShowHead().

Встроенные библиотеки: Bootstrap, шрифты, Vue

В ядре Битрикс уже лежат готовые расширения. Не нужно тащить их с CDN или из папки шаблона:

\Bitrix\Main\UI\Extension::load([
    'ui.fonts.opensans',
    'ui.bootstrap4'
]);

Подводный камень с Bootstrap 4: В Битриксе Bootstrap 4 подключается как ui.bootstrap4, но это версия 5.0-alpha (на 2020 год) . При этом стандартные компоненты Битрикс используют Bootstrap 3. Если на странице окажутся оба — верстка поедет .

Ещё один кейс из сообщества: После подключения ui.bootstrap4 выпадающее меню перестало работать. В консоли: Bootstrap dropdown require Popper.js. Решение — проверить, подключён ли Popper, и не конфликтует ли BS4 с BS3, который тянут стандартные компоненты .

Чек-лист правильного подключения

1. Глобальные файлы шаблона — через Asset::getInstance()->addCss/addJs в header.php

2. Файлы компонентов — через $this->addExternalCss/JS в template.php

3. Встроенные библиотеки — через Extension::load()

4. Проверить наличие $APPLICATION->ShowHead() в header.php (для старого API)

5. Включить объединение и сжатие в настройках Главного модуля

6. Не подключать Bootstrap 4 вместе с Bootstrap 3 без необходимости

Итог: Правильное подключение через API Битрикс — это не просто «так принято». Это единственный способ заставить CMS работать за вас: объединять, сжимать, кешировать и отдавать пользователю ровно тот набор ресурсов, который нужен на конкретной странице.