Системный диалог

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

Компонент задает структуру диалога по правилам дизайн-системы: заголовок и подзаголовок, область содержимого, нижнюю панель с кнопками, фон, затемнение страницы и поведение закрытия.

В Bitrix Framework за системный диалог отвечает расширение ui.system.dialog. Оно экспортирует класс Dialog и объект DialogBackground.

Подключить расширение

Если вы подключаете компонент из PHP, загрузите расширение ui.system.dialog.

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

Если вы работаете в модульном JavaScript, импортируйте нужные экспорты из ui.system.dialog.

import { Dialog, DialogBackground } from 'ui.system.dialog';

Показать диалог

Чтобы открыть диалог, создайте экземпляр Dialog, передайте DOM-узел в content и вызовите show().

import { Dialog } from 'ui.system.dialog';
        
        const content = document.createElement('div');
        content.textContent = 'Изменения будут применены ко всем выбранным элементам.';
        
        const dialog = new Dialog({
            title: 'Подтвердите действие',
            subtitle: 'Проверьте параметры перед продолжением',
            content,
            width: 420,
            hasOverlay: true,
        });
        
        dialog.show();

Метод Dialog.show(options) создает и сразу открывает диалог. Используйте его, если после открытия не нужно менять заголовок, содержимое или кнопки через экземпляр Dialog.

import { Dialog } from 'ui.system.dialog';
        
        const content = document.createElement('div');
        content.textContent = 'Настройки сохранены.';
        
        Dialog.show({
            title: 'Готово',
            content,
        });

Передать параметры

Конструктор Dialog принимает объект с параметрами содержимого, оформления и поведения диалога.

  • content — DOM-узел с содержимым диалога. Компонент выводит его в основной области окна. Обязательный параметр.

  • title — заголовок диалога. Если не передать title и subtitle, шапка диалога скрывается.

  • subtitle — подзаголовок под title. Используйте его для короткого уточнения контекста, а не для основного содержимого.

  • width — фиксированная ширина окна в пикселях. Если параметр не передан, ширина не задается компонентом.

  • hasCloseButton — кнопка закрытия в правой части шапки. Клик по кнопке закрывает диалог.

  • leftButtons, centerButtons, rightButtons — массивы кнопок для нижней панели.

  • hasHorizontalPadding — горизонтальные отступы области содержимого. Передайте false, если содержимое должно занимать всю ширину диалога.

  • hasVerticalPadding — вертикальные отступы области содержимого. Передайте false, если отступы задает внутренний компонент.

  • hasOverlay — затемнение страницы под диалогом.

  • disableScrolling — блокировка прокрутки страницы на время показа диалога.

  • closeByEsc — закрытие по клавише Esc.

  • closeByClickOutside — закрытие по клику вне диалога.

  • background — фон диалога. Значения доступны в DialogBackground.

  • events — обработчики событий диалога.

По умолчанию hasCloseButton, hasHorizontalPadding, hasVerticalPadding, closeByEsc и closeByClickOutside равны true, а hasOverlay и disableScrolling — false.

Добавить кнопки

Кнопки передаются в одну из трех зон нижней панели: leftButtons, centerButtons или rightButtons. Диалог не создает кнопки сам, а только выводит переданные объекты с методом render().

import { Dialog } from 'ui.system.dialog';
        import { Button, AirButtonStyle } from 'ui.buttons';
        
        // Создайте DOM-узел для основной области диалога.
        const content = document.createElement('div');
        content.textContent = 'Отменить действие будет нельзя.';
        
        // Подготовьте кнопки, которые нужно вывести в нижней панели.
        const cancelButton = new Button({
            text: 'Отмена',
            useAirDesign: true,
            onclick: () => dialog.hide(),
        });
        
        const deleteButton = new Button({
            text: 'Удалить',
            style: AirButtonStyle.FILLED_ALERT,
            useAirDesign: true,
            onclick: () => {
                // Выполните удаление и закройте диалог.
                dialog.hide();
            },
        });
        
        const dialog = new Dialog({
            title: 'Удалить элемент',
            content,
            width: 420,
            hasOverlay: true,
            // Передайте кнопки в правую зону нижней панели.
            rightButtons: [
                {
                    render: () => deleteButton.render(),
                },
                {
                    render: () => cancelButton.render(),
                },
            ],
        });
        
        dialog.show();

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

Настроить закрытие

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

import { Dialog } from 'ui.system.dialog';
        
        const content = document.createElement('div');
        content.textContent = 'Форма содержит несохраненные данные.';
        
        const dialog = new Dialog({
            title: 'Заполните обязательные поля',
            content,
            hasCloseButton: false,
            closeByEsc: false,
            closeByClickOutside: false,
            hasOverlay: true,
        });
        
        dialog.show();

Выбрать фон

Фон задается параметром background.

  • DialogBackground.default — основной фон диалога. Используется по умолчанию.

  • DialogBackground.vibrant — вариант фона с размытием для диалога поверх затемненной страницы.

import { Dialog, DialogBackground } from 'ui.system.dialog';
        
        const content = document.createElement('div');
        content.textContent = 'Параметры формы.';
        
        const dialog = new Dialog({
            title: 'Настройки',
            content,
            background: DialogBackground.vibrant,
            hasOverlay: true,
        });
        
        dialog.show();

Обработать события

Передайте обработчики в events, если нужно синхронизировать состояние страницы с открытием или закрытием диалога.

  • onShow — вызывается при показе диалога.

  • onAfterShow — вызывается после показа диалога.

  • onHide — вызывается при закрытии диалога.

  • onAfterHide — вызывается после закрытия диалога.

import { Dialog } from 'ui.system.dialog';
        
        const content = document.createElement('div');
        content.textContent = 'Выберите формат файла.';
        
        const dialog = new Dialog({
            title: 'Экспорт',
            content,
            events: {
                onShow: () => {
                    console.log('Диалог открыт');
                },
                onAfterHide: () => {
                    console.log('Диалог закрыт');
                },
            },
        });
        
        dialog.show();

Управлять диалогом

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

  • show() — открывает диалог.

  • hide() — закрывает диалог.

  • setTitle(title) — меняет заголовок. Если диалог уже открыт, заголовок обновляется сразу.

  • setSubtitle(subtitle) — меняет подзаголовок.

  • setContent(content) — заменяет DOM-узел в области содержимого.

  • setLeftButtons(buttons) — заменяет кнопки слева.

  • setCenterButtons(buttons) — заменяет кнопки по центру.

  • setRightButtons(buttons) — заменяет кнопки справа.

import { Dialog } from 'ui.system.dialog';
        
        const content = document.createElement('div');
        content.textContent = 'Подождите, идет подготовка данных.';
        
        const dialog = new Dialog({
            title: 'Загрузка',
            content,
            hasOverlay: true,
        });
        
        dialog.show();
        
        const result = document.createElement('div');
        result.textContent = 'Данные подготовлены.';
        
        dialog.setTitle('Готово');
        dialog.setContent(result);
Предыдущая
Системный чип
Следующая
Системный хайлайтер