BX.ready — обработка событий после готовности DOM в 1С-Битрикс

BX.ready — это «универсальный DOMContentLoaded» из библиотеки Bitrix Framework.
Функция гарантирует, что ваш JavaScript-код запустится только тогда, когда DOM-дерево уже построено и элементы доступны для чтения/записи. Это особенно важно для компонентов и шаблонов, которые добавляются динамически или грузятся по AJAX.

2. Синтаксис

BX.ready(function () {
    // код, которому нужен доступ к DOM
});

Типовая сигнатура из документации

void BX.ready(Function handler);

Короткая форма

BX(function () {
    // то же самое, но короче
});

3. Сравнение с window.onload

4. Базовый пример

<?php
require $_SERVER['DOCUMENT_ROOT'].'/bitrix/header.php';
$APPLICATION->SetTitle('BX.ready — базовый пример');
/**
 * Загружаем необходимые UI-бандлы.
 * ui.buttons  — стили и JS для .ui-btn
 * ui.dialogs.messagebox — класс BX.UI.Dialogs.MessageBox
 */
\Bitrix\Main\UI\Extension::load([
    'ui.buttons',
    'ui.dialogs.messagebox',
]);
?>
<button id="helloBtn" class="ui-btn ui-btn-lg ui-btn-primary">
    Нажми меня
</button>
<script>
BX.ready(function () {
    BX('helloBtn').addEventListener('click', function () {
        BX.UI.Dialogs.MessageBox.alert('Привет, мир!');
    });
});
</script>
<?php require $_SERVER['DOCUMENT_ROOT'].'/bitrix/footer.php'; ?>

5. Делегирование событий

BX.bindDelegate — удобное средство для делегирования. Его часто комбинируют с BX.ready, чтобы обрабатывать клики по динамически появляющимся элементам.

<?php
require $_SERVER['DOCUMENT_ROOT'].'/bitrix/header.php';
$APPLICATION->SetTitle('BX.bindDelegate + BX.ready');
\Bitrix\Main\UI\Extension::load([
    'ui.buttons',            // если нужна стилизация ссылок/кнопок
    'ui.dialogs.messagebox', // для модального окна
]);
?>
<a href="#" class="css_bind ui-btn ui-btn-primary" data-param="HELLO">Click Me #1</a>
<div class="css_bind ui-btn ui-btn-secondary" data-param="HELLO2">Click Me #2</div>
<script>
BX.ready(function () {
    const suffix = ' — Hello from delegate';
    BX.bindDelegate(
        document.body,
        'click',
        { className: 'css_bind' },          // фильтр по классу
        function (event) {
            const text = this.getAttribute('data-param') + suffix;
            BX.UI.Dialogs.MessageBox.alert(text);
            return BX.PreventDefault(event);
        }
    );
});
</script>
<?php require $_SERVER['DOCUMENT_ROOT'].'/bitrix/footer.php'; ?>

6. Несколько обработчиков BX.ready

Вы можете вызывать BX.ready столько раз, сколько нужно — все колбэки будут выполнены в порядке объявления.

BX(function () {
    console.log('Первый обработчик');
});
BX.ready(function () {
    console.log('Второй обработчик');
});

7. Использование современного синтаксиса (ES6+)

BX.ready(() => {
    const items = document.querySelectorAll('[data-toggle]');
    items.forEach(el => el.classList.toggle('active'));
});

Стрелочные функции сокращают код и сохраняют лексическое значение this.

8. Подгрузка компонентов по AJAX и повторная инициализация

Компоненты, загружаемые посредством BX.ajax.loadJSON или BX.ajax.insertToNode, не перезапустят обработчики из первого BX.ready. Для «ре-инициализации» используйте пользовательские события.

Шаг 1. Генерируем событие после подгрузки

BX.ajax.insertToNode('/ajax/component.php', 'targetDiv', null, () => {
    BX.onCustomEvent('MyComponentLoaded');
});

Шаг 2. Подписываемся в BX.ready

BX.ready(() => {
    BX.addCustomEvent('MyComponentLoaded', () => {
        initMyComponent();     // функция, которая вешает нужные клики/скрипты
    });
    // для первой загрузки страницы
    initMyComponent();
});

9. Типичные ошибки

10. Лучшие практики

1. Загружайте JS-ядро через \Bitrix\Main\UI\Extension::load() — оно само подтянет main.core.
2. Минимизируйте глобальные переменные — передавайте данные в data-* атрибутах или через JSON-инициализацию.
3. Используйте UI-компоненты (BX.UI.*) вместо alert/confirm.
4. Интегрируйте Webpack/Babel — Bitrix отлично работает с бандлами, главное подключать их после bitrix.js.
5. Профилируйте. Большие порталы с обилием делегирования могут испытывать задержки; используйте инструменты разработчика и BX.debug.

11. Заключение

BX.ready — заменяет стандартный DOMContentLoaded, учитывая особенности платформы, старых браузеров и AJAX-подгрузок. Грамотно комбинируя BX.ready, делегирование и пользовательские события, вы получите предсказуемое поведение интерфейса и упростите поддержку кода.
Берите приведённые примеры за основу, адаптируйте под свои задачи — и ваш фронтенд будет загружаться быстро, без гонок и лишних ошибок.