Управление DOM-структурой в 1С-Битрикс: создаём элементы с BX.create

В ядре JavaScript-библиотеки 1С-Битрикс у функции BX.create особая роль — это универсальный конструктор DOM-узлов, который за один вызов позволяет:

• задать тэг,
• назначить свойства (props) и атрибуты (attrs),
• навесить CSS-стили (style),
• описать dataset,
• подключить обработчики событий (events),
• вставить дочерние элементы, или текст/HTML-содержимое.

1. Сигнатура

/* Короткая форма */
DOMNode BX.create(tag [, data [, context]]);
/* Расширенная форма — вся конфигурация в одном объекте */
DOMNode BX.create(data [, context]);

• tag — строка с tagName узла, если он не указан, свойство tag обязательно должно присутствовать в объекте data.
• data — описательный объект (см. следующий раздел).
• context — DOM-контекст (например, iframe.contentDocument), внутри которого создаётся элемент. По умолчанию — document.

2. Объект data: поля и особенности

Важно: text, html и children взаимоисключают друг друга. Если указать более одного поля, отработает только первое найденное.

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

3.1. Текстовое поле только для чтения

const readonlyInput = BX.create('input', {
    attrs: { readonly: 'readonly', placeholder: 'Только для чтения' },
    props: { className: 'form-control' }
});

3.2. Кнопка с событием

function onComplete() {
    console.log('Клик по', BX.proxy_context); // BX.proxy_context → текущий элемент
}
const completeBtn = BX.create('span', {
    attrs: { title: 'Завершить задачу' },
    props: { className: 'task-view-button' },
    dataset: { taskId: 123 },
    text: 'Завершить',
    events: { click: BX.proxy(onComplete, this) }
});

4. Составная форма: построение целой формы «на лету»

const popupFields = BX.create({
    tag: 'div',
    props: { className: 'formFieldsContainer' },
    children: [
        BX.create({
            tag: 'div',
            props: { className: 'form-group' },
            children: [
                BX.create({
                    tag: 'label',
                    attrs: { for: 'reviewName' },
                    text: 'Ваше имя'
                }),
                BX.create({
                    tag: 'input',
                    attrs: {
                        id: 'reviewName',
                        type: 'text',
                        placeholder: 'Ваше имя',
                        name: 'reviewName'
                    },
                    props: { className: 'form-control' }
                })
            ]
        }),
        BX.create({
            tag: 'div',
            props: { className: 'form-group' },
            children: [
                BX.create({
                    tag: 'label',
                    attrs: { for: 'reviewSite' },
                    text: 'Адрес сайта'
                }),
                BX.create({
                    tag: 'input',
                    attrs: {
                        id: 'reviewSite',
                        name: 'reviewSite',
                        type: 'text',
                        placeholder: 'Адрес сайта'
                    },
                    props: { className: 'form-control' }
                })
            ]
        }),
        BX.create({
            tag: 'div',
            props: { className: 'form-group' },
            children: [
                BX.create({
                    tag: 'label',
                    attrs: { for: 'reviewText' },
                    text: 'Ваш отзыв'
                }),
                BX.create({
                    tag: 'textarea',
                    attrs: {
                        id: 'reviewText',
                        name: 'reviewText',
                        rows: 3
                    },
                    props: { className: 'form-control' }
                })
            ]
        })
    ]
});

Вставка в документ

BX.append(popupFields, BX('container')); // «container» — id существующего блока

5. Работа с context

Если нужно строить DOM-элементы внутри iframe — передаём второй/третий параметр:

const iframeDoc = BX('reportFrame').contentDocument;
const reportBtn  = BX.create('button', {
    text: 'Сформировать',
    props: { className: 'btn btn-success' }
}, iframeDoc);
BX.append(reportBtn, iframeDoc.body);

6. Расширенные приёмы

6.1. Умная фабрика для кнопок

function createBtn(text, type = 'primary', onClick = BX.DoNothing) {
    return BX.create('button', {
        props: { className: btn btn-${type} },
        text,
        events: { click: onClick }
    });
}
/* Использование */
const saveBtn   = createBtn('Сохранить', 'success', saveForm);
const cancelBtn = createBtn('Отмена',   'secondary', closeModal);

6.2. Генерация таблицы из данных

function renderTable(rows) {
    return BX.create('table', {
        props: { className: 'table table-striped' },
        children: rows.map(cells =>
            BX.create('tr', {
                children: cells.map(cell =>
                    BX.create('td', { text: cell })
                )
            })
        )
    });
}
const data = [
    ['ID', 'Имя', 'Статус'],
    [1, 'Alice', 'Активен'],
    [2, 'Bob',   'Выключен']
];
BX.append(renderTable(data), BX('grid'));

7. Частые ошибки и подсказки

8. Итог

BX.create берёт на себя от генерации тега до привязки событий — и избавляет разработчика от монотонного document.createElement, setAttribute, appendChild и т.д. Освоив базовые приёмы и шаблоны, можно собирать целые интерфейсы «на лету», сохраняя читаемость кода и контролируя каждую нить DOM-структуры.