При разработке или кастомизации сайта на 1С-Битрикс часто возникает необходимость подключить собственные стили (CSS) и скрипты (JavaScript). Это может быть как частью нового дизайна, так и интеграцией сторонних библиотек (например, jQuery, Swiper, или аналитических скриптов). В этой статье мы подробно рассмотрим правильные и эффективные способы подключения CSS и JS файлов к шаблону сайта в 1С-Битрикс, с учётом рекомендаций фреймворка.
📁 .css и .js — где их хранить?
Прежде чем подключать файлы, важно понимать, где их разместить:
Для шаблона сайта:
Все ресурсы обычно кладутся в папку шаблона:
/local/templates/ваш_шаблон/assets/css/
/local/templates/ваш_шаблон/assets/js/Для компонентов:
Если файлы относятся только к конкретному компоненту, их можно поместить внутрь папки компонента:
/local/components/ваш_компонент/templates/.default/
💡 Рекомендация: Используйте структуру с папками assets/css, assets/js внутри шаблона — это упрощает поддержку проекта.
🛠 Способ 1: Подключение через $APPLICATION->SetAdditionalCSS() и $APPLICATION->AddHeadScript()
Это классический способ, который работает на всех версиях Битрикс.
Пример подключения CSS:
<?php
$APPLICATION->SetAdditionalCSS(SITE_TEMPLATE_PATH . "/assets/css/custom.css");
?>Пример подключения JS:
<?php
$APPLICATION->AddHeadScript(SITE_TEMPLATE_PATH . "/assets/js/custom.js");
?>
⚠️ Важно: Эти методы добавляют файлы в <head> страницы. Для больших скриптов лучше использовать отложенную загрузку (см. ниже).
🚀 Способ 2: Использование Asset API (начиная с версии Битрикс 20.0.0)
Начиная с обновления D7-фреймворка, в Битрикс появился современный механизм управления ресурсами — Asset API. Он позволяет не только подключать файлы, но и управлять зависимостями, версиями и порядком загрузки.
Подключение CSS через Asset:
<?php
use Bitrix\Main\Page\Asset;
Asset::getInstance()->addCss(SITE_TEMPLATE_PATH . "/assets/css/style.css");
?>Подключение JS:
<?php
use Bitrix\Main\Page\Asset;
Asset::getInstance()->addJs(SITE_TEMPLATE_PATH . "/assets/js/script.js");
?>✅ Преимущества Asset API:
-
Автоматическое объединение и минификация (при включённой оптимизации)
-
Управление зависимостями
-
Возможность указать позицию (
BEFORE_CSS,AFTER_JS, и т.д.)
Пример с позиционированием:
<?php
use Bitrix\Main\Page\Asset;
Asset::getInstance()->addString(
'<script src="' . SITE_TEMPLATE_PATH . '/assets/js/lazy.js" defer></script>',
false,
AssetLocation::BEFORE_JS
);
?>⚠️ Способ 3: Подключение в header.php напрямую (не рекомендуется)
Можно просто вставить <link> и <script> в header.php шаблона:
<link rel="stylesheet" href="<?= SITE_TEMPLATE_PATH ?>/assets/css/style.css">
<script src="<?= SITE_TEMPLATE_PATH ?>/assets/js/script.js"></script>❌ Почему это не лучший подход?
-
Нарушается архитектура Битрикс
-
Нет контроля над дублированием (если файл подключится дважды — будут ошибки)
-
Не участвует в механизмах оптимизации (объединение, сжатие)
🛑 Используйте этот способ только для быстрого тестирования.
🎯 Как избежать дублирования подключений?
Если вы подключаете один и тот же файл из нескольких компонентов или областей сайта, используйте проверку:
<?php
if (!defined('MY_CUSTOM_SCRIPT_LOADED')) {
define('MY_CUSTOM_SCRIPT_LOADED', true);
$APPLICATION->AddHeadScript(SITE_TEMPLATE_PATH . "/assets/js/custom.js");
}
?>Или воспользуйтесь встроенными возможностями Asset API — он автоматически исключает дубли при одинаковых путях.
💡 Дополнительные советы
Версионирование файлов
Чтобы избежать проблем с кэшированием, добавляйте параметр версии:
<?php
Asset::getInstance()->addCss(SITE_TEMPLATE_PATH . "/assets/css/style.css?v=1.0.2");
?>Условное подключение
Подключайте ресурсы только на нужных страницах:
<?php
if ($APPLICATION->GetCurPage() == '/catalog/') {
Asset::getInstance()->addCss(SITE_TEMPLATE_PATH . "/assets/css/catalog.css");
}
?>Используйте HTTPS-пути
Убедитесь, что SITE_TEMPLATE_PATH возвращает корректный протокол (особенно если сайт работает по HTTPS).
📊 Сравнение методов
| Метод | Версии Битрикс | Оптимизация | Рекомендация |
|---|---|---|---|
$APPLICATION->SetAdditionalCSS()
|
Все | Нет | Для legacy-проектов |
$APPLICATION->AddHeadScript()
|
Все | Нет | Для legacy-проектов |
| Asset API | 20.0.0+ | Да | Рекомендуемый подход |
| Прямое подключение | Все | Нет | Только для тестирования |
🎨 Практический пример правильного подключения
<?php
// В начале файла шаблона (например, в header.php)
use Bitrix\Main\Page\Asset;
// Подключаем основные стили
Asset::getInstance()->addCss(SITE_TEMPLATE_PATH . "/assets/css/main.css?v=1.2.0");
// Подключаем библиотеки с зависимостями
Asset::getInstance()->addJs("https://code.jquery.com/jquery-3.6.0.min.js");
// Подключаем кастомные скрипты с отложенной загрузкой
Asset::getInstance()->addString(
'<script src="' . SITE_TEMPLATE_PATH . '/assets/js/app.js" defer></script>',
false,
\Bitrix\Main\Page\AssetLocation::BEFORE_JS
);
// Условное подключение для конкретной страницы
if (strpos($APPLICATION->GetCurPage(), '/blog/') !== false) {
Asset::getInstance()->addCss(SITE_TEMPLATE_PATH . "/assets/css/blog.css");
}
?>📝 Заключение
Правильное подключение CSS и JavaScript в 1С-Битрикс — это не просто вставка ссылок, а использование встроенных механизмов платформы. Asset API — современный и гибкий инструмент, который обеспечивает:
-
✅ Чистоту кода
-
✅ Производительность
-
✅ Совместимость
Избегайте «ручного» подключения в HTML, если только вы не делаете временный прототип.
Следуя этим рекомендациям, вы создадите поддерживаемый, быстрый и стабильный сайт на 1С-Битрикс.
