Настройка контекстного меню

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

Регистрация нового пункта осуществляется через API редактора.

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

Пример регистрации пункта в контекстном меню:

// Создаем новый пункт в контекстном меню
editorApi.ui.contextMenu.addItems([
    {
        id: 'plugin1:my-button', // Уникальный ID команды
        title: 'Моя кнопка', // Название команды, показываемое пользователю
    },
]);

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

Рассмотрим подробнее доступные настройки:

Обработка нажатия

Для обработки события нажатия на пункт контекстного меню нужно добавить обработчик onClick, который выполняет необходимое действие.

Вот простой пример, демонстрирующий вывод уведомления при нажатии на кнопку:

function doAction() {
    editorApi.ui.toasts.showToast({
        id: 'plugin1:toast:warning',
        content: 'Сообщение от надстройки',
    });
}

editorApi.ui.contextMenu.addItems([
    {
        id: 'plugin1:my-button',               // Уникальный идентификатор кнопки
        title: 'Моя кнопка',                   // Название кнопки
        // Обратите внимание на создание функции обратного вызова
        onClick: editorApi.createCallback(doAction)
    },
]);

Управление отображением и активностью элементов

Вы можете настраивать отображение пунктов меню и их активность в зависимости от определенных условий. Например, показывать кнопку только если выделен текст.

Отображение элемента в зависимости от выделения

Этот пример показывает пункт меню только тогда, когда выделен текст:

editorApi.ui.contextMenu.addItems([
    {
        id: 'plugin1:my-button',      // Уникальный идентификатор кнопки
        title: 'Моя кнопка',          // Видимое название
        shownInScopes: [{ mode: 'selection' }], // Показывается только при выделении текста
    },
]);

Деактивация элемента в зависимости от позиции курсора в документе

Данный код отключает элемент меню для таблиц и элементов внутри таблиц:

editorApi.ui.contextMenu.addItems([
    {
        id: 'plugin1:my-button',     // Уникальный идентификатор кнопки
        title: 'Моя кнопка',         // Видимое название
        disabledInScopes: [
            { scope: 'table' },      // Деактивируется, когда выбрана таблица
            { parentScope: 'table' } // Деактивируется, когда курсор внутри таблицы
        ],
    },
]);

Дополнительные подробности о расположении курсора и условиях активации/отображения можно посмотреть в описании интерфейса DocumentScope.

Показ меню второго уровня

Чтобы сделать контекстное меню удобнее и более структурированным, можно создавать вложенные подпункты.

Ниже приведён пример реализации многоуровневого меню, которое добавляет дополнительные команды редактирования ("Вырезать", "Скопировать", "Вставить") в качестве дочерних элементов основной кнопки.

const actions = {
    cut: {
        id: 'demo-plugin:ribbon:cut',
        title: 'Вырезать в буфер обмена',
        icon: 'Cut',
        type: 'button',
        groupingId: 'copy-paste',
        onClick: callbacks.clipboard.cut,
    },
    copy: {
        id: 'demo-plugin:ribbon:copy',
        title: 'Копировать в буфер обмена',
        icon: 'Copy',
        type: 'button',
        groupingId: 'copy-paste',
        onClick: callbacks.clipboard.copy,
    },
    paste: {
        id: 'demo-plugin:ribbon:paste',
        title: 'Вставить из буфера обмена',
        icon: 'Paste',
        type: 'button',
        groupingId: 'copy-paste',
        onClick: callbacks.clipboard.paste,
    },
};

editorApi.ui.contextMenu.addItems([
    {
        id: 'plugin1:my-button',     
        title: 'Моя кнопка',         
        items: [
            actions.cut,
            actions.copy,
            actions.paste,
        ],
    },
]);