Перейти к содержимому
BXWiki

Расширение JS не подключается - разбор причин

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

С чего начать

Смотрим, что вообще подключается на странице:

\Bitrix\Main\UI\Extension::load('vendor.widget');
// имя расширения обязано совпадать с деревом каталогов до последней точки
// в исходном коде страницы должен появиться файл расширения
// пустой результат означает, что расширение не найдено по имени
// в вызов можно передать массив имён сразу нескольких расширений

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

Сверяем имя с деревом каталогов:

Окно терминала
ls -la /home/bitrix/www/local/js/vendor/widget/config.php
# имя vendor.widget соответствует каталогу vendor/widget
# каждая точка в имени - это уровень вложенности каталогов

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

Читаем описание расширения:

/local/js/vendor/widget/config.php
return [
    'js' => 'dist/widget.bundle.js',
    'css' => 'dist/widget.bundle.css',
        'rel' => ['main.core', 'ui.buttons'],   // зависимости подключатся сами
    // при импорте из кода сборщик дописывает зависимость сюда сам
];

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

Проверяем свежесть собранного файла:

Окно терминала
ls -l --time-style=+%F\ %H:%M /home/bitrix/www/local/js/vendor/widget/dist/ \
  /home/bitrix/www/local/js/vendor/widget/src/
# собранный файл старше исходников означает забытую пересборку
# на время разработки сборку держат в режиме слежения

Дата собранного файла отвечает на вопрос быстрее любых догадок. Правки в исходниках без пересборки на страницу не попадают, и выглядит это как неработающий код.

Причины

  1. Имя расширения не совпадает с деревом каталогов примерно 30% случаев

    ПризнакВызов подключения выполняется, в исходном коде страницы файла нет.

    ПроверкаСверяем имя расширения с путём: каждая точка - это отдельный уровень каталогов.

    Что делатьПриводим имя и путь к соответствию: расширение ищется строго по этому правилу.

  2. Файл собран, но не пересобран после правок примерно 25% случаев

    ПризнакПравки в исходниках не видны, работает прежняя версия скрипта.

    ПроверкаСмотрим дату собранного файла и сравниваем с датой исходников.

    Что делатьЗапускаем сборку и держим её в режиме слежения во время разработки.

  3. Не указаны зависимости расширения примерно 20% случаев

    ПризнакФайл подключился, но в браузере ошибка о неизвестном объекте ядра.

    ПроверкаСмотрим список зависимостей в описании расширения.

    Что делатьДобавляем нужные расширения в список: они подключатся вместе с вашим.

  4. Файл потерялся при объединении статики примерно 15% случаев

    ПризнакНа части страниц скрипт есть, на части нет, в исходном коде один общий файл.

    ПроверкаОтключаем объединение файлов и проверяем страницу ещё раз.

    Что делатьДаём своим файлам отдельный путь и не кладём их в каталоги ядра.

  5. Страница отдаётся из кэша примерно 10% случаев

    ПризнакРасширение подключается на новой странице, но не появляется на прежней.

    ПроверкаСбрасываем кэш компонента, внутри которого идёт подключение.

    Что делатьСбрасываем кэш после правок: список подключений собирается вместе с кэшем компонента.

Частые вопросы

Куда класть свой код расширения?

В каталог решений проекта, а не в каталог ядра. Файлы ядра перезаписываются обновлением, и своё расширение там не переживёт ближайшего обновления.

Почему в браузере ошибка о неизвестном объекте?

Не указана зависимость от нужного расширения ядра. Зависимости перечисляют в описании, и они подключаются раньше вашего файла.

Нужно ли подключать расширение вручную из шаблона?

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

Что делать при включённом объединении файлов?

Проверять с выключенным объединением, а своим файлам давать отдельный путь. Собранный файл обновляется не сразу и путает при разборе.

Можно ли подключать расширение из скрипта?

Да, отложенная загрузка из кода браузера поддерживается. Это удобно для тяжёлых интерфейсов, которые нужны не каждому посетителю.

Смежное

Первоисточник