Версия: 26.1.0

Interface: BaseContextMenuItem

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

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

Наследует функционал от BaseControl и MayHaveIcon для управления действиями и иконками.

Remarks

Иерархия интерфейсов:

BaseContextMenuItem (текущий интерфейс)
  ├── extends BaseControl — базовые свойства элемента управления
  │   ├── id: string
  │   ├── title: string
  │   ├── onClick: Callback
  │   └── ...
  └── extends MayHaveIcon — поддержка иконок
      └── icon?: string

Области видимости (scopes): Контекстное меню может отображаться по-разному в зависимости от контекста:

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

Использование shownInScopes vs disabledInScopes:

shownInScopes — пункт видимо ТОЛЬКО в указанных контекстах
disabledInScopes — пункт видимо, но отключен в указанных контекстах

Типичные сценарии:

Показать действие только когда есть выделение
Отключить действие при работе с таблицей
Показать разные действия для разных типов объектов

Example

Базовый элемент меню

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

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

const menuItem: BaseContextMenuItem = {
  id: 'plugin:text-action',
  title: 'Действие над текстом',
  shownInScopes: [
    { scope: 'text' },
    { scope: 'selection' }
  ],
  onClick: editorApi.createCallback(() => {})
};

See

BaseControl — базовые свойства элемента управления
MayHaveIcon — поддержка иконок
DocumentScope — описание всех доступных контекстов
ContextMenuApi — API управления контекстным меню

Extends

BaseControl.MayHaveIcon

Properties

disabledInScopes?

optional disabledInScopes: Partial<DocumentScope>[]

Список условий, при которых пункт меню будет отключен (серым цветом).

Пункт меню остаётся видимым, но становится неактивным и не кликабельным в указанных контекстах.

Remarks

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

Если disabledInScopes не указано, пункт активен ВСЕГДА (во всех контекстах)
Если disabledInScopes указано, пункт отключен если выполнен ИЛИ один из условий
Условия проверяются как ИЛИ (OR логика) — достаточно одного совпадения
Пункт остаётся видимым, но выглядит неактивным (серый цвет, no cursor)

Различие от shownInScopes:

shownInScopes — пункт совсем скрыт из меню (не видно)
disabledInScopes — пункт видимо, но отключен (серый, не кликабельный)

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

Когда нужно показать пункт, но он недоступен в некоторых контекстах
Когда нужно дать пользователю подсказку (пункт видимо, но "пока недоступен")
Когда нужна постоянная позиция в меню

Доступные свойства DocumentScope:

scope — текущий контекст (text, table, image, shape, selection, empty)
parentScope — родительский контекст
mode — режим документа (edit, view, review)
documentType — тип документа (text, spreadsheet, presentation)

Default

undefined (активен во всех контекстах)

Examples

Отключено в таблице

const menuItem: BaseContextMenuItem = {
  id: 'plugin:text-action',
  title: 'Действие с текстом',
  disabledInScopes: [
    { scope: 'table' },
    { parentScope: 'table' }
  ],
  onClick: editorApi.createCallback(async () => {
    const text = await editorApi.document.selection.getSelectionAsText();
    // действие с текстом
  })
};

Отключено в отсутствие выделенного текста

const menuItem: BaseContextMenuItem = {
  id: 'plugin:text-action',
  title: 'Действие с текстом',
  disabledInScopes: [
    { mode: 'selection' }
  ],
  onClick: editorApi.createCallback(async () => {
    const text = await editorApi.document.selection.getSelectionAsText();
    // действие с текстом
  })
};

See

DocumentScope — полное описание всех доступных контекстов
shownInScopes — для полного скрытия пункта в определённых контекстах

groupingId?

readonly optional groupingId: string

Идентификатор группы, к которой относится элемент.

Remarks

Поведение:

Элементы с одинаковым groupingId визуально группируются
Между группами (разные groupingId) отображается разделитель
Элементы без groupingId не группируются
Порядок групп определяется order первого элемента в группе

Example

[
  { id: 'copy', title: 'Copy', groupingId: 'clipboard' },
  { id: 'cut', title: 'Cut', groupingId: 'clipboard' },
  // Разделитель добавляется автоматически
  { id: 'paste', title: 'Paste', groupingId: 'clipboard' },
  // Разделитель добавляется автоматически
  { id: 'delete', title: 'Delete', groupingId: 'edit' }
]

Inherited from

BaseControl.groupingId

icon?

readonly optional icon: string

Название встроенной иконки или SVG код пользовательской иконки.

Remarks

Если iconType === 'standard':

Должно быть названием встроенной иконки редактора
Примеры: 'Save', 'Delete', 'Settings', 'Help', 'Search', 'Download', 'Upload'
Полный список доступных иконок см. в документации редактора
Название чувствительно к регистру

Если iconType === 'svg':

Должно содержать валидный SVG код
Должен быть корректно оформлен XML
Может содержать только безопасные SVG элементы
Рекомендуется использовать viewBox для масштабируемости

Examples

{
  icon: 'Save',
  iconType: 'standard'  // или не указывать, это значение по умолчанию
}

{
  icon: '<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">' +
        '<circle cx="12" cy="12" r="10" fill="currentColor"/>' +
        '</svg>',
  iconType: 'svg'
}

const customIconSvg = `
  <svg viewBox="0 0 24 24">
    <path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2z"
          fill="currentColor"/>
  </svg>
`;

{
  icon: customIconSvg,
  iconType: 'svg'
}

See

iconType — тип иконки (standard или svg)

Inherited from

HasIcon.icon

iconType?

readonly optional iconType: "standard" | "svg"

Тип иконки, определяющий как интерпретировать поле icon.

Remarks

'standard' — встроенная иконка редактора:

Быстрая загрузка (уже в памяти)
Соответствует стилю редактора
Автоматически масштабируется и окрашивается
Поддерживает темы (светлая/тёмная)
Ограниченный выбор (только встроенные иконки)

'svg' — пользовательская SVG иконка:

Полная гибкость в дизайне
Можно использовать любую иконку
Меньше файлов (встроены в код)
Требует корректного SVG кода
Поддерживает CSS свойство currentColor для окраски

Default

'standard'

Example

Встроенная иконка (по умолчанию)

{
  icon: 'Settings'
  // iconType: 'standard' используется по умолчанию
}

SVG иконка

{
  icon: '<svg>...</svg>',
  iconType: 'svg'
}

Рекомендуемая SVG структура

{
  icon: `
    <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
      <!-- viewBox позволяет масштабировать без потери качества -->
      <path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2z"
            fill="currentColor" />
      <!-- currentColor наследует цвет из контекста -->
    </svg>
  `,
  iconType: 'svg'
}

See

icon — содержимое иконки

Inherited from

HasIcon.iconType

id

readonly id: string

Уникальный идентификатор элемента пользовательского интерфейса.

Remarks

Требования:

Должен быть уникален среди всех элементов UI редактора
Не может быть пустой строкой
Не может содержать спецсимволы (кроме :, -, _)
Чувствителен к регистру (case-sensitive)

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

Идентификация элемента при обновлении
Идентификация элемента при событиях
Ссылка на элемент в других местах кода

Соглашения:

'plugin:button:save'          // Кнопка надстройки
'plugin:input:username'       // Поле ввода
'plugin:panel:settings'       // Панель параметров
'plugin:group:formatting'     // Группа элементов

Example

// Создание элемента с уникальным id
{
  id: 'plugin:button:submit',
  title: 'Отправить',
  type: 'button'
}

// Использование id для обновления
editorApi.ui.updateUiNodes([
  {
    id: 'plugin:button:submit',
    updates: { disabled: false }
  }
]);

// Использование id для удаления
editorApi.ui.ribbon.removeTabs(['plugin:ribbon:tab']);

Inherited from

BaseControl.id

shownInScopes?

readonly optional shownInScopes: Partial<DocumentScope>[]

Список условий, при которых пункт меню будет видимым и активным.

Позволяет отображать пункт меню только в определённых контекстах (например, только над текстом или только в выделении).

Remarks

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

Если shownInScopes не указано, пункт видимо ВСЕГДА (во всех контекстах)
Если shownInScopes указано, пункт видимо ТОЛЬКО если выполнен ИЛИ один из условий
Условия проверяются как ИЛИ (OR логика) — достаточно одного совпадения

Доступные свойства DocumentScope:

scope — текущий контекст (text, table, image, shape, selection, empty)
parentScope — родительский контекст (например, ячейка в таблице имеет parentScope='table')
mode — режим работы документа (edit, view, review)
documentType — тип документа (text, spreadsheet, presentation)

Типичные условия:

{ scope: 'selection' } — только когда есть выделение
{ scope: 'text' } — только над текстом
{ scope: 'table', parentScope: 'table' } — только в таблице
{ mode: 'edit' } — только в режиме редактирования
{ documentType: 'text' } — только в текстовых документах

Сравнение со стандартным режимом:

Без shownInScopes:
├─ text: видимо ✓
├─ table: видимо ✓
├─ image: видимо ✓
└─ empty: видимо ✓

С shownInScopes: [{ scope: 'text' }, { scope: 'selection' }]:
├─ text: видимо ✓
├─ selection: видимо ✓
├─ table: скрыто ✗
├─ image: скрыто ✗
└─ empty: скрыто ✗

Default

undefined (видимо во всех контекстах)

Example

Видимо только при наличии выделения

const menuItem: BaseContextMenuItem = {
  id: 'plugin:copy-selected',
  title: 'Копировать выделение',
  shownInScopes: [
    { scope: 'selection' }
  ],
  onClick: editorApi.createCallback(async () => {
    await editorApi.document.clipboard.copy();
  })
};

Видимо только над текстом

const menuItem: BaseContextMenuItem = {
  id: 'plugin:text-transform',
  title: 'Трансформировать текст',
  shownInScopes: [
    { scope: 'text' }
  ],
  onClick: editorApi.createCallback(async () => {
    const text = await editorApi.document.selection.getSelectionAsText();
    // трансформация
  })
};

Видимо в таблицах и над фигурами

const menuItem: BaseContextMenuItem = {
  id: 'plugin:edit-object',
  title: 'Редактировать объект',
  shownInScopes: [
    { scope: 'table' },
    { parentScope: 'table' },
    { scope: 'shape' }
  ],
  onClick: editorApi.createCallback(() => {})
};

Видимо только в режиме редактирования

const menuItem: BaseContextMenuItem = {
  id: 'plugin:edit-only',
  title: 'Редактировать',
  shownInScopes: [
    { mode: 'edit' }
  ],
  onClick: editorApi.createCallback(() => {})
};

Видимо только в текстовых документах

const menuItem: BaseContextMenuItem = {
  id: 'plugin:text-doc-action',
  title: 'Действие для текстовых документов',
  shownInScopes: [
    { documentType: 'text' }
  ],
  onClick: editorApi.createCallback(() => {})
};

See

DocumentScope — полное описание всех доступных контекстов
disabledInScopes — для отключения пункта в определённых контекстах

title

readonly title: string

Название/заголовок элемента пользовательского интерфейса.

Remarks

Требования:

Должен быть локализирован (переведён на язык пользователя)
Должен быть понятным и кратким
Не должен быть пустой строкой
Может содержать спецсимволы (кроме < и >)

Примеры:

"Сохранить документ"
"Экспортировать в PDF"
"Параметры надстройки"
"Об приложении"

Советы:

Используйте глаголы для действий (Сохранить, Удалить)
Используйте существительные для панелей (Параметры, Информация)
Сохраняйте названия короткими
Будьте конкретными (не просто "Опции", а "Параметры надстройки")

Example

{
  id: 'button:save',
  title: 'Сохранить',        // Локализирован
  type: 'button'
}

Inherited from

BaseControl.title

Remarks​

Example​

See​

Extends​

Properties​

disabledInScopes?​

Remarks​

Default​

Examples​

See​

groupingId?​

Remarks​

Example​

Inherited from​

icon?​

Remarks​

Examples​

See​

Inherited from​

iconType?​

Remarks​

Default​

Example​

See​

Inherited from​

id​

Remarks​

Example​

Inherited from​

shownInScopes?​

Remarks​

Default​

Example​

See​

title​

Remarks​

Example​

Inherited from​

Remarks

Example

See

Extends

Properties

disabledInScopes?

Remarks

Default

Examples

See

groupingId?

Remarks

Example

Inherited from

icon?

Remarks

Examples

See

Inherited from

iconType?

Remarks

Default

Example

See

Inherited from

id

Remarks

Example

Inherited from

shownInScopes?

Remarks

Default

Example

See

title

Remarks

Example

Inherited from