Как добавить скрипт в 1С-Битрикс

Подключение JavaScript-скриптов в 1С-Битрикс (Управление сайтом) отличается от обычного HTML-сайта: у CMS есть собственные механизмы работы с ассетами, кешированием и композитным режимом. Если просто вставить <script src="..."> в шаблон, скрипт может не подключиться на страницах с композитом, попасть в объединённый бандл или конфликтовать с другими скриптами.

Выбор способа зависит от задачи: подключить глобальную библиотеку на весь сайт, добавить скрипт только на одну страницу, подключить код внутри компонента или внедрить внешний счётчик. Ниже разобраны все рабочие варианты — от простого редактирования шаблона до API-методов CJSCore и Asset.

Какие способы подключения скриптов существуют

В Битриксе есть четыре основных механизма: прямая вставка тега <script> в шаблон, методы класса Asset (ядро D7), старый API CJSCore и $APPLICATION->AddHeadScript(), а также подключение внутри шаблонов компонентов. Все они в итоге формируют теги в HTML, но по-разному участвуют в объединении и кешировании.

Ключевое различие — обработка ядром. Скрипты, добавленные через API, попадают в общий механизм объединения и минификации (если включён в настройках главного модуля), а вставленные напрямую тегом выводятся «как есть». Это влияет на скорость загрузки и на поведение при композитном режиме.

Сравнение способов

Asset::getInstance()->addJs()

Современный способ для шаблона и компонентов, участвует в объединении. Ограничение — требует ядро D7.

$APPLICATION->AddHeadScript()

Старый API, работает везде, но считается устаревшим. Подходит для легаси-кода.

Прямой тег <script> в шаблоне

Просто и предсказуемо, но скрипт не объединяется и не минифицируется ядром.

CJSCore::Init()

Подключение зарегистрированных модулей ядра (jquery, ajax и др.). Только для встроенных библиотек.

Подключение скрипта через шаблон сайта

Шаблон сайта находится в /bitrix/templates/название_шаблона/ (или в /local/templates/ на современных установках). Глобальные скрипты принято подключать в файле header.php, если они нужны в <head>, или в footer.php, если скрипт должен загружаться после контента.

Рекомендуемый вариант — метод Asset::getInstance()->addJs(). Пример подключения файла custom.js из папки шаблона:

<?php
use Bitrix\Main\Page\Asset;
Asset::getInstance()->addJs(SITE_TEMPLATE_PATH . "/js/custom.js");
?>

Константа SITE_TEMPLATE_PATH автоматически указывает на папку текущего шаблона, поэтому код не сломается при смене шаблона. Скрипт, добавленный таким образом, попадёт в объединённый файл, если в настройках главного модуля включены опции «Объединять JS-файлы» и «Минифицировать JS».

Если нужен простой вариант без API, вставьте тег напрямую в header.php перед </head> или в footer.php перед </body>: <script src="<?=SITE_TEMPLATE_PATH?>/js/custom.js"></script>. Этот способ предсказуем, но лишает скрипт оптимизации ядром.

1. 1
   Откройте header.php или footer.php нужного шаблона через «Настройки → Сайты → Шаблоны» или по FTP
2. 2
   Добавьте вызов Asset::getInstance()->addJs() с путём через SITE_TEMPLATE_PATH
3. 3
   Сохраните файл и сбросьте кеш: Настройки → Настройки продукта → Автокеширование
4. 4
   Откройте страницу сайта и проверьте наличие скрипта в исходном коде или во вкладке Network

Подключение скрипта на отдельной странице или в компоненте

Когда скрипт нужен только на конкретной странице, откройте её в визуальном редакторе или как PHP-файл и добавьте вызов Asset::getInstance()->addJs("/local/js/mypage.js"); после подключения пролога. Скрипт подключится только там, где выполняется этот код.

Для компонентов правильное место — файл template.php (или script.js в папке шаблона компонента). Битрикс автоматически подключает файлы script.js и style.css, лежащие рядом с шаблоном компонента, — это самый чистый способ добавить компоненту собственную логику без правки ядра.

Использование CJSCore для встроенных библиотек

Если нужна jQuery или другая библиотека из состава ядра, не подключайте её вручную — вызовите CJSCore::Init(array("jquery"));. Ядро само вставит правильную версию и избежит дублирования, которое часто ломает скрипты при двойном подключении jQuery.

Добавление внешних счётчиков и сторонних сервисов

Коды аналитики, виджетов обратного звонка и чатов обычно требуют размещения перед </body> или сразу после <body>. Вставляйте их в footer.php (или header.php для head-части) напрямую, без Asset — внешние URL всё равно не объединяются ядром.

Если на сайте включён композитный режим, динамические вставки могут кешироваться вместе со страницей. Для счётчиков это обычно не критично, но если виджет должен реагировать на авторизацию пользователя, оберните вывод в композитную область с динамической загрузкой или проверяйте поведение после включения композита.

Проверка результата и композитный режим

После подключения откройте страницу, нажмите Ctrl+U (просмотр исходного кода) и найдите путь к скрипту. Если включено объединение JS, ищите не исходное имя файла, а признак его содержимого в объединённом бандле — проще проверить через DevTools, вкладка Network, фильтр JS.

Дополнительно проверьте консоль браузера (F12): ошибки 404 означают неверный путь, ошибки «$ is not defined» — что скрипт выполняется раньше jQuery. При включённом композитном режиме обязательно проверяйте страницу в режиме инкогнито, так как администратору композит часто отключён.

Контрольные точки

Как проверить результат

Исходный код страницы

Норма

Тег script с нужным src присутствует или файл виден в объединённом бандле

Тревожный признак

Скрипта нет вовсе — не сброшен кеш или неверный шаблон

Консоль браузера

Норма

Нет ошибок 404 и JS-ошибок

Тревожный признак

404 на файл скрипта или конфликты библиотек

Режим инкогнито

Норма

Скрипт работает и для гостя

Тревожный признак

Работает только у администратора — виноват композит или кеш

Типичные ошибки и ограничения

Самая частая проблема — скрипт не появляется из-за кеша. Битрикс агрессивно кеширует и шаблон, и объединённые ассеты: после правки всегда сбрасывайте кеш в настройках автокеширования, а при композите — очищайте и его.

Вторая группа ошибок — неверные пути. Относительный путь вида src="js/custom.js" ломается на страницах с ЧПУ, потому что браузер считает путь от текущего URL. Всегда используйте абсолютный путь от корня сайта или SITE_TEMPLATE_PATH.

FAQ

Куда лучше подключать скрипт — в head или перед закрывающим body?

Скрипты, от которых зависит отрисовка страницы, подключают в head. Остальное лучше размещать перед или использовать Asset — ядро выведет их в конец страницы при соответствующей настройке, что ускоряет первую отрисовку.

Почему скрипт исчезает после обновления Битрикса?

Почти всегда причина в том, что правки вносились в файлы ядра (/bitrix/modules/, /bitrix/js/) или в системный шаблон. Перенесите код в собственный шаблон в /local/templates/ или в шаблон компонента — эти файлы обновления не затрагивают.

Как подключить скрипт только для авторизованных пользователей?

Оберните вызов в условие: if ($USER->IsAuthorized()) { Asset::getInstance()->addJs(...); }. Учтите, что при включённом композитном режиме страница кешируется для всех — для разного контента используйте динамические композитные области.

Можно ли подключить скрипт с внешнего CDN через Asset?

Да, addJs() принимает и внешние URL, например Asset::getInstance()->addJs("https://cdn.example.com/lib.js"). Такой файл не попадёт в объединённый бандл, но будет корректно выведен в нужном месте страницы.

Что делать, если скрипт конфликтует с другими на странице?

Проверьте порядок подключения и дубли библиотек в консоли браузера. Чаще всего помогает удаление ручного подключения jQuery и переход на CJSCore::Init(), а для изоляции своего кода — обёртка в самовызывающуюся функцию (IIFE).