UI-библиотека 1С-Битрикс - кнопки, попапы, слайдер, диалоги

В платформе есть большой набор готовых интерфейсных элементов в актуальном оформлении: кнопки, всплывающие окна, меню, боковой слайдер, диалоги. Их не нужно верстать заново - достаточно подключить расширение и создать объект в JavaScript.

Как это работает

Общий принцип один для всех виджетов. PHP только загружает расширение, а объект создаёт JavaScript. У части компонентов есть три реализации: JS-класс, Vue-компонент и PHP-класс - выбирают по тому, где формируется интерфейс.

Что брать для новых интерфейсов. Модальное окно - системный диалог. Меню - системное меню. Простое подтверждение - окно сообщения. Базовый механизм попапов остаётся для сценариев с точным позиционированием и для совместимости со старым кодом.

Кнопки. Расширение кнопок даёт классы обычной и составной кнопки, набор готовых кнопок с локализованным текстом (сохранить, отменить и другие) и Vue-компонент. Кнопки можно передавать в системный диалог, окно сообщения и попап. Оформление задаётся либо классическими цветом и размером, либо новым дизайном при включении соответствующего флага.

Попапы и меню. Окно позиционируется относительно элемента или контейнера, у попапов и меню есть свои менеджеры. Глобальные объекты старого ядра остались как устаревшие псевдонимы.

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

Системные компоненты и новый дизайн. Актуальный набор в едином оформлении: диалог, меню, алерт, чип, поле ввода, метка, типографика, скелетон. У каждого есть JS-класс и Vue-компонент. Важная особенность: многие из них не выполняют действие сами - по клику вызывается только обработчик, а закрытие или удаление вы делаете кодом.

Примеры

1. Кнопка

\Bitrix\Main\UI\Extension::load('ui.buttons');

import { Button, ButtonColor, ButtonSize } from 'ui.buttons';

const button = new Button({
    text: 'Сохранить',
    color: ButtonColor.SUCCESS,
    size: ButtonSize.MEDIUM,
    onclick: () => save(),
});

button.renderTo(document.getElementById('toolbar'));

2. Окно сообщения

import { MessageBox, MessageBoxButtons } from 'ui.dialogs.messagebox';

// быстрый вариант
MessageBox.confirm('Удалить запись?', (messageBox) => {
    remove();
    messageBox.close();
});

// когда нужен контроль над окном после открытия
const box = new MessageBox({
    message: 'Идёт сохранение',
    buttons: MessageBoxButtons.OK_CANCEL,
});
box.show();
box.setMessage('Готово');

Разница принципиальная: статический вызов не возвращает экземпляр, поэтому управлять окном после открытия не получится. Если нужны закрытие или смена текста из кода - создавайте объект.

3. Попап и меню

import { Popup, Menu } from 'main.popup';

const popup = new Popup({
    bindElement: anchor,
    content: 'Содержимое',
    cacheable: false,      // окно удалится после закрытия
});
popup.show();

const menu = new Menu({
    bindElement: button,
    items: [
        { id: 'edit', text: 'Изменить', onclick: () => edit() },
        { id: 'delete', text: 'Удалить', onclick: () => remove() },
    ],
});
menu.show();

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

Пункты меню требуют уникальных идентификаторов - добавление пункта с уже существующим идентификатором молча игнорируется.

4. Боковой слайдер

BX.SidePanel.Instance.open('/company/personal/user/1/', {
    width: 800,
    cacheable: false,
});

// данные, переданные в слайдер
const value = slider.getData().get('key');

Слайдер тоже кеширует содержимое: повторное открытие того же адреса покажет сохранённую страницу. Данные слайдера возвращаются словарём, а не обычным объектом, - обращаться к ним нужно через метод получения значения.

Справочник API

Расширение	Что даёт	Особенности
`ui.buttons`	кнопки и составные кнопки	готовые кнопки с локализацией, два стиля оформления
`ui.dialogs.messagebox`	окна сообщений и подтверждений	статический вызов не возвращает экземпляр
`ui.system.dialog`	системный модальный диалог	рекомендуется для новых интерфейсов
`ui.system.menu`	системное меню
`ui.system.alert`	сообщения-предупреждения	действие не выполняется само
`ui.system.chip`, `ui.system.input`, `ui.system.label`	элементы форм	JS-класс и Vue-компонент
`ui.system.skeleton`	заглушки загрузки
`main.popup`	попапы и меню	точное позиционирование, менеджеры
`main.sidepanel`	боковой слайдер	внешний адрес или своё содержимое
`ui.icons`	иконки	без CSS-расширения набора не отобразятся
`Bitrix\UI\Buttons`	кнопки со стороны PHP	когда разметка формируется на сервере

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

Окно нельзя закрыть из кода. Использован статический вызов, который не возвращает экземпляр. Создавайте объект.

Закрытое окно всплывает снова с прежним содержимым. Оно кешируется по умолчанию - отключите кеширование или уничтожьте объект.

Пункт меню не добавляется. Идентификатор совпадает с уже существующим.

Данные слайдера читаются как свойства объекта. Они возвращаются словарём, нужен метод получения значения.

Иконка не появилась. Либо не подключено CSS-расширение набора, либо методы настройки вызваны до отрисовки - до неё у объекта ещё нет элемента на странице.

Ожидают, что системный компонент сам выполнит действие. Он вызывает обработчик, а закрытие и удаление - на вас.

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

Что выбрать для модального окна?

Для новых интерфейсов - системный диалог: он в актуальном оформлении и согласован с остальными компонентами. Окно сообщения подходит для простых подтверждений и уведомлений. Базовый механизм попапов берут, когда нужно точное позиционирование относительно элемента или требуется совместимость со старым кодом.

Почему окно нельзя закрыть программно?

Скорее всего, оно открыто статическим методом, который сам создаёт и показывает окно, но не отдаёт ссылку на него. Если после открытия нужно менять текст, кнопки или закрывать окно из кода, создавайте экземпляр явно и вызывайте показ у него.

Зачем кнопкам отдельное расширение, если можно свёрстанную кнопку?

Ради единообразия и поведения: готовые кнопки уже локализованы, имеют состояния загрузки и блокировки, корректно встраиваются в диалоги и попапы и обновляются вместе с платформой. Своя вёрстка со временем начинает отличаться от системных интерфейсов, особенно после смены оформления.

Почему повторно открытый слайдер показывает старое содержимое?

Потому что слайдер кеширует открытые страницы: повторное открытие того же адреса переиспользует уже загруженную. Если содержимое должно быть свежим, отключайте кеширование при открытии. Та же логика действует и у попапов.

Связанные темы

Ядро BX - на чём построены виджеты
Подключение JS/CSS - как загрузить расширение
BitrixVue 3 - Vue-версии тех же компонентов
Админ-интерфейс - гриды и формы в админке
Раздел JS и интерфейсы