Управление DOM-структурой в 1С-Битрикс: разбор BX.adjust

Метод BX.adjust() относится к ядру JavaScript-библиотеки Bitrix и предназначен для быстрого и безопасного изменения существующих DOM-узлов. По сути это «швейцарский нож» для манипуляций с атрибутами, стилями, событиями и содержимым, который избавляет от рутинного element.style, addEventListener, setAttribute и прочих низкоуровневых вызовов.

Сигнатура

DOMNode BX.adjust(
    DOMNode node,
    object  data
);

• Возвращает: ссылку на тот же узел node (что удобно для чейнинга).

Описание параметров data

Важно: text, html, children — взаимоисключающие поля. Укажите только одно из них, иначе Bitrix проигнорирует остальные.

Быстрые действия: включаем и выключаем элементы

// Заблокировать кнопку
BX.adjust(BX('submitBtn'), {
    props: { disabled: true }
});
// Разблокировать кнопку
BX.adjust(BX('submitBtn'), {
    props: { disabled: false }
});

Пример 1: Массовое изменение стиля и атрибутов

Исходный HTML:

<div id="obj"
     class="bigtitle"
     data-src="/fff/fff/"
     style="height: 100px; width: 200px; border: 1px solid #ccc; background: #ff0; color: #f00;">
    Объект
</div>

JavaScript (обратите внимание: width, а не weight):

var obj = BX('obj');
BX.adjust(obj, {
    style: {
        height:  '200px',
        width:   '100px',
        background: '#f00',
        color:      '#ff0'
    },
    attrs: {
        'data-src': '/ccc/ccc',
        id:    'obj2',
        class: 'smalltitle'
    },
    text: 'Объект с изменёнными данными'
});

Результат:

<div id="obj2"
     class="smalltitle"
     data-src="/ccc/ccc"
     style="height: 200px; width: 100px; border: 1px solid #ccc; background: #f00; color: #ff0;">
    Объект с изменёнными данными
</div>

Пример 2: Добавляем обработчики событий на лету

BX.adjust(BX('alertBtn'), {
    events: {
        click: function () {
            alert('Кнопка нажата!');
        },
        mouseenter: function (e) {
            e.target.style.opacity = 0.8;
        },
        mouseleave: function (e) {
            e.target.style.opacity = 1;
        }
    },
    props: {
        title: 'Наведите и кликните'
    }
});

Пример 3: Вставка HTML вместо текста

BX.adjust(BX('newsItem'), {
    html: '<strong>Новость:</strong> <em>BX.adjust рулит!</em>'
});

Пример 4: Динамическое добавление дочерних элементов

var list = BX('todo');
BX.adjust(list, {
    children: [
        BX.create('li', {text: 'Сделать задачу 1'}),
        BX.create('li', {text: 'Сделать задачу 2'}),
        BX.create('li', {text: '???'}),
        BX.create('li', {text: 'Профит!'})
    ]
});

children полностью заменит старое содержимое списка.

Пример 5: Комбинируем BX.create + BX.adjust для мини-компонента

var card = BX.create('div', {
    props: { className: 'card' },
    style: { padding: '16px', border: '1px solid #eee' },
    children: [
        BX.create('h3', {text: 'Заголовок'}),
        BX.create('p', {text: 'Описание карточки'}),
        BX.create('button', {text: 'Подробнее', props: {type: 'button', id: 'moreBtn'}})
    ]
});
BX.adjust(card, {
    events: {
        click: function (e) {
            if (e.target.id === 'moreBtn') {
                alert('Здесь могла быть ваша реклама');
            }
        }
    }
});
document.body.appendChild(card);

Советы по производительности

1. Избегайте каскадов BX.adjust: если нужно переработать большой блок, постройте новый через BX.create и замените целиком.
2. Группируйте стили в одном вызове — это снижает число перерисовок.
3. Не забывайте снимать ненужные обработчики (через BX.removeCustomEvent или ручной removeEventListener), если элемент удаляется.

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

Заключение

BX.adjust() — инструмент для атомарного редактирования DOM в 1С-Битрикс. Он делает код чище, короче и безопаснее, с учётом особенностей всех браузеров, которые поддерживает платформа. Освоив этот метод, вы сможете:

• Мгновенно переключать состояния элементов (disabled, hidden и т. д.);
• Динамически подстраивать стили без лишних инфаркто-reflow;
• Единообразно назначать/снимать события;
• Работать с data-* без ручного конкатенирования строк.

Применяйте BX.adjust везде, где раньше писали десятки строк ванильного JavaScript — и пусть ваш фронтенд на Битриксе станет чище и быстрее!