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

ui.dialogs.messagebox — модальное окно для сообщения, подтверждения действия или выбора ответа.

Компонент подходит для сценариев, где разработчику нужно показать короткий текст и обработать нажатие на кнопку OK, Отмена, Да или Нет.

В расширении доступны класс MessageBox и объект MessageBoxButtons.

MessageBox создает окно и задает заголовок, текст, размеры и обработчики кнопок.

MessageBoxButtons содержит наборы стандартных кнопок для информационного сообщения, подтверждения и выбора ответа.

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

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

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

Если вы работаете в модульном JavaScript, импортируйте MessageBox и MessageBoxButtons из ui.dialogs.messagebox.

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

Показать сообщениеПоказать сообщение

MessageBox.alert() открывает окно с одной кнопкой OK. В первый аргумент передайте строку или DOM-узел, обработчик кнопки OK укажите следующим аргументом.

import { MessageBox } from 'ui.dialogs.messagebox';
        
        MessageBox.alert('Настройки сохранены.');
        

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

MessageBox.alert(message, onOk, okCaption);
        

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

MessageBox.alert(message, title, onOk, okCaption);
        

Аргументы метода:

• message — обязательный аргумент. Сообщение в виде строки или DOM-узла.

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

• onOk — обработчик кнопки OK.

• okCaption — текст кнопки OK.

import { MessageBox } from 'ui.dialogs.messagebox';
        
        MessageBox.alert(
        	'Проверьте параметры перед продолжением.',
        	'Параметры задачи',
        	() => true,
        	'Понятно',
        );
        

Метод возвращает экземпляр MessageBox. Используйте его, если после открытия нужно закрыть окно из внешнего кода или получить доступ к методам экземпляра.

Запросить подтверждениеЗапросить подтверждение

MessageBox.confirm() открывает окно с кнопками OK и Отмена. В первый аргумент передайте строку или DOM-узел, обработчики кнопок OK и Отмена укажите следующими аргументами.

Метод подходит для удаления, отмены действия или другого сценария, где пользователь должен подтвердить операцию.

import { MessageBox } from 'ui.dialogs.messagebox';
        
        MessageBox.confirm(
        	'Удалить элемент?',
        	(messageBox) => {
        		return BX.ajax.runAction('example.Item.delete', {
        			data: {
        				id: 42,
        			},
        		});
        	},
        	'Удалить',
        );
        

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

MessageBox.confirm(message, onOk, okCaption, onCancel, cancelCaption, useAirDesign);
        

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

MessageBox.confirm(message, title, onOk, okCaption, onCancel, cancelCaption, useAirDesign);
        

Аргументы метода:

• message — обязательный аргумент. Сообщение в виде строки или DOM-узла.

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

• onOk — обработчик кнопки OK.

• okCaption — текст кнопки OK.

• onCancel — обработчик кнопки Отмена.

• cancelCaption — текст кнопки Отмена.

• useAirDesign — включает оформление Air Design для окна и кнопок.

import { MessageBox } from 'ui.dialogs.messagebox';
        
        MessageBox.confirm(
        	'Отменить изменения в форме?',
        	'Несохраненные данные',
        	() => true,
        	'Отменить изменения',
        	() => false,
        	'Вернуться',
        	true,
        );
        

MessageBox.confirm() возвращает экземпляр MessageBox, как и MessageBox.alert().

Создать окно с настройкамиСоздать окно с настройками

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

import { MessageBox } from 'ui.dialogs.messagebox';
        
        MessageBox.show({
        	title: 'Заявка отправлена',
        	message: 'Ответственный получит уведомление.',
        	modal: true,
        	buttons: BX.UI.Dialogs.MessageBoxButtons.OK,
        });
        

MessageBox.show(options) не возвращает экземпляр окна.

Если после открытия нужно вызвать close(), setMessage(), setTitle() или изменить кнопки, создайте экземпляр MessageBox и вызовите show().

import { MessageBox } from 'ui.dialogs.messagebox';
        
        const messageBox = new MessageBox({
        	title: 'Удалить контакт',
        	message: 'Контакт будет удален из адресной книги.',
        	buttons: BX.UI.Dialogs.MessageBoxButtons.OK_CANCEL,
        	okCaption: 'Удалить',
        	cancelCaption: 'Отмена',
        	onOk: () => {
        		messageBox.close();
        		return false;
        	},
        });
        
        messageBox.show();
        

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

После создания вызовите show().

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

Конструктор MessageBox и метод MessageBox.show() принимают объект options. Все параметры options необязательные. Без сообщения message окно откроется без содержимого.

Выбрать кнопкиВыбрать кнопки

В buttons передайте строковое значение из MessageBoxButtons. Компонент создаст кнопки с локализованными подписями.

Если выбран MessageBoxButtons.NONE, в окне нет стандартных кнопок. Обработчики onOk, onCancel, onYes и onNo не сработают при нажатии на стандартную кнопку.

Если стандартного набора недостаточно, передайте массив кнопок BX.UI.Button.

import { MessageBox } from 'ui.dialogs.messagebox';
        
        const messageBox = new MessageBox({
        	message: 'Выберите действие.',
        	buttons: [
        		new BX.UI.Button({
        			text: 'Архивировать',
        			color: BX.UI.Button.Color.PRIMARY,
        			events: {
        				click: () => messageBox.close(),
        			},
        		}),
        	],
        });
        
        messageBox.show();
        

Обработать нажатие на кнопкуОбработать нажатие на кнопку

Для new MessageBox и MessageBox.show обработчики задаются в объекте параметров. Укажите обработчик для кнопки, на нажатие которой нужно отреагировать:

• onOk — обработчик кнопки OK,

• onCancel — обработчик кнопки Отмена,

• onYes — обработчик кнопки Да,

• onNo — обработчик кнопки Нет.

По умолчанию значение каждого параметра — null.

Обработчик получает три аргумента: экземпляр MessageBox, кнопку и событие нажатия.

import { MessageBox } from 'ui.dialogs.messagebox';
        
        const messageBox = new MessageBox({
        	message: 'Удалить элемент?',
        	buttons: BX.UI.Dialogs.MessageBoxButtons.OK_CANCEL,
        	onOk: (box, button, event) => {
        		return BX.ajax.runAction('example.Item.delete', {
        			data: {
        				id: 42,
        			},
        		});
        	},
        	onCancel: () => true,
        });
        
        messageBox.show();
        

Поведение кнопки зависит от результата обработчика:

• если обработчик не задан, окно закрывается,

• если обработчик возвращает true, окно закрывается,

• если обработчик возвращает false, окно остается открытым,

• если обработчик возвращает Promise или BX.Promise, кнопка переходит в состояние ожидания.

Если асинхронная операция завершится успешно, окно закроется. Если операция завершится с ошибкой, окно останется открытым.

На время выполнения обработчика кнопка блокируется. Это защищает сценарий от повторного нажатия до завершения текущего действия.

Изменить окно после созданияИзменить окно после создания

Экземпляр MessageBox хранит состояние окна. После создания измените сообщение, заголовок, кнопки и подписи стандартных кнопок.

import { MessageBox } from 'ui.dialogs.messagebox';
        
        const messageBox = new MessageBox({
        	message: 'Идет проверка данных.',
        	buttons: BX.UI.Dialogs.MessageBoxButtons.OK,
        });
        
        messageBox.show();
        messageBox.setTitle('Готово');
        messageBox.setMessage('Данные проверены.');
        messageBox.setOkCaption('Закрыть');
        // Подписи остальных кнопок меняют `setCancelCaption()`, `setYesCaption()` и `setNoCaption()`.
        

Для закрытия окна вызовите close().

messageBox.close();
        

Создавайте экземпляр MessageBox, когда после открытия нужно управлять окном из кода. Для одноразового сообщения или подтверждения достаточно MessageBox.alert(), MessageBox.confirm() или MessageBox.show(options).