Управление DOM-структурой в Битрикс: BX.addClass и BX.removeClass

Встроенная JS-библиотека ядра 1С-Битрикс содержит удобные «джейквери-подобные» методы для работы с CSS-классами. BX.addClass и BX.removeClass позволяют безопасно добавлять или удалять класс у одного или группы узлов, возвращая сам узел для дальнейших операций. Это основной строительный блок практически любого динамического интерфейса на Bitrix-сайтах.

1. Сигнатуры и поведение функций

/**
 * Добавляет класc, если его ещё нет.
 * @param {DOMNode} node – целевой узел
 * @param {String} className – имя класса или несколько через пробел
 * @returns {DOMNode}
 */
BX.addClass(node, className);

/**
 * Удаляет класс, если он есть
 * (Bitrix-ядро умеет принимать строку из нескольких классов).
 * @param {DOMNode} node
 * @param {String} className
 * @returns {DOMNode}
 */
BX.removeClass(node, className);

Функции входят в раздел «Управление DOM-структурой» ядра JS-библиотеки Bitrix и официально возвращают тот же узел, что удобно для «мягкого» чейнинга с другими методами (например, BX.adjust).

2. Минимальное подключение ядра

На большинстве шаблонов kernel_main.js и kernel_main.css уже подключены системой.
Если создаёте «голый» шаблон, не забудьте:

<?php
\Bitrix\Main\Page\Asset::getInstance()
  ->addJs('/bitrix/js/main/core/core.js');
?>

После этого в скриптах доступен глобальный объект BX.

3. Базовое использование

<div id="feedback" class="message"></div>
<script>
BX.ready(function () {
    const box = BX('feedback');
    BX.addClass(box, 'message--success');
});
</script>

Что происходит? При готовности DOM мы находим узел по id и добавляем модификатор.
Безопасность: метод не дублирует класс, если тот уже присутствует.

4. Удаление и переключение класса

<button id="toggle">Вкл/Выкл</button>
<div id="panel" class="panel"></div>
<script>
BX.ready(function () {
    const btn = BX('toggle');
    const panel = BX('panel');
    BX.bind(btn, 'click', () => {
        // класс active будем то добавлять, то удалять
        if (BX.hasClass(panel, 'active')) { // проверим текущее состояние
            BX.removeClass(panel, 'active');
        } else {
            BX.addClass(panel, 'active');
        }
    });
});
</script>

Метод BX.hasClass возвращает boolean и помогает избежать лишних операций.

5. Работа с несколькими узлами

<ul id="catalog">
  <li>Товар 1</li>
  <li>Товар 2</li>
  <li>Товар 3</li>
</ul>
<script>
BX.ready(function () {
    BX.findChildren( // найдём все <li>
        BX('catalog'),
        { tag: 'li' },
        true
    ).forEach(item => BX.addClass(item, 'catalog__item'));
});
</script>

BX.findChildren рекурсивно собирает потомков, после чего мы проходимся по коллекции и добавляем единый BEM-класс.

6. Добавление нескольких классов одной строкой

BX.addClass(node, 'btn btn--primary btn--lg'); // три класса за один вызов
BX.removeClass(node, 'btn--lg btn--wide'); // удаляем сразу два

Внутри функции строка разбивается на массив по пробелу – это быстрее, чем множество отдельных вызовов.

7. Использование в компонентах и Ajax-действиях

7.1 Обновляем иконку корзины после Ajax-добавления товара

<?php
// шаблон компонента catalog.element (фрагмент)
?>
<button id="buy" class="btn js-buy">Купить</button>
<span id="basketIndicator" class="basket-icon"></span>
<script>
BX.ready(function () {
    const indicator = BX('basketIndicator');
    BX.bind(BX('buy'), 'click', function () {
        BX.ajax.runComponentAction(
            'bitrix:catalog.element',
            'addToBasket',
            { mode: 'class', data: { id: <?=$arResult['ID']?> } }
        ).then(() => {
            BX.addClass(indicator, 'basket-icon--filled');
        });
    });
});
</script>

7.2 «Плавающая» ошибка формы с тайм-аутом

function showFormError(node, text, ms = 4000) {
    node.textContent = text;
    BX.addClass(node, 'alert');
    setTimeout(() => BX.removeClass(node, 'alert'), ms);
}

8. Полезные советы и best practices

9. Частые ошибки

1. Передаёте null вместо узла. Всегда проверяйте BX(node) вернул ли элемент.
2. Добавляете класс в цикле без проверки. При большом списке используйте BX.hasClass или classList.contains для старого кода.
3. Удаляете не тот класс. При групповой передаче строкой удостоверьтесь, что пробелы стоят корректно.

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

BX.addClass и BX.removeClass – инструменты разработки на 1С-Битрикс. Они инкапсулируют кросс-браузерные мелочи и позволяют писать лаконичный код без внешних библиотек. Практикуйте приёмы из примеров выше, придерживайтесь аккуратной схемы именования классов, и ваши интерфейсы будут работать быстро, а код останется читаемым.

Успехов в разработке и чистого DOM!