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

Interface: EditorUiApi

Главный API для управления пользовательским интерфейсом редактора.

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

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

Remarks

Структура UI редактора:

┌─────────────────────────────────────────────────────┐
│ Лента инструментов (ribbon)                         │
├──────────────────────────────────────┬──────────────┤
│ Основное рабочее пространство        │ Боковая      │
│ (документ)                           │ панель       │
│ + Графический слой (overlays)        │ (sidebar)    │
│ + Уведомления (toasts)               │ справа       │
│ + Контекстное меню                   │              │
│ + Модальные окна (modals)            │              │
└──────────────────────────────────────┴──────────────┘

Компоненты EditorUiApi:

ribbon — лента инструментов с кнопками и меню
sidebar — боковые панели с вкладками
overlays — графические слои поверх документа (планируется)
toasts — всплывающие уведомления
modals — модальные окна и диалоги
contextMenu — контекстное меню (правый клик)
updateUiNodes — методы обновления пользовательских элементов

Типичные сценарии использования:

Добавление кнопок и вкладок в ленту инструментов
Создание боковых панелей для параметров надстройки
Показ уведомлений о выполнении операций
Открытие модальных окон для ввода данных
Добавление пунктов в контекстное меню
Динамическое обновление элементов UI
Отображение результатов и статуса операций

Example

Использование разных компонентов EditorUiApi

export default {
  onInit: async (editorApi) => {
    // Добавить кнопку в ленту
    editorApi.ui.ribbon.addTab({
      id: 'plugin:tab',
      title: 'My Plugin',
      groups: [{
        id: 'plugin:group',
        type: 'controls',
        controls: [{
          id: 'plugin:button',
          title: 'Do something',
          type: 'button',
          onClick: editorApi.createCallback(() => {
            editorApi.ui.toasts.showToast({ id, content: 'Done!' });
          })
        }]
      }]
    });

    // Добавить боковую панель
    editorApi.ui.sidebar.addTab({
      id: 'plugin:sidebar',
      title: 'Settings',
      content: [{
        type: 'controls',
        items: [{
          id: 'plugin:info',
          type: 'textblock',
          content: 'Plugin is ready'
        }]
      }]
    });

    // Добавить пункт в контекстное меню
    editorApi.ui.contextMenu.addItems([{
      id: 'plugin:menu-item',
      title: 'My action',
      onClick: editorApi.createCallback(() => {
        editorApi.ui.toasts.showToast({ id, content: 'Action executed' });
      })
    }]);
  }
}

See

RibbonApi — ленту инструментов
SidebarApi — боковые панели
ToastsApi — уведомления
ModalsApi — модальные окна
ContextMenuApi — контекстное меню
OverlaysApi — графические слои (планируется)

Methods

updateUiNodes()

updateUiNodes(updates, priority?): void

Метод для динамического обновления пользовательских элементов интерфейса.

Позволяет изменять свойства элементов UI (контент, состояние, видимость) после их создания.

Parameters

updates

UINodeUpdate[]

Массив обновлений для элементов UI

priority?

Priority

Приоритет обработки (Normal по умолчанию, High для срочных обновлений)

Returns

void

Remarks

Типы обновлений:

Изменение содержимого (content)
Изменение состояния (disabled, error, checked)
Изменение текста (title, placeholder, helperText)
Изменение стилей (styles)
Изменение видимости (visible)

Работает только с элементами надстройки:

Запросы на встроенные элементы редактора игнорируются
ID элемента должен содержать префикс надстройки
Контейнер должен содержать такой элемент

Приоритеты:

Normal (default) — обновление выполняется в очереди
High — срочное обновление, выполняется как можно скорее

Throws

Может выбросить ошибку если элемент не найден (в некоторых случаях)

Example

Обновление содержимого элемента

editorApi.ui.updateUiNodes([
  {
    id: 'plugin:info',
    updates: {
      content: 'Новое содержимое'
    }
  }
]);

Обновление состояния (disabled, error)

editorApi.ui.updateUiNodes([
  {
    id: 'plugin:input',
    updates: {
      error: true,
      helperText: 'Ошибка валидации'
    }
  },
  {
    id: 'plugin:button',
    updates: {
      disabled: !isValid
    }
  }
]);

Обновление с высоким приоритетом

editorApi.ui.updateUiNodes(
  [
    {
      id: 'plugin:status',
      updates: {
        content: 'Критическая ошибка!'
      }
    }
  ],
  'High'  // Срочное обновление
);

Цепное обновление нескольких элементов

const updates: UINodeUpdate[] = [
  {
    id: 'plugin:input-email',
    updates: {
      error: false,
      helperText: ''
    }
  },
  {
    id: 'plugin:input-password',
    updates: {
      error: false,
      helperText: ''
    }
  },
  {
    id: 'plugin:button-submit',
    updates: {
      disabled: false
    }
  }
];

editorApi.ui.updateUiNodes(updates);

Обновление при изменении состояния (real-time валидация)

// В обработчике onInput для текстового поля
onInput: editorApi.createCallback((value: string) => {
  const isValid = value.length >= 8;

  editorApi.ui.updateUiNodes([
    {
      id: 'plugin:password',
      updates: {
        error: !isValid,
        helperText: isValid
          ? 'Пароль хороший'
          : `Ещё ${8 - value.length} символов`
      }
    },
    {
      id: 'plugin:submit-btn',
      updates: {
        disabled: !isValid
      }
    }
  ]);
})

See

UINodeUpdate — структура обновления элемента
Priority — типы приоритетов
RibbonApi — для управления элементами ленты
SidebarApi — для управления элементами боковой панели

Properties

contextMenu

readonly contextMenu: ContextMenuApi

API управления контекстным меню (правый клик).

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

Remarks

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

Появляется при клике правой кнопкой мыши
Размещает кастомные пункты ниже стандартных
Поддерживает условную видимость (shownInScopes)
Поддерживает группировку пунктов
Может содержать вложенные подменю

Типичные пункты:

Быстрые действия (Copy, Paste, Delete)
Трансформация текста (Uppercase, Lowercase)
Специальные операции (Export, Analyze)
Настройки объекта

Лучшие практики:

Ограничивайте количество пунктов (максимум 5-7)
Группируйте связанные пункты
Используйте условную видимость
Не дублируйте стандартные операции

See

ContextMenuApi — полное описание API

Example

editorApi.ui.contextMenu.addItems([
  {
    id: 'plugin:action',
    title: 'Мое действие',
    shownInScopes: [{ scope: 'text' }],
    onClick: editorApi.createCallback(() => {})
  }
]);

modals

readonly modals: ModalsApi

API управления модальными окнами (диалогами).

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

Remarks

Типы модальных окон:

Диалоги подтверждения (OK / Cancel)
Формы ввода данных
Оповещения и предупреждения
Окна информации и справки

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

Блокируют взаимодействие с остальным интерфейсом
Отображаются в центре экрана
Требуют действия пользователя (выбор кнопки)
Могут содержать сложные формы

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

Подтверждение опасных операций (Delete, Clear)
Ввод данных (Search, Settings)
Важные сообщения
Выбор из вариантов

Лучшие практики:

Используйте для важных решений
Не перегружайте содержимое
Предоставляйте понятные опции (OK, Cancel, Apply)
Выделяйте опасные действия (Delete красным)

See

ModalsApi — полное описание API

Example

editorApi.ui.modals.showModal({
  title: 'Подтверждение',
  content: 'Вы уверены?',
  buttons: [
    { title: 'OK', variant: 'primary' },
    { title: 'Cancel', variant: 'secondary' }
  ]
});

ribbon

readonly ribbon: RibbonApi

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

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

Remarks

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

Создание пользовательских вкладок
Добавление кнопок, выпадающих меню, селекторов
Организация элементов в группы
Управление порядком и видимостью элементов

Типичные элементы ленты:

Кнопки действий (Save, Copy, Paste)
Выпадающие меню (Format, Export)
Селекторы (Font Size, Style)
Индикаторы статуса

Лучшие практики:

Ограничивайте количество вкладок (максимум 3-5)
Группируйте связанные элементы
Используйте понятные иконки
Не перегружайте ленту элементами

See

RibbonApi — полное описание API

Example

editorApi.ui.ribbon.addTab({
  id: 'plugin:tab',
  title: 'My Plugin',
  order: 10,
  groups: [{
    id: 'plugin:group',
    type: 'controls',
    controls: [
      {
        id: 'plugin:button',
        title: 'Action',
        type: 'button',
        onClick: editorApi.createCallback(() => {})
      }
    ]
  }]
});

readonly sidebar: SidebarApi

API управления боковыми панелями с вкладками.

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

Remarks

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

Создание пользовательских панелей
Добавление вкладок на панели
Размещение элементов управления и контента
Управление позицией и размером панели
Поддержка прокрутки и динамического контента

Типичный контент:

Параметры надстройки (Settings)
Информационные панели (Info, Help)
Навигационные панели (Outline, Navigation)
Результаты операций (Results, Output)
Формы ввода данных

Лучшие практики:

Используйте для параметров и настроек
Отображайте информацию и результаты
Группируйте элементы логически
Предусмотрите скролл для длинного контента

See

SidebarApi — полное описание API

Example

editorApi.ui.sidebar.addTab({
  id: 'plugin:panel',
  title: 'Settings',
  icon: 'Settings',
  content: [{
    type: 'controls',
    items: [
      {
        id: 'plugin:input',
        type: 'input',
        title: 'Parameter',
        placeholder: 'Enter value'
      }
    ]
  }]
});

toasts

readonly toasts: ToastsApi

API управления всплывающими уведомлениями (toast notifications).

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

Remarks

Типы уведомлений:

не указан - нейтральный, без иконки
error — красные, для ошибок

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

Появляются в углу экрана (обычно внизу справа)
Автоматически исчезают через несколько секунд
Не блокируют работу пользователя
Стекируются если несколько сообщений

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

Подтверждение операций
Уведомления об ошибках
Информирование о статусе
Подсказки пользователю

Лучшие практики:

Используйте краткие сообщения (до 100 символов)
Не показывайте много сообщений одновременно
Предложите решение для ошибок

See

ToastsApi — полное описание API

Example

editorApi.ui.toasts.showToast({ id, content: 'Успешно сохранено' });
editorApi.ui.toasts.showToast({ id, type: 'error', content: 'Ошибка при сохранении' });

Remarks​

Example​

See​

Methods​

updateUiNodes()​

Parameters​

updates​

priority?​

Returns​

Remarks​

Throws​

Example​

See​

Properties​

contextMenu​

Remarks​

See​

Example​

modals​

Remarks​

See​

Example​

ribbon​

Remarks​

See​

Example​

sidebar​

Remarks​

See​

Example​

toasts​

Remarks​

See​

Example​

Remarks

Example

See

Methods

updateUiNodes()

Parameters

updates

priority?

Returns

Remarks

Throws

Example

See

Properties

contextMenu

Remarks

See

Example

modals

Remarks

See

Example

ribbon

Remarks

See

Example

sidebar

Remarks

See

Example

toasts

Remarks

See

Example