Показ модальных окон и предупреждений

Модальные окна служат для отображения сообщений и блокировки взаимодействия пользователя с окном приложения.

Показ модального окна

Модальные окна могут содержать простой текст или HTML-контент. Это поведение, как и остальные настройки, задается в объекте, который передается в метод showModal().

Пример того, как показать текущий выделенный фрагмент документа в модальном окне:

async function getSelectionAsText() {
    // Получаем выделенный текст в простом формате
    const text = await editorApi.document.selection.getSelectionAsText('plain/text');
    // Открываем модальное окно с простым текстом
    editorApi.ui.modals.showModal({
        id: 'demo-plugin:modal.about',       // Уникальный идентификатор окна
        title: 'Выделение как текст',        // Заголовок окна
        content: text,                       // Содержимое окна
    });
}

async function getSelectionAsHtml() {
    // Получаем выделенный текст в формате HTML
    const html = await editorApi.document.selection.getSelectionAsText('html');
    // Открываем модальное окно с HTML-кодом
    editorApi.ui.modals.showModal({
        id: 'demo-plugin:modal.about',       // Уникальный идентификатор окна
        title: 'Выделение как HTML',         // Заголовок окна
        content: html,                       // Содержимое окна
        contentType: 'html',                 // Указываем, что контент HTML
    });
}

Переопределение кнопок модального окна

Модальные окна сопровождаются стандартными кнопками ("ОК" или "Отмена"). Однако иногда нужно адаптировать поведение или оформление этих кнопок, например, изменить надпись или назначить собственное действие.

API предоставляет возможность переопределять стандартные кнопки модальных окон. Например, задать собственные названия и функциональность:

function onModalOk() {
    console.log('Пользователь нажал кнопку "Понятно"');
}

editorApi.ui.modals.showModal({
    id: 'custom-modal-1',                                  // Уникальный идентификатор окна
    title: 'Предупреждение',                               // Заголовок окна
    content: 'К сожалению, в данной версии надстройки это сделать невозможно.', // Сообщение
    okButton: {                                            // Персонализация кнопки ОК
        title: 'Понятно',                                  // Новая надпись на кнопке
        onClick: editorApi.createCallback(onModalOk),      // Новый обработчик события
    },
});

Показ уведомления

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

Для показа уведомлений воспользуйтесь методом editorApi.ui.toasts.showToast.
При этом можно переопределить интервал, через который уведомление должно исчезнуть.

// Покажем простое уведомление, которое исчезнет через 3 секунды (дефолтный таймаут)
async function showWarning() {
    editorApi.ui.toasts.showToast({
        id: 'demo-plugin:toast.warn',           // Уникальный идентификатор окна
        content: 'Выберите текст в редакторе',  // Текст уведомления
    });
}

// Покажем уведомление, которое исчезнет через 10 секунд
async function showWarningWithDuration(duration = 10_000) {
    editorApi.ui.toasts.showToast({
        id: 'demo-plugin:toast.warn',        
        content: 'Выберите текст в редакторе, чтобы обработать его',
        autohideIntervalMs: duration,
    });
}