Версия: 26.1.0 (в разработке)

Interface: ButtonUpdate

Интерфейс для обновления свойств кнопки (Button).

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

Remarks

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

title — название кнопки
icon — иконка кнопки
disabled — доступность (включена/отключена)
onClick — обработчик события нажатия
tooltip — подсказка при наведении (если поддерживается)

Не можно изменять:

id — идентификатор элемента (уникален)
type — тип элемента (всегда 'button')

Особенности:

Все свойства опциональны — обновляются только переданные
Непереданные свойства остаются без изменений
Обновление срабатывает немедленно

Example

Обновление названия и иконки

editorApi.ui.updateUiNodes([
  {
    id: 'plugin:button:save',
    updates: {
      title: 'Сохранить изменения',
      icon: 'Check'
    }
  }
]);

Отключение кнопки

editorApi.ui.updateUiNodes([
  {
    id: 'plugin:button:submit',
    updates: {
      disabled: true,
      title: 'Заполните все поля'  // Подскажем пользователю
    }
  }
]);

Обновление обработчика события

editorApi.ui.updateUiNodes([
  {
    id: 'plugin:button:action',
    updates: {
      onClick: editorApi.createCallback(() => {
        // новая логика
      })
    }
  }
]);

See

Button — структура кнопки
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',
  updates: {
    checked: true  // Отметить флажок
  }
}]);

disabled?

readonly optional disabled: boolean

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

Remarks

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

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

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

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

Default

false (включено)

Example

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

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

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

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

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

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

fullWidth?

readonly optional fullWidth: boolean

Флаг растягивания кнопки на всю ширину контейнера.

Если установлено в true, кнопка займёт всю доступную ширину своего контейнера.

Remarks

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

Для главных действий в диалогах (OK, Apply, Submit)
В узких боковых панелях для лучшей видимости
Когда нужно выделить кнопку среди других элементов

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

В ленте инструментов (обычно игнорируется)
Когда несколько кнопок в ряду (нужно согласовать размеры)
Для вспомогательных кнопок

Контейнер может игнорировать:

Некоторые контейнеры (лента, сетка) могут игнорировать fullWidth
Это зависит от реализации контейнера

Default

false

Example

Полная ширина для главного действия

const submitButton: Button = {
  id: 'plugin:submit',
  title: 'Отправить',
  type: 'button',
  variant: 'primary',
  fullWidth: true,  // Занимает всю ширину
  onClick: editorApi.createCallback(() => {
    // отправка
  })
};

Диалог с кнопками на всю ширину

const dialogButtons: Button[] = [
  {
    id: 'plugin:ok',
    title: 'OK',
    type: 'button',
    variant: 'primary',
    fullWidth: true,
    onClick: editorApi.createCallback(() => {})
  },
  {
    id: 'plugin:cancel',
    title: 'Отмена',
    type: 'button',
    fullWidth: true,
    onClick: editorApi.createCallback(() => {})
  }
];

Комбинация с другими свойствами

const actionButton: Button = {
  id: 'plugin:apply',
  title: 'Применить',
  type: 'button',
  variant: 'primary',
  fullWidth: true,
  icon: 'CheckMark',
  onClick: editorApi.createCallback(async () => {
    // применение действия
  })
};

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

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

onClick?

readonly optional onClick: Callback

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

Remarks

Как создать onClick:

const onClick = editorApi.createCallback(() => {
  // Ваша логика здесь
});

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

Обязательное свойство для кнопки
Создаётся через editorApi.createCallback()
Может быть синхронным или асинхронным (Promise)
Вызывается в контексте редактора
Имеет доступ к editorApi через замыкание

Когда вызывается:

При клике левой кнопкой мыши на кнопку
При нажатии Enter когда кнопка в фокусе
На мобильных устройствах: при tap на кнопку

Обработка ошибок:

Используйте try-catch для асинхронных операций
Показывайте ошибки пользователю через editorApi.ui.toasts.showToast({ type: 'error' })

Example

Синхронный обработчик

const button: Button = {
  id: 'plugin:action',
  title: 'Действие',
  type: 'button',
  onClick: editorApi.createCallback(() => {
    console.log('Кнопка нажата');
    editorApi.ui.toasts.showToast({ id, content: 'Готово' });
  })
};

Асинхронный обработчик

const button: Button = {
  id: 'plugin:load-data',
  title: 'Загрузить',
  type: 'button',
  onClick: editorApi.createCallback(async () => {
    editorApi.ui.toasts.showToast({ id, content: 'Загрузка...' });
    const data = await fetchData();
    await editorApi.document.insertContent(JSON.stringify(data));
    editorApi.ui.toasts.showToast({ id, content: 'Загружено' });
  })
};

Обработчик с проверками

const button: Button = {
  id: 'plugin:copy',
  title: 'Копировать',
  type: 'button',
  onClick: editorApi.createCallback(async () => {
    try {
      const text = await editorApi.document.selection.getSelectionAsText();

      if (!text) {
        editorApi.ui.toasts.showToast({ id, content: 'Пожалуйста, выделите текст' });
        return;
      }

      await editorApi.document.clipboard.copy();
      editorApi.ui.toasts.showToast({ id, content: 'Скопировано' });
    } catch (error) {
      editorApi.ui.toasts.showToast({ id, type: 'error', content: 'Ошибка при копировании' });
    }
  })
};

See

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

onlyIcon?

readonly optional onlyIcon: boolean

Флаг отображения только иконки без текста названия.

Если установлено в true, кнопка отображается только как иконка, название (title) будет использовано как tooltip при наведении.

Remarks

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

В плотных UI (панели инструментов, боковые панели)
Для экономии места при множестве кнопок
Когда иконка достаточно понятна без текста

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

Для новых или неочевидных операций
Когда нужно видеть текст
Для кнопок в диалогах (там лучше видеть текст)

Требования:

Кнопка должна иметь icon для отображения
title всё ещё должен быть понятным (используется как tooltip)

Контейнер может игнорировать:

Некоторые контейнеры могут показывать текст несмотря на onlyIcon: true
Это зависит от реализации контейнера

Default

false

Example

Кнопка только с иконкой (компактная)

const saveButton: Button = {
  id: 'plugin:save',
  title: 'Сохранить',  // Используется как tooltip
  icon: 'Save',
  type: 'button',
  onlyIcon: true,
  onClick: editorApi.createCallback(async () => {
    // сохранение
  })
};

Кнопка с иконкой и текстом (обычная)

const saveButton: Button = {
  id: 'plugin:save',
  title: 'Сохранить',
  icon: 'Save',
  type: 'button',
  onlyIcon: false,  // Или не указывать (default)
  onClick: editorApi.createCallback(async () => {
    // сохранение
  })
};

Компактная лента с кнопками только иконок

const toolbarButtons: Button[] = [
  {
    id: 'plugin:save',
    title: 'Сохранить',
    icon: 'Save',
    type: 'button',
    onlyIcon: true,
    onClick: editorApi.createCallback(() => {})
  },
  {
    id: 'plugin:copy',
    title: 'Копировать',
    icon: 'Copy',
    type: 'button',
    onlyIcon: true,
    onClick: editorApi.createCallback(() => {})
  }
];

title?

readonly optional title: string

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

Remarks

Требования:

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

Примеры:

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

Советы:

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

Example

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

type?

readonly optional type: "button"

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

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

Remarks

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

Default

'button'

Example

const button: Button = {
  id: 'plugin:action',
  title: 'Действие',
  type: 'button',  // Маркер типа
  onClick: editorApi.createCallback(() => {})
};

variant?

readonly optional variant: "link" | "primary" | "secondary"

Внешний вид (стиль) кнопки.

Влияет на визуальное представление и выделение кнопки, однако контейнер может переопределить стиль в зависимости от своих требований.

Remarks

Возможные варианты:

Вариант	Описание	Когда использовать
`primary`	Основная кнопка, выделена визуально (обычно соответствует теме текущего редактора)	Главное действие (Сохранить, Отправить, Применить)
`secondary`	Обычная кнопка, нейтральный стиль (используется по умолчанию)	Обычные действия (Копировать, Вставить, Удалить)
`link`	Представление в виде гиперссылки (синий текст с подчеркиванием)	Вспомогательные действия (Помощь, Подробнее, Отмена)

Влияние контейнера:

Лента инструментов может игнорировать variant и использовать свой стиль
Модальные окна часто переопределяют variant кнопок (OK/Cancel)
Боковые панели обычно соблюдают variant

Визуальные примеры:

primary:    ███ Сохранить ███  (выделенная, контрастная)
secondary:  ░░░ Копировать ░░░  (обычная, нейтральная)
link:       Помощь (синий текст, как ссылка)

Default

'secondary'

Example

Основная кнопка для важного действия

const submitButton: Button = {
  id: 'plugin:submit',
  title: 'Отправить',
  type: 'button',
  variant: 'primary',
  onClick: editorApi.createCallback(() => {
    // отправка данных
  })
};

Ссылка-кнопка для вспомогательного действия

const helpButton: Button = {
  id: 'plugin:help',
  title: 'Нужна помощь?',
  type: 'button',
  variant: 'link',
  onClick: editorApi.createCallback(() => {
    window.open('https://help.example.com');
  })
};

Кнопки в диалоге (разные варианты)

const okButton: Button = {
  id: 'plugin:ok',
  title: 'OK',
  type: 'button',
  variant: 'primary',  // Главное действие
  onClick: editorApi.createCallback(() => {})
};

const cancelButton: Button = {
  id: 'plugin:cancel',
  title: 'Отмена',
  type: 'button',
  variant: 'secondary',  // Вспомогательное действие
  onClick: editorApi.createCallback(() => {})
};

Remarks​

Example​

See​

Properties​

checked?​

Remarks​

Example​

disabled?​

Remarks​

Default​

Example​

fullWidth?​

Remarks​

Default​

Example​

groupingId?​

Remarks​

Example​

icon?​

Remarks​

Examples​

See​

iconType?​

Remarks​

Default​

Example​

See​

id​

Remarks​

Example​

onClick?​

Remarks​

Example​

See​

onlyIcon?​

Remarks​

Default​

Example​

title?​

Remarks​

Example​

type?​

Remarks​

Default​

Example​

variant?​

Remarks​

Default​

Example​

Remarks

Example

See

Properties

checked?

Remarks

Example

disabled?

Remarks

Default

Example

fullWidth?

Remarks

Default

Example

groupingId?

Remarks

Example

icon?

Remarks

Examples

See

iconType?

Remarks

Default

Example

See

id

Remarks

Example

onClick?

Remarks

Example

See

onlyIcon?

Remarks

Default

Example

title?

Remarks

Example

type?

Remarks

Default

Example

variant?

Remarks

Default

Example