Перейти к основному содержимому
Версия: Next

Interface: InputUpdate

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

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

Remarks​

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

  • content — текущее значение в поле
  • title — название/ярлык поля
  • placeholder — подсказка в пустом поле
  • helperText — текст помощи под полем
  • error — флаг ошибки (влияет на цвет helperText)
  • disabled — доступность поля (включено/отключено)
  • onInput — обработчик при изменении
  • onBlur — обработчик при потере фокуса
  • onFocus — обработчик при получении фокуса

Нельзя изменять:

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

Сценарии обновления:

  • Валидация при вводе — обновить error и helperText
  • Отключение при загрузке — обновить disabled
  • Очистка после операции — обновить content на пустую строку
  • Включение/отключение кнопки в зависимости от значения

Example​

Обновление значения и состояния ошибки

editorApi.ui.updateUiNodes([
    {
        id: 'plugin:input:email',
        content: '',  // Очистить поле
        error: false,  // Убрать ошибку
        helperText: ''  // Очистить подсказку
    }
]);

Валидация с ошибкой

editorApi.ui.updateUiNodes([
    {
        id: 'plugin:input:email',
        error: true,
        helperText: 'Email неправильного формата. Используйте: example@domain.com'
    }
]);

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

// При начале загрузки
editorApi.ui.updateUiNodes([
    {
        id: 'plugin:input:username',
        disabled: true,
        placeholder: 'Загрузка...'
    },
    {
        id: 'plugin:button:login',
        disabled: true,
        title: 'Вход...'
    }
]);

// После загрузки
editorApi.ui.updateUiNodes([
    {
        id: 'plugin:input:username',
        disabled: false,
        placeholder: 'Введите имя пользователя'
    },
    {
        id: 'plugin:button:login',
        disabled: false,
        title: 'Вход'
    }
]);

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

editorApi.ui.updateUiNodes([
    {
        id: 'plugin:input:filter',
        onInput: editorApi.createCallback((value: string) => {
          // новая логика фильтрации
        })
    }
]);

See​

  • Input — структура текстового поля
  • EditorUiApi.updateUiNodes — метод для применения обновлений

Properties​

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 — событие при изменении значения

disabled?​

readonly optional disabled: boolean

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

Remarks​

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

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

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

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

Default​

false (включено)

Example​

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

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

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

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

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

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

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 — текст, который становится красным

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

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 — для менее навязчивых подсказок

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

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

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 — для более подробной помощи под полем

title?​

readonly optional title: string

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

Remarks​

Требования:

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

Примеры:

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

Советы:

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

Example​

{
    id: 'button:save',
    title: 'Сохранить',
    type: 'button'
}

type?​

optional 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 {
            // применить фильтр
        }
    })
};