Версия: Next

Interface: ButtonWithDropdownUpdate

Интерфейс для обновления свойств кнопки с выпадающим меню (ButtonWithDropdown).

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

Remarks

Можно обновлять:

title — название основной кнопки
icon — иконка основной кнопки
disabled — доступность основной кнопки
items — массив элементов в выпадающем меню (полная замена)

Важно о вложенных элементах (items): Есть два способа обновления элементов выпадающего списка:

Полная замена всего списка — передайте новый массив items
- Все старые элементы будут заменены новыми
- Используйте когда радикально меняется содержимое меню
Обновление отдельных элементов — обновите каждый элемент по его id
- Родительская кнопка не меняется
- Сам список items не меняется
- Используйте для частичных обновлений

Example

Полная замена меню

editorApi.ui.updateUiNodes([
    {
        id: 'plugin:dropdown:export',
        title: 'Экспортировать в',
        items: [  // Полная замена всех элементов
          {
              id: 'export:pdf',
              title: 'PDF (новый)',
              type: 'button',
              onClick: editorApi.createCallback(() => {})
          },
          {
              id: 'export:docx',
              title: 'Word (новый)',
              type: 'button',
              onClick: editorApi.createCallback(() => {})
          }
        ]
    }
]);

Обновление отдельных элементов меню

// Обновляем элементы 'export:pdf' и 'export:docx'
editorApi.ui.updateUiNodes([
    {
        id: 'export:pdf',
        disabled: true,
        icon: 'Warning',
        title: 'PDF (недоступен)'
    },
    {
        id: 'export:docx',
        disabled: false,
        title: 'Word (доступен)'
    }
]);

Отключение основной кнопки, но не меню

editorApi.ui.updateUiNodes([
    {
        id: 'plugin:dropdown:export',
        disabled: true  // Отключаем кнопку, но меню остаётся с теми же элементами
    }
]);

See

ButtonWithDropdown — структура кнопки с меню
EditorUiApi.updateUiNodes — метод для применения обновлений

Properties

checked?

readonly optional checked: boolean

Состояние компонента: включено (true) или выключено (false).

Remarks

true — компонент в состоянии "включено":

Галочка в флажке
Переключатель в "ВКЛ" позиции
Радиокнопка заполнена
Визуально выглядит активным

false — компонент в состоянии "выключено":

Флажок пуст
Переключатель в "ВЫКЛ" позиции
Радиокнопка не заполнена
Визуально выглядит неактивным

undefined — состояние не определено:

Используется редко
Может означать неопределённое состояние (не да, не нет)

Example

Флажок (checkbox)

{
    id: 'checkbox:confirm',
    type: 'checkbox',
    title: 'Я согласен с условиями',
    checked: false  // Изначально не отмечено
}

Переключатель (toggle)

{
    id: 'toggle:darkmode',
    type: 'toggle',
    title: 'Тёмный режим',
    checked: true  // Изначально включено
}

Обновление состояния

editorApi.ui.updateUiNodes([{
    id: 'checkbox:confirm',
    checked: true  // Отметить флажок
}]);

disabled?

readonly optional disabled: boolean

Флаг отключения элемента.

Remarks

true — элемент отключен:

Визуально затемнен/затенён
События клика/ввода игнорируются
Подсказка может объяснить причину отключения
Фокус не может перейти на отключённый элемент

false или не указано — элемент включен:

Элемент активен и реагирует на действия
Полная интерактивность
Нормальный визуальный вид

Default

false (включено)

Example

Отключение кнопки во время загрузки

// Начало загрузки
editorApi.ui.updateUiNodes([{
    id: 'button:submit',
    disabled: true,
    title: 'Загрузка...'
}]);

// После загрузки
editorApi.ui.updateUiNodes([{
    id: 'button:submit',
    disabled: false,
    title: 'Отправить'
}]);

Отключение поля ввода в зависимости от условия

editorApi.events.subscribe('documentChange', (payload) => {
    const isEmpty = payload.info.content.length === 0;

    editorApi.ui.updateUiNodes([{
        id: 'input:search',
        disabled: isEmpty  // Отключить если документ пуст
    }]);
});

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' }
]

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)

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 — содержимое иконки

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']);

items?

readonly optional items: Button[]

Массив кнопок, отображаемых в выпадающем меню.

Содержит список элементов Button, которые будут доступны при открытии выпадающего меню.

Remarks

Характеристики items:

Минимум 1 кнопка в массиве
Максимум рекомендуется 5-7 кнопок (для удобства)
Все элементы должны быть типа Button
Кнопки отображаются в том же порядке, что в массиве
Каждая кнопка должна иметь свой onClick
Кнопки могут быть отключены через disabled

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

Первая кнопка — наиболее типичный выбор
Группируйте похожие действия рядом
Используйте понятные названия и иконки
Если много действий, подумайте о подменю

Структура Button в items:

id — уникальный идентификатор
title — текст кнопки
type: 'button' — обязательно 'button'
onClick — обработчик события
icon (опционально) — иконка
disabled (опционально) — отключение кнопки

Example

Простой выпадающий список

const dropdown: ButtonWithDropdown = {
    id: 'plugin:format',
    title: 'Format',
    icon: 'Palette',
    type: 'button-with-dropdown',
    items: [
        {
            id: 'plugin:format-bold',
            title: 'Bold',
            type: 'button',
            onClick: editorApi.createCallback(() => {})
        },
        {
            id: 'plugin:format-italic',
            title: 'Italic',
            type: 'button',
            onClick: editorApi.createCallback(() => {})
        },
        {
            id: 'plugin:format-underline',
            title: 'Underline',
            type: 'button',
            onClick: editorApi.createCallback(() => {})
        }
    ]
};

Выпадающий список с иконками

const dropdown: ButtonWithDropdown = {
    id: 'plugin:align',
    title: 'Align',
    icon: 'AlignLeft',
    type: 'button-with-dropdown',
    items: [
        {
            id: 'plugin:align-left',
            title: 'Align Left',
            icon: 'AlignLeft',
            type: 'button',
            onClick: editorApi.createCallback(() => {})
        },
        {
            id: 'plugin:align-center',
            title: 'Align Center',
            icon: 'AlignCenter',
            type: 'button',
            onClick: editorApi.createCallback(() => {})
        },
        {
            id: 'plugin:align-right',
            title: 'Align Right',
            icon: 'AlignRight',
            type: 'button',
            onClick: editorApi.createCallback(() => {})
        }
    ]
};

Выпадающий список с некоторыми отключенными кнопками

const dropdown: ButtonWithDropdown = {
    id: 'plugin:options',
    title: 'Options',
    icon: 'Settings',
    type: 'button-with-dropdown',
    items: [
        {
            id: 'plugin:option-1',
            title: 'Option 1',
            type: 'button',
            onClick: editorApi.createCallback(() => {})
        },
        {
            id: 'plugin:option-2',
            title: 'Option 2',
            type: 'button',
            disabled: true,  // Отключена - недоступна
            onClick: editorApi.createCallback(() => {})
        },
        {
            id: 'plugin:option-3',
            title: 'Option 3',
            type: 'button',
            onClick: editorApi.createCallback(() => {})
        }
    ]
};

See

Button — простые кнопки в меню
Callback — для обработчиков в кнопках

onClick?

readonly optional onClick: Callback

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

Опциональный обработчик, который определяет поведение при клике на основную кнопку.

Remarks

Режимы работы:

1. Без onClick (только выпадающее меню):

Клик на кнопку открывает/закрывает выпадающее меню
Клик на стрелку также открывает/закрывает меню
Нет дополнительного действия при клике на основную область
Используется для простого выбора из списка

2. С onClick (двухфункциональная кнопка):

Клик на основную часть выполняет onClick
Клик на стрелку открывает/закрывает меню
Кнопка имеет две разные функции
Используется когда есть основное действие + варианты

Поведение:

Если не указан, кнопка работает только как меню
При клике на основную область выполняется onClick (если указан)
При клике на стрелку открывается меню независимо от onClick
Обработчик может быть синхронным или асинхронным

Default

undefined (режим: только меню)

Example

Только выпадающее меню (без onClick)

const dropdown: ButtonWithDropdown = {
    id: 'plugin:export',
    title: 'Export',
    icon: 'Download',
    type: 'button-with-dropdown',
    // onClick не указан - кнопка только открывает меню
    items: [
        {
          id: 'plugin:export-pdf',
          title: 'PDF',
          type: 'button',
          onClick: editorApi.createCallback(() => {})
        }
    ]
};

Двухфункциональная кнопка (с onClick)

const dropdown: ButtonWithDropdown = {
    id: 'plugin:paste',
    title: 'Paste',
    icon: 'Paste',
    type: 'button-with-dropdown',
    // onClick указан - клик на кнопку вставляет, клик на стрелку открывает варианты
    onClick: editorApi.createCallback(async () => {
        await editorApi.document.clipboard.paste();
    }),
    items: [
        {
            id: 'plugin:paste-special',
            title: 'Paste Special',
            type: 'button',
            onClick: editorApi.createCallback(async () => {
                // специальная вставка
            })
        }
    ]
};

Асинхронный onClick

const dropdown: ButtonWithDropdown = {
    id: 'plugin:save',
    title: 'Save',
    icon: 'Save',
    type: 'button-with-dropdown',
    onClick: editorApi.createCallback(async () => {
        editorApi.ui.toasts.showToast({ id, content: 'Saving...' });
        await saveDocument();
        editorApi.ui.toasts.showToast({ id, content: 'Saved' });
    }),
    items: [
        {
            id: 'plugin:save-as',
            title: 'Save As...',
            type: 'button',
            onClick: editorApi.createCallback(() => {})
        }
    ]
};

See

Callback — полное описание интерфейса Callback
EditorApi.createCallback — как создать callback

title?

readonly optional title: string

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

Remarks

Требования:

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

Примеры:

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

Советы:

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

Example

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

type?

readonly optional type: "button-with-dropdown"

Маркер типа элемента управления.

Используется для идентификации элемента как кнопки с выпадающим меню в контейнере.

Remarks

Всегда равен 'button-with-dropdown' для этого интерфейса
Используется контейнерами для определения типа элемента
Позволяет TypeScript правильно типизировать элемент

Default

'button-with-dropdown'

Example

const dropdown: ButtonWithDropdown = {
    id: 'plugin:dropdown',
    title: 'Действие',
    icon: 'Menu',
    type: 'button-with-dropdown',  // Маркер типа
    items: []
};

Remarks​

Example​

See​

Properties​

checked?​

Remarks​

Example​

disabled?​

Remarks​

Default​

Example​

groupingId?​

Remarks​

Example​

icon?​

Remarks​

Examples​

See​

iconType?​

Remarks​

Default​

Example​

See​

id​

Remarks​

Example​

items?​

Remarks​

Example​

See​

onClick?​

Remarks​

Default​

Example​

See​

title?​

Remarks​

Example​

type?​

Remarks​

Default​

Example​

Remarks

Example

See

Properties

checked?

Remarks

Example

disabled?

Remarks

Default

Example

groupingId?

Remarks

Example

icon?

Remarks

Examples

See

iconType?

Remarks

Default

Example

See

id

Remarks

Example

items?

Remarks

Example

See

onClick?

Remarks

Default

Example

See

title?

Remarks

Example

type?

Remarks

Default

Example