Type Alias: Input

Input = BaseControl & MayBeDisabled & object

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

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

Type declaration

autofocus?

optional autofocus: boolean

Флаг автоматического перемещения фокуса на это поле при загрузке.

Если установлено в true, поле автоматически получит фокус, когда контейнер загружается или становится видимым.

Remarks

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

• Главное поле ввода в форме
• Быстрое начало работы (пользователь может сразу печатать)
• Улучшение UX — нет нужды кликать на поле

Поведение:

• Срабатывает после загрузки контейнера
• Фокус переходит на поле автоматически
• Курсор появляется в поле
• Пользователь может сразу начать печатать

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

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

Default

false (фокус не устанавливается)

Example

Поле с автофокусом

const searchInput: Input = {
  id: 'plugin:search',
  title: 'Поиск',
  type: 'input',
  placeholder: 'Введите поисковый запрос...',
  autofocus: true,  // Фокус на это поле при загрузке
  onInput: editorApi.createCallback((value: string) => {
    // выполнить поиск
  })
};

Диалог с автофокусом на главное поле

const dialog: Modal = {
  title: 'Ввод данных',
  content: {
    type: 'controls',
    items: [
      {
        id: 'plugin:name',
        title: 'Имя',
        type: 'input',
        autofocus: true,  // Пользователь сразу может печатать
        placeholder: 'Введите ваше имя'
      }
    ]
  }
};

content?

optional content: string

Текущее значение текстового поля.

Содержит текст, введённый пользователем или установленный программно.

Remarks

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

• Инициализация поля значением
• Обновление значения программно через editorApi.ui.updateNode()
• Получение текущего значения в обработчиках событий

Обновление значения:

editorApi.ui.updateNode('input-id', { content: 'новое значение' });

Получение значения:

• Через параметр в onInput: (value: string) => {}
• Или сохранить локальную переменную в обработчике

Примечание:

• При обновлении content не срабатывает onInput
• Используйте onInput для отслеживания изменений пользователем

Default

undefined (пустое поле)

Example

Инициализация с значением

const input: Input = {
  id: 'plugin:text',
  title: 'Текст',
  type: 'input',
  content: 'Начальное значение'
};

Обновление значения программно

editorApi.ui.updateNode('plugin:text', {
  content: 'Новое значение'
});

See

onInput — событие при изменении значения

error?

optional error: boolean

Флаг ошибки ввода.

Указывает на ошибку валидации. Влияет на визуальное представление: изменяет цвет helperText и может добавить красную рамку вокруг поля.

Remarks

Поведение:

• error: false — поле в нормальном состоянии
• error: true — поле в состоянии ошибки (красная рамка и текст)

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

• Красная рамка вокруг поля
• HelperText становится красным (если установлен)
• Может отобразиться иконка ошибки (зависит от контейнера)

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

• Валидация на клиенте (email, формат, требования)
• Валидация на сервере (уникальность, наличие)
• Обязательные поля

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

• Всегда установите helperText при error: true
• Объясните пользователю что не так и как исправить
• Обновляйте ошибку в real-time при вводе (onInput)
• Очищайте ошибку, когда пользователь исправит значение

Default

false (нет ошибки)

Example

Валидация при blur

const emailInput: Input = {
  id: 'plugin:email',
  title: 'Email',
  type: 'input',
  placeholder: 'example@domain.com',
  error: false,
  helperText: 'Введите корректный email',
  onBlur: editorApi.createCallback(async () => {
    const value = await getInputValue('plugin:email');
    const isValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);

    editorApi.ui.updateNode('plugin:email', {
      error: !isValid,
      helperText: isValid
        ? 'Email корректен'
        : 'Email в неправильном формате'
    });
  })
};

Валидация при вводе

const passwordInput: Input = {
  id: 'plugin:password',
  title: 'Пароль',
  type: 'input',
  placeholder: 'Минимум 8 символов',
  onInput: editorApi.createCallback((value: string) => {
    const isValid = value.length >= 8;

    editorApi.ui.updateNode('plugin:password', {
      error: !isValid,
      helperText: isValid
        ? 'Пароль достаточно длинный'
        : `Ещё ${8 - value.length} символов`
    });
  })
};

See

helperText — текст, который становится красным

helperText?

optional helperText: string

Текст-подсказка, отображаемая под полем ввода.

Обычно серого цвета, но красного, если установлен флаг error.

Remarks

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

• Дополнительные инструкции или подробности
• Сообщения об ошибках валидации (если error: true)
• Требования к формату
• Дополнительная информация

Цветовая кодировка:

• error: false — серый цвет (информация)
• error: true — красный цвет (ошибка)

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

• Используйте для валидации ошибок
• Указывайте точные требования (мин/макс длина, формат)
• Предложите исправления, если возможно
• Будьте вежливы в формулировке

Default

undefined (нет подсказки)

Example

Информационная подсказка

const passwordInput: Input = {
  id: 'plugin:password',
  title: 'Пароль',
  type: 'input',
  helperText: 'Минимум 8 символов, должны быть буквы и цифры'
};

Подсказка об ошибке

const input: Input = {
  id: 'plugin:email',
  title: 'Email',
  type: 'input',
  error: true,
  helperText: 'Email в неправильном формате. Используйте format: example@domain.com'
};

Обновление helperText при ошибке

editorApi.ui.updateNode('plugin:input', {
  error: true,
  helperText: 'Это значение уже используется'
});

See

• error — флаг ошибки (меняет цвет helperText)
• placeholder — для менее навязчивых подсказок

onBlur?

optional onBlur: Callback

Обработчик события потери фокуса полем ввода.

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

Remarks

Когда срабатывает:

• При клике вне поля
• При нажатии Tab для перехода на следующий элемент
• При программном снятии фокуса
• При скрытии контейнера

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

• Валидация после завершения ввода
• Сохранение значения
• Очистка UI
• Отправка данных на сервер
• Отслеживание активности

Примечание:

• Не получает параметры
• Срабатывает один раз при потере фокуса
• Хороший момент для валидации (не затрудняет ввод)

Default

undefined (событие не обрабатывается)

Example

Валидация при blur

const emailInput: Input = {
  id: 'plugin:email',
  title: 'Email',
  type: 'input',
  placeholder: 'example@domain.com',
  onBlur: editorApi.createCallback(async () => {
    // это хороший момент для валидации
    // не затрудняет пользователя при вводе
  })
};

Автосохранение при blur

const textInput: Input = {
  id: 'plugin:content',
  title: 'Содержимое',
  type: 'input',
  onBlur: editorApi.createCallback(async () => {
    const value = await getInputValue('plugin:content');
    // автосохранить значение
    await saveToServer(value);
  })
};

See

• onFocus — событие при получении фокуса
• onInput — при изменении значения

onEnter?

optional onEnter: Callback

Обработчик события нажатия клавиши Enter в поле.

Срабатывает, когда пользователь нажимает Enter (Return) в этом поле.

Remarks

Когда срабатывает:

• При нажатии Enter в поле ввода
• Может быть настроено в некоторых контейнерах

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

• Отправка формы (Search, Send)
• Выполнение команды (Command line)
• Подтверждение действия
• Быстрые операции

Примечание:

• Не получает параметры
• Обычно используется для завершения ввода
• Хороший способ повысить productivity (не нужна кнопка)
• На мобильных клавиатуре обычно есть кнопка "Go" вместо Enter

Default

undefined (событие не обрабатывается)

Example

Поле поиска с Enter

const searchInput: Input = {
  id: 'plugin:search',
  title: 'Поиск',
  type: 'input',
  placeholder: 'Введите и нажмите Enter...',
  withClearButton: true,
  onEnter: editorApi.createCallback(async () => {
    const value = await getInputValue('plugin:search');
    console.log('Поиск:', value);
    // выполнить поиск
  })
};

Команды с Enter

const commandInput: Input = {
  id: 'plugin:command',
  title: 'Команда',
  type: 'input',
  placeholder: 'Введите команду и нажмите Enter',
  autofocus: true,
  onEnter: editorApi.createCallback(async () => {
    const command = await getInputValue('plugin:command');
    console.log('Выполнить:', command);
    // выполнить команду
    // очистить поле
    editorApi.ui.updateNode('plugin:command', { content: '' });
  })
};

Отправка формы при Enter

const nameInput: Input = {
  id: 'plugin:name',
  title: 'Имя',
  type: 'input',
  placeholder: 'Введите имя и нажмите Enter',
  onEnter: editorApi.createCallback(async () => {
    const name = await getInputValue('plugin:name');
    if (name.trim()) {
      // отправить форму
      await submitForm({ name });
    }
  })
};

See

onEsc — для обработки Escape

onEsc?

optional onEsc: Callback

Обработчик события нажатия клавиши Escape в поле.

Срабатывает, когда пользователь нажимает Esc в этом поле.

Remarks

Когда срабатывает:

• При нажатии Escape (Esc) в поле ввода
• Может быть использовано для отмены действий
• Важно для улучшения UX

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

• Отмена редактирования (вернуться к исходному значению)
• Закрытие редактора или формы
• Очистка поля
• Отмена поиска

Примечание:

• Не получает параметры
• Хороший паттерн UX — Escape отменяет текущее действие
• На мобильных устройствах может быть недоступно

Default

undefined (событие не обрабатывается)

Example

Отмена редактирования

let originalValue = 'Исходное значение';

const editInput: Input = {
  id: 'plugin:edit',
  title: 'Редактирование',
  type: 'input',
  content: originalValue,
  onEsc: editorApi.createCallback(() => {
    // Escape отменяет редактирование
    editorApi.ui.updateNode('plugin:edit', {
      content: originalValue
    });
    console.log('Редактирование отменено');
  })
};

Очистка поиска

const searchInput: Input = {
  id: 'plugin:search',
  title: 'Поиск',
  type: 'input',
  placeholder: 'Поиск (Esc для отмены)...',
  withClearButton: true,
  onEsc: editorApi.createCallback(() => {
    // Escape очищает поиск и результаты
    editorApi.ui.updateNode('plugin:search', {
      content: ''
    });
    // очистить результаты поиска
  })
};

Закрытие модального окна

const commandInput: Input = {
  id: 'plugin:command',
  title: 'Команда',
  type: 'input',
  placeholder: 'Введите (Esc для отмены)',
  onEsc: editorApi.createCallback(async () => {
    // Escape закрывает диалог
    await editorApi.ui.closeModal?.('command-modal');
  })
};

See

onEnter — для обработки Enter

onFocus?

optional onFocus: Callback

Обработчик события установки фокуса в поле ввода.

Срабатывает, когда пользователь кликает на поле или переходит на него клавишей Tab.

Remarks

Когда срабатывает:

• При клике на поле
• При нажатии Tab для перехода на поле
• При программной установке фокуса
• При autofocus при загрузке контейнера

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

• Показать подсказки или дополнительную информацию
• Очистить сообщение об ошибке
• Включить дополнительный UI элемент
• Отслеживание активности
• Загрузка данных по требованию

Примечание:

• Не получает параметры
• Срабатывает один раз при получении фокуса
• Используйте вместе с onBlur для отслеживания активности

Default

undefined (событие не обрабатывается)

Example

Отслеживание фокуса

const input: Input = {
  id: 'plugin:text',
  title: 'Текст',
  type: 'input',
  onFocus: editorApi.createCallback(() => {
    console.log('Поле получило фокус');
    // показать подсказку или помощь
  }),
  onBlur: editorApi.createCallback(() => {
    console.log('Поле потеряло фокус');
    // скрыть подсказку
  })
};

Очистка ошибки при фокусе

const input: Input = {
  id: 'plugin:email',
  title: 'Email',
  type: 'input',
  error: false,
  helperText: '',
  onFocus: editorApi.createCallback(() => {
    // очистить ошибку при фокусе
    editorApi.ui.updateNode('plugin:email', {
      error: false,
      helperText: 'Введите email адрес'
    });
  })
};

See

• onBlur — событие при потере фокуса
• onInput — при изменении значения

onInput?

optional onInput: Callback<string>

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

Срабатывает при вводе, удалении, вставке или любом изменении текста.

Remarks

Когда срабатывает:

• При каждом нажатии клавиши в поле
• При вставке текста (Ctrl+V)
• При удалении текста (Backspace, Delete)
• При очистке кнопкой очистки
• При программном обновлении content (некоторые контейнеры)

Параметр callback:

• Получает текущее значение поля как параметр
• Тип: Callback<string>
• Вызывается с новым значением

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

• Валидация при вводе (real-time)
• Поиск и фильтрация (live search)
• Обновление зависимых элементов
• Ограничение количества символов
• Автосохранение

Примечание:

• Срабатывает часто — избегайте тяжёлых операций
• Используйте debounce для сетевых запросов
• Сохраняйте значение в локальной переменной для быстрого доступа

Default

undefined (событие не обрабатывается)

Example

Простое отслеживание значения

let currentValue = '';

const input: Input = {
  id: 'plugin:text',
  title: 'Текст',
  type: 'input',
  onInput: editorApi.createCallback((value: string) => {
    currentValue = value;
    console.log('Введено:', value);
  })
};

Live search с debounce

let searchTimeout: NodeJS.Timeout;

const searchInput: Input = {
  id: 'plugin:search',
  title: 'Поиск',
  type: 'input',
  placeholder: 'Поиск...',
  withClearButton: true,
  onInput: editorApi.createCallback((value: string) => {
    clearTimeout(searchTimeout);

    searchTimeout = setTimeout(() => {
      console.log('Выполнить поиск:', value);
      // выполнить сетевой запрос
    }, 300);
  })
};

Валидация при вводе

const input: Input = {
  id: 'plugin:password',
  title: 'Пароль',
  type: 'input',
  placeholder: 'Минимум 8 символов',
  onInput: editorApi.createCallback((value: string) => {
    const isValid = value.length >= 8;

    editorApi.ui.updateNode('plugin:password', {
      error: !isValid,
      helperText: isValid
        ? '✓ Пароль достаточно длинный'
        : `✗ Ещё ${8 - value.length} символов`
    });
  })
};

See

• Callback — тип обработчика
• onBlur — для валидации после завершения ввода
• onEnter — для отправки при нажатии Enter

placeholder?

optional placeholder: string

Текст-подсказка, отображаемая в пустом поле ввода.

Обычно серого цвета, исчезает когда пользователь начинает печатать.

Remarks

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

• Помощь пользователю в понимании, что ввести
• Примеры формата (email@example.com, YYYY-MM-DD)
• Краткие инструкции

Поведение:

• Отображается только когда поле пусто
• Исчезает при фокусе или начале печати
• Не входит в значение поля
• Светло-серый цвет по умолчанию

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

• Используйте краткие подсказки (не более 50 символов)
• Дайте примеры формата если нужна определённая структура
• Не повторяйте title в placeholder
• Используйте helperText для более подробных инструкций

Default

undefined (нет подсказки)

Example

Простой placeholder

const input: Input = {
  id: 'plugin:search',
  title: 'Поиск',
  type: 'input',
  placeholder: 'Введите текст...'
};

Placeholder с примером формата

const emailInput: Input = {
  id: 'plugin:email',
  title: 'Email',
  type: 'input',
  placeholder: 'example@domain.com'
};

const dateInput: Input = {
  id: 'plugin:date',
  title: 'Дата',
  type: 'input',
  placeholder: 'YYYY-MM-DD'
};

See

helperText — для более подробной помощи под полем

type

type: "input"

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

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

Remarks

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

Default

'input'

Example

const input: Input = {
  id: 'plugin:text-input',
  title: 'Текст',
  type: 'input',  // Маркер типа
  placeholder: 'Введите текст'
};

withClearButton?

optional withClearButton: boolean

Флаг наличия кнопки очистки поля ввода.

Если установлено в true, в конце поля отображается кнопка (обычно иконка X), которая позволяет пользователю быстро очистить содержимое.

Remarks

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

• Поля поиска (для быстрой очистки)
• Фильтры (для сброса фильтра)
• Поля ввода, где часто нужна очистка
• Лучшее UX для мобильных устройств

Поведение:

• Кнопка обычно в конце поля
• Видна, только если в поле есть текст
• При клике полностью очищает поле
• Срабатывает onInput с пустой строкой

Визуальное представление:

┌─────────────────────────────────┬─────┐
│ Введённый текст                │  ✕  │
└─────────────────────────────────┴─────┘
                                    ^
                          кнопка очистки

Default

false (без кнопки очистки)

Example

Поле поиска с кнопкой очистки

const searchInput: Input = {
  id: 'plugin:search',
  title: 'Поиск',
  type: 'input',
  placeholder: 'Поиск...',
  withClearButton: true,  // Добавить кнопку очистки
  onInput: editorApi.createCallback((value: string) => {
    // выполнить поиск или фильтрацию
  })
};

Фильтр с очисткой

const filterInput: Input = {
  id: 'plugin:filter',
  title: 'Фильтр',
  type: 'input',
  placeholder: 'Введите текст для фильтрации',
  withClearButton: true,
  onInput: editorApi.createCallback((value: string) => {
    if (value === '') {
      // очистить фильтр, показать все
    } else {
      // применить фильтр
    }
  })
};

Remarks

Поддержка в контейнерах:

• Боковые панели (sidebar) — полная поддержка
• Модальные окна (modals) — полная поддержка
• Лента инструментов (ribbon) — зависит от реализации (может не поддерживаться)
• Контекстное меню — не поддерживается

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

Input (текущий тип)
  ├── extends BaseControl
  │   ├── id: string (обязательно)
  │   ├── title: string (обязательно)
  │   ├── order?: number (опционально)
  │   └── groupingId?: string (опционально)
  └── extends MayBeDisabled
      └── disabled?: boolean (опционально)
  └── Специфичные свойства Input:
      ├── content?: string (текущее значение)
      ├── placeholder?: string (подсказка в пустом поле)
      ├── helperText?: string (текст помощи)
      ├── error?: boolean (ошибка)
      ├── onInput?: Callback<string>
      ├── onFocus?: Callback
      ├── onBlur?: Callback
      ├── onEnter?: Callback
      └── onEsc?: Callback

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

• Ввод текста команд или параметров в боковой панели
• Поля для поиска или фильтрации
• Формы для ввода данных в модальных окнах
• Динамические поля ввода с валидацией
• Взаимодействие с пользователем для получения входных данных

Example

Простое текстовое поле в боковой панели

const inputField: Input = {
  id: 'plugin:search',
  title: 'Поиск',
  type: 'input',
  placeholder: 'Введите текст для поиска...',
  onInput: editorApi.createCallback((value: string) => {
    console.log('Поиск:', value);
    // выполнить поиск
  })
};

Текстовое поле с валидацией

const emailInput: Input = {
  id: 'plugin:email',
  title: 'Email',
  type: 'input',
  placeholder: 'example@domain.com',
  helperText: 'Введите корректный email адрес',
  error: false,
  onBlur: editorApi.createCallback(async () => {
    const emailValue = await getInputValue('plugin:email');
    const isValid = validateEmail(emailValue);
    // обновить состояние ошибки
    editorApi.ui.updateNode('plugin:email', { error: !isValid });
  })
};

Поле с Enter и Escape обработчиками

const commandInput: Input = {
  id: 'plugin:command',
  title: 'Команда',
  type: 'input',
  placeholder: 'Введите команду и нажмите Enter',
  onEnter: editorApi.createCallback(async () => {
    const command = await getInputValue('plugin:command');
    console.log('Выполнить команду:', command);
    // выполнить команду
  }),
  onEsc: editorApi.createCallback(() => {
    // очистить поле
    editorApi.ui.updateNode('plugin:command', { content: '' });
  })
};

See

• BaseControl — базовые свойства (id, title, order, groupingId)
• MayBeDisabled — состояние disabled
• Callback — тип обработчика события
• SidebarApi — использование в боковых панелях