Interface: DocumentScope

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

Используется для динамического управления состоянием UI элементов (видимость, активность) в зависимости от того, где находится курсор пользователя и что выделено.

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

Remarks

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

• DocumentScope описывает текущее положение курсора/выделения в документе
• Используется в BaseContextMenuItem.shownInScopes и BaseContextMenuItem.disabledInScopes
• Позволяет условно показывать или отключать UI элементы
• Проверяется в real-time при движении курсора

Три уровня контекста:

1. mode — режим работы (курсор или выделение)
2. scope — прямой контекст (текст, таблица, изображение и т.д.)
3. parentScope — родительский контекст (где находится scope)

Типичная иерархия:

Документ
├─ Текст в документе (mode: cursor/selection, scope: text, parentScope: document)
├─ Таблица (parentScope: table)
│  └─ Ячейка таблицы (scope: text, parentScope: table-cell)
├─ Фигура (scope: shape, parentScope: shape)
│  └─ Текст в фигуре (scope: text, parentScope: shape)
├─ Гиперссылка (scope: hyperlink, parentScope: document)
├─ Изображение (scope: image, parentScope: document)
└─ Колонтитулы (parentScope: header-footer)

Практическое использование:

• Показать "Копировать" только когда есть выделение: shownInScopes: [{ mode: 'selection' }]
• Отключить "Трансформировать текст" в таблицах: disabledInScopes: [{ scope: 'table' }]
• Показать "Открыть ссылку" только над ссылками: shownInScopes: [{ scope: 'hyperlink' }]
• Деактивировать редактирование в защищённых колонтитулах: disabledInScopes: [{ parentScope: 'header-footer' }]

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

• Текстовые документы (Word)
• Электронные таблицы (Excel)
• Презентации (PowerPoint)

Example

Проверка текущего контекста

const currentContext: DocumentScope = {
  mode: 'selection',        // Есть выделение
  scope: 'text',            // Выделен текст
  parentScope: 'document'   // В основном документе
};

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

const menuItem: SimpleContextMenuItem = {
  id: 'plugin:copy',
  title: 'Копировать',
  shownInScopes: [
    { mode: 'selection' }  // Видимо только когда есть выделение
  ],
  onClick: editorApi.createCallback(async () => {
    await editorApi.document.clipboard.copy();
  })
};

See

• BaseContextMenuItem.shownInScopes — для условной видимости
• BaseContextMenuItem.disabledInScopes — для условного отключения

Properties

mode

readonly mode: "selection" | "cursor"

Режим позиционирования курсора в документе.

Определяет, активен ли курсор или текст выделен.

Remarks

Возможные значения:

Значение	Описание	Когда происходит
cursor	Курсор активен, выделения нет	Пользователь кликнул в документе и ничего не выделил
selection	Активно выделение текста	Пользователь выделил текст или элемент (Shift+Click, Drag)

Примеры:

• mode: 'cursor' — пользователь просто кликнул и ничего не выделил
• mode: 'selection' — пользователь выделил текст/объект

Практическое использование:

• Показывать "Копировать" только при mode: 'selection'
• Показывать "Вставить" при mode: 'cursor'
• Отключить "Удалить" при mode: 'cursor' (нечего удалять)

Example

Условие видимости по режиму

// Видимо только при выделении
shownInScopes: [{ mode: 'selection' }]

// Видимо только когда курсор без выделения
shownInScopes: [{ mode: 'cursor' }]

See

BaseContextMenuItem.shownInScopes — использование в условиях видимости

---

parentScope

readonly parentScope: "table" | "shape" | "document" | "header-footer" | "table-of-contents" | "table-cell"

Высокоуровневая структура, содержащая текущий контекст (scope).

Определяет, в какой "большой" контейнер вложен текущий элемент.

Remarks

Возможные значения:

Значение	Описание	Когда используется
document	Основное содержимое документа	Текст в основном тексте
header-footer	Колонтитулы (верхний/нижний)	Редактирование заголовков страниц
table-of-contents	Содержание документа	Редактирование оглавления
shape	Геометрическая фигура	Редактирование текста в фигуре
table	Таблица (целиком)	Выделена таблица целиком
table-cell	Ячейка таблицы	Редактирование текста в ячейке

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

Документ (parentScope: 'document')
├─ Текст (scope: 'text', parentScope: 'document')
├─ Таблица (parentScope: 'table')
│  └─ Ячейка (scope: 'text', parentScope: 'table-cell')
├─ Фигура (scope: 'shape', parentScope: 'shape')
│  └─ Текст в фигуре (scope: 'text', parentScope: 'shape')
├─ Гиперссылка (scope: 'hyperlink', parentScope: 'document')
├─ Изображение (scope: 'image', parentScope: 'document')
├─ Колонтитулы (parentScope: 'header-footer')
│  └─ Текст в колонтитуле (scope: 'text', parentScope: 'header-footer')
└─ Содержание (parentScope: 'table-of-contents')
   └─ Пункт оглавления (scope: 'hyperlink', parentScope: 'table-of-contents')

Практическое использование:

• Отключить редактирование в защищённых колонтитулах: disabledInScopes: [{ parentScope: 'header-footer' }]
• Показать "Вставить строку" только в таблицах: shownInScopes: [{ parentScope: 'table' }]
• Отключить некоторые операции в таблице: disabledInScopes: [{ parentScope: 'table' }]
• Показать "Редактировать фигуру" только в фигурах: shownInScopes: [{ parentScope: 'shape' }]

Комбинирование scope и parentScope:

// Только текст в основном документе (не в таблицах, не в фигурах)
shownInScopes: [{ scope: 'text', parentScope: 'document' }]

// Текст в таблицах
shownInScopes: [{ parentScope: 'table-cell' }]

// Текст в фигурах
shownInScopes: [{ parentScope: 'shape' }]

// Текст в колонтитулах
shownInScopes: [{ parentScope: 'header-footer' }]

Example

Условия видимости по родительскому контексту

// Видимо только в таблицах
shownInScopes: [{ parentScope: 'table' }]

// Видимо только в ячейках таблицы
shownInScopes: [{ parentScope: 'table-cell' }]

// Видимо только в фигурах
shownInScopes: [{ parentScope: 'shape' }]

// Видимо только в колонтитулах
shownInScopes: [{ parentScope: 'header-footer' }]

// Видимо только в оглавлении
shownInScopes: [{ parentScope: 'table-of-contents' }]

See

• scope — прямой контекст
• BaseContextMenuItem.shownInScopes — использование в условиях видимости

---

scope

readonly scope: "table" | "shape" | "image" | "text" | "hyperlink" | "mixed"

Прямой контекст нахождения курсора или выделения в структуре документа.

Определяет, над чем конкретно находится курсор или что выделено.

Remarks

Возможные значения:

Значение	Описание	Пример
text	Непосредственно в тексте	Курсор между букв "те
hyperlink	Над гиперссылкой	Курсор над ссылкой "[Ссылка]"
shape	Внутри геометрической фигуры	Редактирование текста в фигуре
image	Над изображением	Курсор над картинкой
table	В таблице	Выделена ячейка или вся таблица
mixed	Сложный случай	Выделено сразу несколько разных объектов

Примеры использования:

• Показать "Открыть ссылку" только при scope: 'hyperlink'
• Отключить "Трансформировать текст" при scope: 'table'
• Показать "Редактировать фигуру" при scope: 'shape'
• Показать "Вставить в таблицу" при scope: 'table'

Иерархия scope и parentScope:

scope: 'text', parentScope: 'document'     // Текст в основном документе
scope: 'text', parentScope: 'table-cell'   // Текст в ячейке таблицы
scope: 'text', parentScope: 'shape'        // Текст внутри фигуры
scope: 'hyperlink', parentScope: 'document' // Ссылка в основном документе
scope: 'image', parentScope: 'document'    // Изображение в документе

Example

Условия видимости по типу элемента

// Видимо только над текстом
shownInScopes: [{ scope: 'text' }]

// Видимо только над ссылками
shownInScopes: [{ scope: 'hyperlink' }]

// Видимо над таблицами
shownInScopes: [{ scope: 'table' }]

// Видимо над фигурами
shownInScopes: [{ scope: 'shape' }]

// Видимо над изображениями
shownInScopes: [{ scope: 'image' }]

See

• parentScope — родительский контекст
• BaseContextMenuItem.shownInScopes — использование в условиях видимости