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

Своё расширение JS - каталог, зависимости, подключение

Собираем свой JavaScript в расширение: один каталог, объявленные зависимости и подключение одной строкой вместо россыпи файлов в шаблоне.

Решение

Заводим каталог расширения:

/local/js/vendor/cart/
    config.php    - описание: файлы и зависимости
    script.js     - сам код
    style.css     - стили расширения
    lang/ru/      - языковые сообщения, доступные коду расширения
// имя расширения собирается из пути: каталог vendor и каталог cart дают vendor.cart

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

Описываем файлы и зависимости:

config.php
return [
    'js'  => 'script.js',
    'css' => 'style.css',
    'rel' => ['main.core', 'ui.buttons'],   // что подключить до нас
];
// путь к файлам указывают относительно каталога самого расширения

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

Подключаем расширение из кода:

use Bitrix\Main\UI\Extension;


Extension::load('vendor.cart');                  // одно расширение
Extension::load(['vendor.cart', 'ui.alerts']);   // или сразу несколько
// зависимости из rel подключаются сами, перечислять их повторно не нужно
// повторный вызов ничего не сломает: платформа подключит файлы один раз

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

Собираем современный синтаксис:

// bundle.config.js рядом с исходниками
module.exports = {
    input: './src/cart.js',
    output: './dist/cart.bundle.js',
    namespace: 'BX.Vendor',
};
// сборка запускается штатной командой платформы и кладёт результат в dist
// собранный файл и указывают в описании расширения

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

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

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

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

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

Типичные проблемы

Расширение не подключается на странице.

Имя не совпадает с путём к каталогу расширения на диске. Платформа ищет описание расширения строго по этому пути и нигде больше его не смотрит.

Код падает с ошибкой про неизвестный объект.

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

Браузер ругается на синтаксис файла.

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

Стили расширения не приехали.

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

После обновления продукта расширение пропало.

Каталог расширения лежал внутри каталога ядра, а его обновление продукта перезаписывает целиком. Свои расширения держат рядом с сайтом или в своём модуле.

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

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

Да, тем же вызовом до вывода разметки. Компонент при этом остаётся самостоятельным.

Как узнать имя штатного расширения?

По пути к его каталогу в каталоге скриптов ядра. Имя повторяет путь через точку.

Нужно ли расширение для одной функции?

Обычно нет: короткий код живёт в шаблоне. Расширение окупается зависимостями и повторным использованием.

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

Тем же путём, что и остальной код проекта. Платформа сама пометит новую версию файла.

Смежное

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