Перейти к основному содержимому
Версия: 26.1.0 (в разработке)

Type Alias: ContextMenuItem

ContextMenuItem = SimpleContextMenuItem | ContextMenuItemWithDropdown

Объединённый тип для всех поддерживаемых вариантов элементов контекстного меню.

Представляет собой union type, который позволяет использовать любой из поддерживаемых типов элементов контекстного меню в методах ContextMenuApi.addItems.

Remarks​

Поддерживаемые типы:

ТипОписаниеИспользование
SimpleContextMenuItemПростой пункт без подменюПрямые действия
ContextMenuItemWithDropdownПункт с выпадающим подменюГруппировка действий

Как работает union type:

  • ContextMenuItem может быть либо SimpleContextMenuItem, либо ContextMenuItemWithDropdown
  • TypeScript автоматически проверяет тип при использовании
  • В runtime можно проверить наличие свойства items для определения типа

Иерархия типов:

ContextMenuItem (текущий union type)
  ├── SimpleContextMenuItem
  │   └── extends BaseContextMenuItem
  │       ├── extends BaseControl
  │       └── extends MayHaveIcon
  │   └── onClick: Callback (обязательно)
  │
  └── ContextMenuItemWithDropdown
      └── extends BaseContextMenuItem
          ├── extends BaseControl
          └── extends MayHaveIcon
      └── items: ContextMenuItem[] (обязательно)

Общие свойства для всех типов:

  • id — уникальный идентификатор элемента
  • title — текст, отображаемый в меню
  • icon? — иконка элемента (опционально)
  • shownInScopes? — условия видимости (опционально)
  • disabledInScopes? — условия отключения (опционально)
  • groupingId? — ID группы для группировки (опционально)

Различия между типами:

SimpleContextMenuItem:

  • onClick: Callback — обработчик клика (обязательно)
  • Нет свойства items
  • Используется для прямых действий
  • Одиночный пункт меню

ContextMenuItemWithDropdown:

  • items: ContextMenuItem[] — массив вложенных элементов (обязательно)
  • Нет свойства onClick на главном уровне
  • Используется для группировки связанных действий
  • Имеет подменю с дополнительными опциями

Example​

Использование SimpleContextMenuItem

const menuItem: ContextMenuItem = {
  id: 'plugin:action',
  title: 'Простое действие',
  onClick: editorApi.createCallback(() => {
    console.log('Действие выполнено');
  })
};

editorApi.ui.contextMenu.addItems([menuItem]);

Использование ContextMenuItemWithDropdown

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

editorApi.ui.contextMenu.addItems([menuItem]);

Смешивание типов в одном массиве

const menuItems: ContextMenuItem[] = [
  // SimpleContextMenuItem
  {
    id: 'plugin:copy',
    title: 'Копировать',
    onClick: editorApi.createCallback(async () => {
      await editorApi.document.clipboard.copy();
    })
  },
  // ContextMenuItemWithDropdown
  {
    id: 'plugin:export',
    title: 'Экспортировать',
    items: [
      {
        id: 'plugin:export-pdf',
        title: 'PDF',
        onClick: editorApi.createCallback(() => {})
      }
    ]
  },
  // Ещё SimpleContextMenuItem
  {
    id: 'plugin:paste',
    title: 'Вставить',
    onClick: editorApi.createCallback(async () => {
      await editorApi.document.clipboard.paste();
    })
  }
];

editorApi.ui.contextMenu.addItems(menuItems);

Определение типа в runtime (type guard)

function isSimpleMenuItem(item: ContextMenuItem): item is SimpleContextMenuItem {
  return 'onClick' in item && !('items' in item);
}

function isDropdownMenuItem(item: ContextMenuItem): item is ContextMenuItemWithDropdown {
  return 'items' in item && !('onClick' in item);
}

const menuItem: ContextMenuItem = {
  id: 'plugin:action',
  title: 'Действие',
  onClick: editorApi.createCallback(() => {})
};

if (isSimpleMenuItem(menuItem)) {
  console.log('Это простой пункт меню');
  menuItem.onClick(); // TypeScript знает о свойстве onClick
} else if (isDropdownMenuItem(menuItem)) {
  console.log('Это пункт с подменю');
  console.log('Элементов в подменю:', menuItem.items.length);
}

Полный пример надстройки с разными типами меню

export default {
  onInit: (editorApi) => {
    const menuItems: ContextMenuItem[] = [
      // Простой пункт меню
      {
        id: 'plugin:bold',
        title: 'Жирный',
        icon: 'Bold',
        shownInScopes: [{ scope: 'selection' }],
        onClick: editorApi.createCallback(async () => {
          const text = await editorApi.document.selection.getSelectionAsText();
          if (text) {
            await editorApi.document.insertContent(
              `<b>${text}</b>`,
              'html'
            );
          }
        })
      },

      // Выпадающее меню
      {
        id: 'plugin:transform',
        title: 'Трансформировать',
        icon: 'TextTransform',
        groupingId: 'plugin_text',
        items: [
          {
            id: 'plugin:uppercase',
            title: 'ВЕРХНИЙ РЕГИСТР',
            onClick: editorApi.createCallback(async () => {
              const text = await editorApi.document.selection.getSelectionAsText();
              if (text) {
                await editorApi.document.insertContent(text.toUpperCase());
              }
            })
          },
          {
            id: 'plugin:lowercase',
            title: 'нижний регистр',
            onClick: editorApi.createCallback(async () => {
              const text = await editorApi.document.selection.getSelectionAsText();
              if (text) {
                await editorApi.document.insertContent(text.toLowerCase());
              }
            })
          }
        ]
      },

      // Ещё простой пункт
      {
        id: 'plugin:about',
        title: 'О надстройке',
        groupingId: 'plugin_info',
        onClick: editorApi.createCallback(() => {
          editorApi.ui.toasts.showToast({ id, content: 'Версия надстройки: 1.0.0' });
        })
      }
    ];

    editorApi.ui.contextMenu.addItems(menuItems);
  },

  onDestroy: (editorApi) => {
    editorApi.ui.contextMenu.removeItems([
      'plugin:bold',
      'plugin:transform',
      'plugin:about'
    ]);
  }
}

Создание builder функции для удобного создания меню

function createSimpleMenuItem(
  id: string,
  title: string,
  onClick: () => void,
  icon?: string
): SimpleContextMenuItem {
  return {
    id,
    title,
    icon,
    onClick: editorApi.createCallback(onClick)
  };
}

function createDropdownMenuItem(
  id: string,
  title: string,
  items: ContextMenuItem[],
  icon?: string
): ContextMenuItemWithDropdown {
  return {
    id,
    title,
    icon,
    items
  };
}

const menuItems: ContextMenuItem[] = [
  createSimpleMenuItem(
    'plugin:action',
    'Мое действие',
    () => console.log('Действие'),
    'Star'
  ),
  createDropdownMenuItem(
    'plugin:menu',
    'Меню',
    [
      createSimpleMenuItem(
        'plugin:submenu-1',
        'Подменю 1',
        () => console.log('Подменю 1')
      )
    ],
    'Menu'
  )
];

See​