Interface: RibbonApi

API для управления верхней панелью инструментов.

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

Возможности:

• Создание полностью независимых вкладок с собственным содержимым
• Добавление групп в предопределённую вкладку "Надстройки"
• Получение списка всех вкладок для анализа состояния
• Удаление добавленных вкладок и групп

Структура панели инструментов:

┌────────────────────────────────────────────────────────────┐
│ Вкладка 1  │ Вкладка 2  │ Ваша вкладка  │ Вкладка 3        │
├────────────────────────────────────────────────────────────┤
│ [Группа 1] | [Группа 2] | [Группа 3]                       │
│ Кнопка   │ Кнопка   │ Кнопка │ Кнопка с меню               │
│ Кнопка   │ Кнопка   │ Кнопка │ Кнопка                      │
└────────────────────────────────────────────────────────────┘

Methods

addPluginTabGroups()

addPluginTabGroups(groups): Promise<void>

Добавляет группы элементов в предопределённую вкладку "Надстройки".

Если вкладка "Надстройки" не была ещё создана, она будет создана автоматически. Если вкладка уже существует, новые группы добавляются в неё.

Полная информация о группах передаётся в объекте параметров. Каждая группа содержит id, название и массив элементов управления.

Parameters

groups

CustomRibbonGroup[]

Массив групп для добавления в вкладку "Надстройки" (тип CustomRibbonGroup[])

Returns

Promise<void>

Remarks

Использование вкладки "Надстройки":

• Автоматическая вкладка для всех надстроек
• Удобно, если вы не хотите создавать отдельную вкладку
• Несколько надстроек могут добавлять группы в одну вкладку

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

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

Example

Добавление группы в вкладку "Надстройки"

editorApi.ui.ribbon.addPluginTabGroups([
    {
        id: 'plugin:group:analyze',
        type: 'controls',
        title: 'Анализ',
        controls: [
            {
                id: 'plugin:btn:analyze',
                title: 'Анализировать текст',
                icon: 'Search',
                type: 'button',
                onClick: editorApi.createCallback(async () => {
                    const content = await editorApi.document.getContent?.();
                    editorApi.ui.toasts.showToast({ id, content: 'Анализ выполнен' });
                })
            }
        ]
    }
]);

Добавление нескольких групп

editorApi.ui.ribbon.addPluginTabGroups([
    {
        id: 'plugin:group:text-tools',
        type: 'controls',
        title: 'Текст',
        controls: [ ..кнопки ]
    },
    {
        id: 'plugin:group:export-tools',
        type: 'controls',
        title: 'Экспорт',
        controls: [ ..кнопки  ]
    }
]);

See

• addTab — для создания отдельной вкладки
• CustomRibbonGroup — структура группы

---

addTab()

addTab(tab): void

Регистрирует новую пользовательскую вкладку в панели инструментов.

Вкладка содержит одну или несколько групп элементов (кнопки, выпадающие меню и т.д.). Все элементы в группе располагаются горизонтально в одном ряду.

Полная информация передаётся в объекте параметров:

• id — уникальный идентификатор вкладки (обычно префикс надстройки + 'ribbon:tab')
• title — название вкладки (отображается на вкладке)
• order — позиция среди других вкладок (меньше = левее)
• groups — массив групп с элементами управления

Parameters

tab

CustomRibbonTabInfo

Полное описание вкладки (тип CustomRibbonTabInfo)

Returns

void

Remarks

Расположение вкладок:

• order используется для позиционирования вкладки
• Вкладки сортируются слева направо по значению order
• Встроенные вкладки имеют фиксированные значения order

Организация элементов:

• Группы разделяются вертикальными линиями
• Элементы в группе располагаются в горизонтальный ряд
• Рекомендуется 3-5 элементов в группе для удобства

Example

Простая вкладка с одной кнопкой

editorApi.ui.ribbon.addTab({
    id: 'plugin:ribbon:tab',
    title: 'Моя надстройка',
    order: 25,
    groups: [
        {
            id: 'plugin:group:main',
            type: 'controls',
            controls: [
                {
                    id: 'plugin:button:about',
                    title: 'О программе',
                    icon: 'Help',
                    type: 'button',
                    onClick: editorApi.createCallback(() => {
                        editorApi.ui.toasts.showToast({ id, content: 'Версия 1.0' });
                    })
                }
            ]
        }
    ]
});

Вкладка с несколькими группами

editorApi.ui.ribbon.addTab({
    id: 'plugin:ribbon:tab',
    title: 'Текст',
    order: 30,
    groups: [
        {
            id: 'plugin:group:format',
            type: 'controls',
            title: 'Форматирование',
            controls: [
                {
                    id: 'plugin:btn:bold',
                    title: 'Жирный',
                    icon: 'Bold',
                    type: 'button',
                    onClick: editorApi.createCallback(() => { // ваш код  })
                },
                {
                    id: 'plugin:btn:italic',
                    title: 'Курсив',
                    icon: 'Italic',
                    type: 'button',
                    onClick: editorApi.createCallback(() => { // ваш код  })
                }
            ]
        },
        {
            id: 'plugin:group:export',
            type: 'controls',
            title: 'Экспорт',
            controls: [
                {
                    id: 'plugin:btn:export',
                    title: 'Экспортировать',
                    icon: 'Download',
                    type: 'button-with-dropdown',
                    items: [
                        {
                            id: 'plugin:export:pdf',
                            title: 'PDF',
                            type: 'button',
                            onClick: editorApi.createCallback(() => { // ваш код  })
                        }
                    ]
                }
            ]
        }
    ]
});

See

• CustomRibbonTabInfo — структура параметров вкладки
• CustomRibbonGroup — структура группы элементов
• Button — простая кнопка
• ButtonWithDropdown — кнопка с выпадающим меню

---

removePluginTabGroups()

removePluginTabGroups(groups): Promise<void>

Удаляет группы элементов из предопределённой вкладки "Надстройки".

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

Parameters

groups

string[]

Массив идентификаторов групп для удаления

Returns

Promise<void>

Remarks

Поведение:

• Группы удаляются из вкладки "Надстройки"
• Если это последняя группа, вкладка скрывается (но не удаляется)
• Группы других надстроек не затрагиваются

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

• Очистка при деактивации надстройки (в onDestroy)
• Удаление временных групп
• Переинициализация UI надстройки

Example

Удаление одной группы

editorApi.ui.ribbon.removePluginTabGroups(['plugin:group:main']);

Удаление нескольких групп

editorApi.ui.ribbon.removePluginTabGroups([
  'plugin:group:text',
  'plugin:group:export'
]);

See

• addPluginTabGroups — для добавления групп в "Надстройки"
• removeTabs — для удаления пользовательской вкладки

---

removeTabs()

removeTabs(tabs): void

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

Вкладка удаляется полностью со всеми содержащимися группами и элементами.

Parameters

tabs

string[]

Массив идентификаторов вкладок для удаления

Returns

void

Remarks

Ограничения:

• Можно удалять только вкладки, созданные через addTab
• Встроенные вкладки редактора удалить нельзя
• Вкладку "Надстройки" удалить нельзя (используйте removePluginTabGroups)

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

• Очистка при деактивации надстройки (в onDestroy)
• Удаление временных вкладок
• Переинициализация UI надстройки

Example

Удаление одной вкладки

editorApi.ui.ribbon.removeTabs(['plugin:ribbon:tab']);

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

editorApi.ui.ribbon.removeTabs([
    'plugin:ribbon:tab-1',
    'plugin:ribbon:tab-2',
    'plugin:ribbon:tab-3'
]);

See

• addTab — для создания вкладки
• removePluginTabGroups — для удаления групп из вкладки "Надстройки"