Interface: BaseControl

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

Определяет общую функциональность и структуру для всех UI компонентов, включая кнопки, пункты меню, селекторы, индикаторы и другие элементы управления.

Объединяет функциональность из четырёх базовых интерфейсов для обеспечения единообразия и совместимости всех UI элементов.

Remarks

Иерархия интерфейсов:

BaseControl (текущий интерфейс)
  ├── extends BaseUiElement
  │   ├── id: string (обязательно)
  │   ├── onClick?: Callback (опционально)
  │   └── ...
  ├── extends HasTitle
  │   └── title: string (обязательно)
  ├── extends MayHaveOrder
  │   └── order?: number (опционально)
  └── extends MayHaveGroupingId
      └── groupingId?: string (опционально)

Компоненты, использующие BaseControl:

• SimpleContextMenuItem — пункты контекстного меню
• BaseContextMenuItem — базовые пункты контекстного меню
• Кнопки в ленте инструментов
• Элементы боковых панелей
• Селекторы и выпадающие списки
• Пункты в основном меню

Обязательные свойства:

• id — уникальный идентификатор элемента
• title — текст, отображаемый пользователю

Опциональные свойства:

• onClick? — обработчик события клика
• order? — порядок отображения элемента
• groupingId? — идентификатор группы для группировки элементов

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

• Это базовый интерфейс, используемый внутренне другими интерфейсами
• Прямое использование редко, обычно используются более специфичные интерфейсы
• Расширение для создания кастомных UI компонентов

Example

Элемент, использующий BaseControl

const button: SimpleContextMenuItem = {
  id: 'plugin:my-button',           // от BaseUiElement
  title: 'Моя кнопка',              // от HasTitle
  order: 10,                        // от MayHaveOrder
  groupingId: 'plugin_actions',     // от MayHaveGroupingId
  onClick: editorApi.createCallback(() => {
    console.log('Кнопка нажата');
  })
};

editorApi.ui.contextMenu.addItems([button]);

Структура наследуемых свойств

// BaseUiElement: базовые свойства элемента
{
  id: 'plugin:element',
  onClick: callback
}

// HasTitle: название элемента
{
  title: 'Название элемента'
}

// MayHaveOrder: порядок отображения
{
  order: 100
}

// MayHaveGroupingId: группировка элементов
{
  groupingId: 'group_name'
}

Разные типы UI элементов с BaseControl

// Пункт контекстного меню (использует BaseControl через SimpleContextMenuItem)
const menuItem: SimpleContextMenuItem = {
  id: 'plugin:menu-item',
  title: 'Пункт меню',
  groupingId: 'plugin_menu',
  onClick: editorApi.createCallback(() => {})
};

// Кнопка в ленте (использует BaseControl через RibbonButton)
const button = {
  id: 'plugin:button',
  title: 'Кнопка',
  order: 1,
  onClick: editorApi.createCallback(() => {})
};

// Элемент в боковой панели (использует BaseControl)
const panelItem = {
  id: 'plugin:panel-item',
  title: 'Элемент панели',
  groupingId: 'plugin_panel',
  order: 5,
  onClick: editorApi.createCallback(() => {})
};

Общие принципы для всех UI элементов:

1. id должен быть уникален в контексте надстройки
2. title должен быть понятным и лаконичным
3. order используется для сортировки элементов (меньше — выше/левее)
4. groupingId используется для визуальной группировки однотипных элементов
5. onClick содержит логику при клике пользователя

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

• Используйте единообразные ID для похожих элементов
• Группируйте связанные элементы с одинаковым groupingId
• Используйте order для логичного расположения элементов
• Используйте понятные названия в title

See

• BaseUiElement — базовые свойства с id и onClick
• HasTitle — интерфейс для элементов с названием
• MayHaveOrder — интерфейс для опционального порядка
• MayHaveGroupingId — интерфейс для опциональной группировки
• SimpleContextMenuItem — реальное использование BaseControl
• BaseContextMenuItem — пример наследования BaseControl

Extends

• BaseUiElement.HasTitle.MayHaveGroupingId

Extended by

• Button
• ButtonWithDropdown
• BaseContextMenuItem

Properties

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

Inherited from

MayHaveGroupingId.groupingId

---

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

Inherited from

BaseUiElement.id

---

title

readonly title: string

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

Remarks

Требования:

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

Примеры:

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

Советы:

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

Example

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

Inherited from

HasTitle.title