Interface: CustomRibbonGroup

Интерфейс группы элементов на панели инструментов.

Группа — это логическая и визуальная организация кнопок и других элементов. Все элементы в группе располагаются горизонтально в одном ряду и отделяются от других групп вертикальной линией.

Remarks

Структура группы:

• id — уникальный идентификатор группы
• title — название группы (опционально, отображается под элементами)
• type — тип группы ('controls' — группа с кнопками и управлением)
• controls — массив элементов управления (кнопки, выпадающие меню и т.д.)

Рекомендации:

• Группируйте связанные функции вместе
• 3-5 элементов в группе — оптимально
• Используйте названия, отражающие назначение (Форматирование, Экспорт, Анализ)
• Разделяйте несвязанные функции в разные группы

Extends

• BaseUiElement.MayHaveTitle.MayHaveOrder.MayHaveIcon

Properties

controls

readonly controls: RibbonControl[]

Массив элементов управления в этой группе.

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

Remarks

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

• Button — простая кнопка с действием
• ButtonWithDropdown — кнопка с выпадающим меню

Рекомендации:

• Не более 5-7 элементов в группе
• Логически группируйте элементы
• Используйте иконки для быстрого распознавания

Example

controls: [
    {
        id: 'plugin:btn:action1',
        title: 'Действие 1',
        icon: 'Star',
        type: 'button',
        onClick: editorApi.createCallback(() => {})
    },
    {
        id: 'plugin:btn:action2',
        title: 'Действие 2',
        icon: 'Settings',
        type: 'button',
        onClick: editorApi.createCallback(() => {})
    }
]

See

• Button — простая кнопка
• ButtonWithDropdown — кнопка с меню

---

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',
        disabled: false,
    }
]);

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

Inherited from

BaseUiElement.id

---

order?

readonly optional order: number

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

Remarks

Правила сортировки:

• Элементы расположены по возрастанию значения order
• Контейнер автоматически переупорядочивает элементы при изменении order

Рекомендуемые значения:

• 10, 20, 30 — для встроенных элементов
• 15, 27, 28 — для пользовательских элементов

Примеры:

// На панели инструментов
{ id: 'tab:file', order: 10 }      // Слева
{ id: 'tab:edit', order: 20 }      // В середине
{ id: 'plugin:tab', order: 100 }   // Справа

Inherited from

HasOrder.order

---

title?

readonly optional title: string

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

Remarks

Требования:

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

Примеры:

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

Советы:

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

Example

{
    id: 'button:save',
    title: 'Сохранить',
    type: 'button'
}

Inherited from

HasTitle.title

---

type

readonly type: "controls"

Тип группы.

Определяет как интерпретируется содержимое группы. В текущей версии поддерживается только тип 'controls' для элементов управления.

Default

'controls'