Версия: 26.1.0 (в разработке)

Interface: ContextMenuApi

API для управления контекстным меню (правый клик) в редакторе.

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

Remarks

Типичное расположение в контекстном меню:

Копировать
Вырезать
Вставить
─────────────────────
Ваши пункты меню    ← добавляются здесь
─────────────────────
Форматирование
Стиль

Рекомендации по дизайну:

Максимум 3-5 основных пунктов меню
Группируйте связанные пункты в подменю (cascading items)
Используйте иконки для быстрого визуального распознавания
Предусмотрите условную видимость (shownInScopes, disabledInScopes)
Не перегружайте меню — это снижает удобство использования

Области видимости (scopes):

text — пункт меню над текстом
table — пункт меню над таблицей
image — пункт меню над изображением
selection — пункт меню над выделением

Когда использовать:

Быстрые действия над контентом (копирование, анализ, трансформация)
Контекстные операции в зависимости от типа элемента
Доступ к функциям надстройки без переходов в UI

Example

Добавление простых пунктов меню

editorApi.ui.contextMenu.addItems([
  {
    id: 'plugin:convert-to-upper',
    title: 'Преобразовать в ВЕРХНИЙ РЕГИСТР',
    icon: 'TextUppercase',
    onClick: editorApi.createCallback(async () => {
      const text = await editorApi.document.selection.getSelectionAsText();
      if (text) {
        await editorApi.document.insertContent(text.toUpperCase());
      }
    })
  }
]);

Меню с условной видимостью

editorApi.ui.contextMenu.addItems([
  {
    id: 'plugin:action-on-text',
    title: 'Действие только над текстом',
    shownInScopes: ['text', 'selection'],  // Видно только над текстом
    onClick: editorApi.createCallback(() => {
      // действие
    })
  },
  {
    id: 'plugin:action-on-table',
    title: 'Действие над таблицей',
    shownInScopes: ['table'],              // Видно только над таблицей
    onClick: editorApi.createCallback(() => {
      // действие
    })
  }
]);

Сгруппированное меню с подпунктами

editorApi.ui.contextMenu.addItems([
  {
    groupingId: 'plugin_export',
    id: 'plugin:export-group',
    title: 'Экспортировать',
    icon: 'Download',
    subItems: [
      {
        id: 'plugin:export-pdf',
        title: 'Экспортировать в PDF',
        onClick: editorApi.createCallback(() => {
          // экспорт в PDF
        })
      },
      {
        id: 'plugin:export-html',
        title: 'Экспортировать в HTML',
        onClick: editorApi.createCallback(() => {
          // экспорт в HTML
        })
      }
    ]
  }
]);

Управление видимостью и состоянием

editorApi.ui.contextMenu.addItems([
  {
    id: 'plugin:paste-special',
    title: 'Специальная вставка',
    disabledInScopes: ['empty'],           // Отключено в пустом месте
    disabledIf: async () => {
      // Отключить, если нечего вставлять
      return !(await navigator.clipboard.readText()).length;
    },
    onClick: editorApi.createCallback(() => {
      // действие
    })
  }
]);

Надстройка с полным контекстным меню

export default {
  onInit: (editorApi) => {
    const callbacks = {
      insertText: editorApi.createCallback(async () => {
        await editorApi.document.insertContent('Вставленный текст');
      }),
      insertHtml: editorApi.createCallback(async () => {
        await editorApi.document.insertContent(
          '<p><b>Жирный текст</b></p>',
          'html'
        );
      }),
      convertToUpper: editorApi.createCallback(async () => {
        const text = await editorApi.document.selection.getSelectionAsText();
        if (text) {
          await editorApi.document.insertContent(text.toUpperCase());
        }
      })
    };

    editorApi.ui.contextMenu.addItems([
      {
        id: 'plugin:insert-text',
        title: 'Вставить текст',
        icon: 'Plus',
        onClick: callbacks.insertText
      },
      {
        id: 'plugin:insert-html',
        title: 'Вставить HTML',
        icon: 'Code',
        onClick: callbacks.insertHtml
      },
      {
        groupingId: 'plugin_text_transform',
        id: 'plugin:convert-upper',
        title: 'ВЕРХНИЙ РЕГИСТР',
        shownInScopes: ['selection'],
        onClick: callbacks.convertToUpper
      }
    ]);
  },

  onDestroy: (editorApi) => {
    // Удалить все пункты меню при выгрузке надстройки
    editorApi.ui.contextMenu.removeItems([
      'plugin:insert-text',
      'plugin:insert-html',
      'plugin:convert-upper'
    ]);
  }
}

See

ContextMenuItem — структура элемента контекстного меню
EditorUiApi.ribbon — для добавления элементов в ленту инструментов
EditorUiApi.sidebar — для добавления боковых панелей

Methods

addItems()

addItems(items): void

Добавляет кастомные элементы в контекстное меню документа.

Новые пункты появятся ниже стандартных пунктов меню редактора (Копировать, Вставить и т.д.).

Parameters

items

ContextMenuItem[]

Массив элементов для регистрации в контекстном меню

Returns

void

Remarks

Структура ContextMenuItem:

id (обязательно) — уникальный идентификатор элемента
title (обязательно) — текст, отображаемый в меню
onClick (обязательно) — callback, вызываемый при клике
icon (опционально) — иконка элемента
groupingId (опционально) — ID группы для группировки пунктов
shownInScopes (опционально) — область видимости (text, table, image, selection, empty)
disabledInScopes (опционально) — области, где пункт отключен
subItems (опционально) — подпункты для каскадного меню
disabledIf (опционально) — функция для условного отключения

Правила именования:

ID должен быть уникален в рамках надстройки
Рекомендуется префикс: plugin:context-menu:имя-действия
Избегайте специальных символов, используйте только буквы, цифры, дефисы

Группировка пунктов:

groupingId позволяет визуально группировать связанные пункты
Пункты с одинаковым groupingId отделяются разделителем (──)
Максимум 2-3 группы для удобства

Производительность:

Добавьте не более 5-10 основных пунктов
Используйте подменю (subItems) для организации
Избегайте слишком сложных иконок

Example

Простой пункт меню

editorApi.ui.contextMenu.addItems([
  {
    id: 'plugin:action',
    title: 'Мое действие',
    icon: 'Star',
    onClick: editorApi.createCallback(async () => {
      console.log('Пункт меню нажат');
    })
  }
]);

Несколько пунктов с группировкой

editorApi.ui.contextMenu.addItems([
  {
    id: 'plugin:action-1',
    title: 'Действие 1',
    groupingId: 'plugin_group1',
    onClick: editorApi.createCallback(() => {})
  },
  {
    id: 'plugin:action-2',
    title: 'Действие 2',
    groupingId: 'plugin_group1',
    onClick: editorApi.createCallback(() => {})
  },
  {
    id: 'plugin:action-3',
    title: 'Действие 3',
    groupingId: 'plugin_group2',
    onClick: editorApi.createCallback(() => {})
  }
]);

Пункты с условной видимостью

editorApi.ui.contextMenu.addItems([
  {
    id: 'plugin:cut-text',
    title: 'Вырезать текст',
    shownInScopes: ['text', 'selection'],  // Видимо только над текстом
    onClick: editorApi.createCallback(async () => {
      await editorApi.document.clipboard.cut();
    })
  },
  {
    id: 'plugin:paste-special',
    title: 'Специальная вставка',
    disabledInScopes: ['empty'],  // Отключено в пустом месте
    onClick: editorApi.createCallback(async () => {
      await editorApi.document.clipboard.paste();
    })
  }
]);

Каскадное (вложенное) меню

editorApi.ui.contextMenu.addItems([
  {
    id: 'plugin:export',
    title: 'Экспортировать',
    icon: 'Download',
    items: [
      {
        id: 'plugin:export-pdf',
        title: 'В PDF',
        onClick: editorApi.createCallback(() => {
          // экспорт в PDF
        })
      },
      {
        id: 'plugin:export-docx',
        title: 'В Word',
        onClick: editorApi.createCallback(() => {
          // экспорт в Word
        })
      },
      {
        id: 'plugin:export-html',
        title: 'В HTML',
        onClick: editorApi.createCallback(() => {
          // экспорт в HTML
        })
      }
    ]
  }
]);

See

ContextMenuItem — полное описание структуры элемента
removeItems — удаление пунктов меню

removeItems()

removeItems(items): void

Удаляет ранее зарегистрированные кастомные элементы из контекстного меню.

Parameters

items

string[]

Массив ID элементов для удаления (созданные методом addItems)

Returns

void

Remarks

Правила удаления:

Удаляются только элементы, зарегистрированные текущей надстройкой
ID должны точно совпадать с ID при регистрации
Удаление несуществующего ID молча игнорируется (не выбрасывает ошибку)
После удаления пункты исчезают из меню сразу

Когда вызывать:

В методе onDestroy при выгрузке надстройки
При отключении функции в надстройке
При перезагрузке конфигурации

Производительность:

Операция практически мгновенная
Безопасно вызывать несколько раз
Не требует дополнительной очистки

Example

Удаление одного элемента

editorApi.ui.contextMenu.removeItems(['plugin:my-action']);

Удаление нескольких элементов

editorApi.ui.contextMenu.removeItems([
  'plugin:insert-text',
  'plugin:insert-html',
  'plugin:action-3'
]);

Удаление при выгрузке надстройки

export default {
  onInit: (editorApi) => {
    editorApi.ui.contextMenu.addItems([
      { id: 'plugin:action-1', title: '...', onClick: ... },
      { id: 'plugin:action-2', title: '...', onClick: ... }
    ]);
  },

  onDestroy: (editorApi) => {
    // Удалить все пункты при выгрузке
    editorApi.ui.contextMenu.removeItems([
      'plugin:action-1',
      'plugin:action-2'
    ]);
  }
}

Удаление с проверкой

async function cleanupContextMenu(editorApi, items) {
  try {
    editorApi.ui.contextMenu.removeItems(items);
    console.log('Пункты меню удалены');
  } catch (error) {
    console.error('Ошибка при удалении:', error);
  }
}

See

addItems — регистрация пунктов меню
EditorPlugin.onDestroy — метод для очистки при выгрузке надстройки

Remarks​

Example​

See​

Methods​

addItems()​

Parameters​

items​

Returns​

Remarks​

Example​

See​

removeItems()​

Parameters​

items​

Returns​

Remarks​

Example​

See​

Remarks

Example

See

Methods

addItems()

Parameters

items

Returns

Remarks

Example

See

removeItems()

Parameters

items

Returns

Remarks

Example

See