Подключение JS-расширений (extension)

Механизм расширений (extension) — современный способ подключать JS и CSS в Битрикс с автоматическим разрешением зависимостей. Вместо десятка ручных addJs вы объявляете одно имя, а платформа сама подтянет всё нужное в правильном порядке.

Зачем нужны расширения

Исторически скрипты подключали вручную через класс Asset или устаревший CJSCore::Init(). Проблема ручного подхода — зависимости: если ваш модуль требует core, popup и ajax, вы обязаны помнить порядок и не забыть ни одну библиотеку.

Расширение (extension) решает это декларативно: рядом с файлами лежит config.php, где перечислены JS, CSS и зависимости. При подключении расширения Битрикс строит граф зависимостей и подключает всё в нужной последовательности, без дублей.

Как подключить расширение

Из любого места (шаблон компонента, страница, класс) расширение подключается одной строкой:

<?php
use Bitrix\Main\UI\Extension;
Extension::load('ui.buttons');
Extension::load(['ui.alerts', 'ui.notification']);

Метод Extension::load() принимает как строку, так и массив имён. Все зависимости из config.php подтянутся автоматически. В сборках через BX.Runtime используется асинхронный вариант:

BX.Runtime.loadExtension('ui.buttons').then(function(exports) {
  // exports — экспортируемые сущности расширения
});

В шаблоне компонента вызов Extension::load() лучше делать вне кэша — например, в component_epilog.php, чтобы подключение отработало даже при отдаче страницы из кэша.

Файл config.php своего расширения

Своё расширение — это папка внутри модуля: /local/js/my.module/catalog.viewer/ с файлом config.php. Имя расширения выводится из пути: my.module.catalog.viewer. Пример конфигурации:

<?php
return [
  'js' => './script.js',
  'css' => './style.css',
  'rel' => ['main.core', 'ui.buttons', 'main.popup'],
  'lang' => './lang',
];

Ключи файла:

После создания файлов расширение доступно по имени: Extension::load('my.module.catalog.viewer').

Зависимости rel и порядок загрузки

Ключ rel — сердце механизма. В нём перечислены другие расширения, которые должны быть подключены до вашего. Битрикс рекурсивно обходит их, поэтому достаточно указать прямые зависимости — транзитивные подтянутся сами.

• main.core — базовое ядро BX (нужно почти всегда);
• main.core.events — события BX.Event;
• main.popup — всплывающие окна;
• ui.buttons, ui.forms — компоненты интерфейса.

Extension, Asset и CJSCore — что когда

Три способа подключения решают разные задачи. Ориентир:

Класс Asset по-прежнему полезен для точечного подключения одного файла:

\Bitrix\Main\Page\Asset::getInstance()->addJs('/local/js/widget.js');
\Bitrix\Main\Page\Asset::getInstance()->addCss('/local/css/widget.css');

Но как только появляется хотя бы одна зависимость от ядра — переходите на extension, иначе будете вручную следить за порядком подключения.

Отладка и типичные проблемы

Если расширение не подключается, проверьте по списку:

1. Имя. Оно строится из пути папки: точки вместо слэшей. Опечатка в имени — расширение молча не загрузится.
2. Кэш. После правки config.php сбросьте кэш компонентов и файлов в админке — карта расширений кэшируется.
3. Оптимизация JS/CSS. При включённой оптимизации файлы склеиваются; при отладке её удобно временно выключить в настройках модуля main.
4. Пути в config.php. Относительные пути (./) считаются от папки расширения, а не от корня сайта.

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

Итог

Extension — предпочтительный способ подключать фронтенд в современном Битрикс: одно имя в Extension::load(), а зависимости описаны в config.php через ключ rel. Для одиночных файлов остаётся Asset, для наследия — CJSCore. Свои расширения кладут в /local/js/ и подключают вне кэша.

Когда фронтенд проекта разрастается до собственной библиотеки компонентов и сложной сборки, мы в B2Bsite помогаем выстроить структуру расширений и наладить деплой — чтобы новые релизы выкатывались быстро и без ручного сведения зависимостей.