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) => {
        // выполнить поиск
    })
};

content?

optional content: string

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

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

Remarks

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

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

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

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

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

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

Примечание:

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

Default

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

Example

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

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

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

editorApi.ui.updateUiNodes([{
    id: '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.updateUiNodes([{
            id: '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.updateUiNodes([{
            id: '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.updateUiNodes([{
    id: '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.updateUiNodes([{ id: '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.updateUiNodes([{ id: '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.updateUiNodes([{
            id: '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.updateUiNodes([{
            id: '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.updateUiNodes([{
            id: '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.updateUiNodes('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.updateUiNodes([{ id: 'plugin:command', content: '' }]);
    })
};

See

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