AiFieldInput
AiFieldInput — поле ввода сообщения в чате с агентом и в любом разговоре, которому нужны вложения и ряд действий. Поле принимает текст с чипами скиллов, команд и упоминаний, показывает приложенные файлы и собирает действия перед отправкой. Что произойдёт после отправки, решает потребитель.
Когда использовать
- Ввод сообщения в чате с агентом.
- Ввод ответа в разговоре, где нужны вложения, вызов скиллов по
/и упоминания по@.
Когда не нужен
- Однострочный ввод без вложений и действий:
- используйте
FieldTextиз@cloud-ru/ds-fields.
- используйте
- Многострочный текст без чипов и футера:
- используйте
FieldTextAreaиз@cloud-ru/ds-fields.
- используйте
Анатомия
Поле собрано сверху вниз из четырёх частей, в состоянии ошибки — из пяти:
- кнопка прокрутки к последнему сообщению (
scrollButton) — над полем, с точкой непрочитанного; - слот баннера (
banner) —AiFieldBannerилиAiFieldNotice; пока открыт список по/или@, баннер скрыт, но держит своё место; на мобильной раскладке баннер берёт размерmиз своего пресета адаптивности; - рамка поля — ряд вложений (
attachments, плиткиAiAttachmentиз@cloud-ru/ds-ai-attachment), текстовая область и футер; - строка ошибки (
error) — только в состоянии ошибки, между рамкой и дисклеймером; - дисклеймер (
disclaimer) — текст под рамкой.
Футер состоит из двух слотов (footerLeftActions, footerRightActions) и кнопки отправки, которая стоит справа всегда. Кнопки футера экспортируются отдельно: AiFieldInputPlusButton, AiFieldInputSettingsButton, AiFieldInputModelButton, AiFieldInputEffortButton, AiFieldInputContextButton, AiFieldInputVoiceButton, AiFieldInputSendButton. У AiFieldInputPlusButton, AiFieldInputSettingsButton, AiFieldInputModelButton и AiFieldInputEffortButton есть встроенный выпадающий список:
items— пункты{ id, label, description? };onSelect— выбор пункта, получаетid.
На desktop список открывается над кнопкой, на mobile — в шторке снизу. Пока список открыт, кнопка остаётся в состоянии Pressed. Поиск по названию в списке моделей включается пропом searchable у AiFieldInputModelButton, по умолчанию его нет. На mobile с поиском шторка раскрывается на весь экран, без него — по высоте списка. Выбранный пункт в списке не отмечается: текущее значение показывает подпись кнопки (label). Без items кнопка только сообщает о нажатии через onClick.
Значение
Содержимое поля — массив сегментов AiFieldInputValue:
text— текст,\n— перенос строки;skill— чип скилла или команды. Параметры — обычный текст сообщения за чипом; пока за чипом в строке ничего нет, в нём видна подсказкаparamsPlaceholder(её задаёт строка спискаskills);mention— чип упоминания;search— знак/или@с набранным запросом, пока значение не выбрано.
Ввод / или @ создаёт сегмент search, если для этого знака передан список (skills или mentions) и знак стоит в начале строки, после пробела или сразу за чипом; внутри слова (e@mail) поиск не открывается. Подсказку в поиске задаёт searchPlaceholder — отдельно для / (skill) и @ (mention); не заданный ключ берёт текст из локали. Подсказка видна, пока запрос пуст и сразу за знаком нет текста.
Строки списка передаются пропсами:
skills— команды и скиллы, открываются по/;mentions— ресурсы и сущности, открываются по@.
Поле само показывает список над полем и фильтрует строки по набранному тексту. Список стоит поверх содержимого выше поля и не меняет высоту компонента: баннер на это время скрыт, но держит место. Если совпадений нет — строка «Ничего не найдено». Выбор строки заменяет сегмент search на чип skill или mention, вызывает onActionSelect и возвращает баннер. Пока список открыт, кнопка прокрутки скрыта.
Строка drillDown с вложенными items открывает следующий уровень: первой стоит строка возврата («Назад» или backLabel), при переходе на уровень и обратно набранный запрос стирается, и фильтрация начинается заново. Список закрывают Escape и клик вне списка и текста поля, в том числе по кнопкам футера, — набранный текст остаётся в поле обычным текстом. Клик внутри текста список не закрывает.
Список можно открыть и без знака в тексте — например, пунктом «Добавить скилл» в меню кнопки добавления. Для этого компоненты в слотах поля берут хук useAiFieldInputActions и вызывают openActionList('/') (или '@' для упоминаний):
function PlusButton() {
const { openActionList } = useAiFieldInputActions();
return (
<AiFieldInputPlusButton
items={[{ id: 'skills', label: 'Добавить скилл' }]}
onSelect={id => id === 'skills' && openActionList(SEARCH_TRIGGER.Skill)}
/>
);
}
В таком режиме поле не меняется, фокус встаёт на панель списка, и набранные буквы ничего не делают. Как и при поиске по /, строки сначала не выделены: стрелка вниз выделяет первую, стрелка вверх — последнюю, Enter выбирает первую. Выбранная строка встаёт чипом туда, где стоял курсор, или в конец текста, если поле ещё не фокусировали. После выбора или закрытия (Escape, клик вне списка) фокус возвращается в поле.
Баннер — обычный слот: крестик появляется, если передать onClose в AiFieldBanner; по нему потребитель убирает баннер из пропа banner.
Клавиатура
Enter— отправка (onSubmit); при открытом поиске — выбор первой строки списка.Shift+Enter— перенос строки.↓/↑при открытом поиске — переход в список.Escпри открытом поиске — закрытие списка, знак и запрос остаются текстом.Backspaceсразу за чипом выделяет его (Pressed), повторный — удаляет.Deleteсразу перед чипом — так же. Ввод при выделенном чипе снимает выделение и печатает за чипом.
Состояния
- Default — рамка с нейтральной обводкой.
- Focus — акцентная обводка рамки.
- Disabled (
disabled) — ввод недоступен, ряд вложений скрыт, кнопки футера выключены, кнопка контекста остаётся активной. - Secure (
secure) — ввод пароля, API-ключа или токена. Вместо редактора — однострочное поле пароля: значение скрыто, не копируется и не вырезается, длинное значение обрезается по ширине. Кнопка «глаз» в начале левого футера показывает и снова скрывает значение, каретка остаётся в поле. После отправки значение снова скрыто. Чипов нет, «/» и «@» вводятся как обычный текст. При включенииsecureчипы убираются из значения, текст остаётся. При выключенииsecureзначение очищается; в controlled-режиме редактор не показывает секрет, пока родитель не пришлёт новое значение. - Error (
error) — мягкая красная заливка рамки, в фокусе красная обводка, под рамкой строка ошибки с текстом изerror. Счётчикcurrent/maxв строке ошибки задаётlength— для ошибок, связанных с длиной значения. Ошибка не блокирует ввод и отправку: доступностью кнопки отправки управляетsend. Снимается снаружи — когда значение исправлено или отправлено снова. На выключенном поле ошибка не показывается. В режимеsecureтекст ошибки не повторяет значение.
Кнопка отправки (default — по содержимому)
disabled— пустое поле.active— в поле есть содержимое.loading— сообщение отправляется.stop— агент генерирует ответ, нажатие останавливает генерацию.
Состояния loading и stop задаёт потребитель через send.state. Нажатие на кнопку в состоянии active вызывает onSubmit так же, как Enter; send.onClick получает состояние и содержимое поля. Пока кнопка в loading или stop, Enter не отправляет.
Установка
pnpm add @cloud-ru/ds-ai-field-input @cloud-ru/ds-ai-attachment
@cloud-ru/ds-ai-attachment нужен для плиток вложений, сам пакет поля от него не зависит.
import { AiFieldInput } from '@cloud-ru/ds-ai-field-input'
Примеры использования
Базовое поле
import { AiFieldInput, AiFieldInputValue } from '@cloud-ru/ds-ai-field-input';
import { useState } from 'react';
export function Basic() {
const [value, setValue] = useState<AiFieldInputValue>([]);
const [lastSent, setLastSent] = useState('');
return (
<AiFieldInput
value={value}
onChange={setValue}
onSubmit={current => {
setLastSent(current.map(segment => (segment.type === 'text' ? segment.text : '')).join(''));
setValue([]);
}}
placeholder='Спросите что-нибудь'
disclaimer={lastSent ? `Отправлено: ${lastSent}` : undefined}
/>
);
}Скиллы и упоминания
import { AiFieldBanner } from '@cloud-ru/ds-ai-field-banner';
import { ACTION_LIST_ITEM_TYPE, AiFieldInput, AiFieldInputActionListItem, AiFieldInputValue } from '@cloud-ru/ds-ai-field-input';
import { useState } from 'react';
const SKILLS: AiFieldInputActionListItem[] = [
{ id: 'summarize', label: 'summarize', caption: 'Краткое содержание', shortcut: '⌘ S' },
{ id: 'translate', label: 'translate', caption: 'Перевод текста' },
{
id: 'agents',
label: 'Агенты',
caption: '2',
type: ACTION_LIST_ITEM_TYPE.DrillDown,
backLabel: 'К списку команд',
items: [
{ id: 'hermes', label: 'Гермес' },
{ id: 'analyst', label: 'Аналитик' },
],
},
];
const MENTIONS: AiFieldInputActionListItem[] = [
{ id: 'team', label: 'команде', caption: 'Группа' },
{ id: 'docs', label: 'документация', caption: 'Пространство' },
];
export function SlashCommands() {
const [value, setValue] = useState<AiFieldInputValue>([]);
const [bannerVisible, setBannerVisible] = useState(true);
return (
<AiFieldInput
value={value}
onChange={setValue}
onSubmit={() => setValue([])}
placeholder='Введите / для скиллов или @ для упоминаний'
skills={SKILLS}
mentions={MENTIONS}
banner={
bannerVisible ? (
<AiFieldBanner content='Агент работает в режиме чтения' onClose={() => setBannerVisible(false)} />
) : undefined
}
/>
);
}Вложения
import { AiAttachment, ATTACHMENT_STATE, ATTACHMENT_TYPE } from '@cloud-ru/ds-ai-attachment';
import { AiFieldInput } from '@cloud-ru/ds-ai-field-input';
import { useState } from 'react';
const INITIAL_FILES = ['report.pdf', 'budget.xlsx', 'notes.txt', 'design.fig', 'contract.docx', 'roadmap.pdf'];
export function Attachments() {
const [files, setFiles] = useState(INITIAL_FILES);
const [failed, setFailed] = useState('budget.xlsx');
return (
<AiFieldInput
placeholder='Опишите, что сделать с файлами'
attachments={
files.length > 0
? files.map(file => (
<AiAttachment
key={file}
type={ATTACHMENT_TYPE.File}
state={file === failed ? ATTACHMENT_STATE.Error : ATTACHMENT_STATE.Default}
fileName={file}
tooltip={file === failed ? 'Не удалось загрузить' : file}
onRemove={() => setFiles(prev => prev.filter(name => name !== file))}
onRetry={() => setFailed('')}
/>
))
: undefined
}
/>
);
}Футер
import {
AiFieldInput,
AiFieldInputContextButton,
AiFieldInputEffortButton,
AiFieldInputModelButton,
AiFieldInputPlusButton,
AiFieldInputSettingsButton,
AiFieldInputVoiceButton,
SEND_STATE,
SendState,
} from '@cloud-ru/ds-ai-field-input';
import { useState } from 'react';
const PLUS_ITEMS = [
{ id: 'files', label: 'Файлы', description: 'Загрузить с устройства' },
{ id: 'skills', label: 'Скиллы', description: 'Добавить скилл в запрос' },
{ id: 'connectors', label: 'Коннекторы', description: 'Внешние источники данных' },
];
const SETTINGS_ITEMS = [
{ id: 'chat', label: 'Настройки чата', description: 'Название, папка и доступ' },
{ id: 'memory', label: 'Память', description: 'Что агент помнит о вас' },
];
const MODELS = [
{ id: 'gigachat-2-max', label: 'GigaChat 2 Max' },
{ id: 'gigachat-2-pro', label: 'GigaChat 2 Pro' },
{ id: 'gigachat-2-lite', label: 'GigaChat 2 Lite' },
];
const EFFORTS = [
{ id: 'low', label: 'Низкий' },
{ id: 'medium', label: 'Средний' },
{ id: 'high', label: 'Высокий' },
];
export function FooterActions() {
const [state, setState] = useState<SendState | undefined>(undefined);
const [model, setModel] = useState(MODELS[0]);
const [effort, setEffort] = useState(EFFORTS[2]);
const handleModelSelect = (id: string) => setModel(MODELS.find(item => item.id === id) ?? MODELS[0]);
const handleEffortSelect = (id: string) => setEffort(EFFORTS.find(item => item.id === id) ?? EFFORTS[2]);
return (
<AiFieldInput
defaultValue={[{ type: 'text', text: 'Сгенерируй план релиза' }]}
footerLeftActions={
<>
<AiFieldInputPlusButton
items={PLUS_ITEMS}
tooltip={{ content: 'Файлы, скиллы и коннекторы', shortcut: '⌘ /' }}
/>
<AiFieldInputSettingsButton items={SETTINGS_ITEMS} tooltip={{ content: 'Настройки' }} />
<AiFieldInputModelButton
label={model.label}
items={MODELS}
tooltip={{ content: 'Выбор модели' }}
onSelect={handleModelSelect}
/>
<AiFieldInputEffortButton
label={effort.label}
items={EFFORTS}
tooltip={{ content: 'Уровень усилий' }}
onSelect={handleEffortSelect}
/>
</>
}
footerRightActions={
<>
<AiFieldInputContextButton value={82} tooltip={{ content: 'Лимит: 82%' }} />
<AiFieldInputVoiceButton tooltip={{ content: 'Голосовой ввод' }} />
</>
}
send={{
state,
onClick: current => setState(current === SEND_STATE.Stop ? undefined : SEND_STATE.Stop),
}}
/>
);
}Выключенное поле
import { AiFieldInput } from '@cloud-ru/ds-ai-field-input';
export function Disabled() {
return <AiFieldInput disabled placeholder='Отправка сообщений недоступна' />;
}Ввод секрета
import { AiFieldInput, AiFieldInputValue } from '@cloud-ru/ds-ai-field-input';
import { useState } from 'react';
export function Secure() {
const [value, setValue] = useState<AiFieldInputValue>([]);
const [saved, setSaved] = useState(false);
return (
<AiFieldInput
secure
value={value}
onChange={setValue}
onSubmit={() => {
setSaved(true);
setValue([]);
}}
placeholder='Вставьте API-ключ'
disclaimer={saved ? 'Ключ отправлен' : undefined}
/>
);
}Ошибка
import { AiFieldInput, AiFieldInputValue } from '@cloud-ru/ds-ai-field-input';
import { useState } from 'react';
const MAX_LENGTH = 40;
function getLength(value: AiFieldInputValue) {
return value.reduce((sum, segment) => sum + ('text' in segment ? segment.text.length : 0), 0);
}
export function ErrorState() {
const [value, setValue] = useState<AiFieldInputValue>([
{ type: 'text', text: 'Сообщение длиннее допустимого лимита символов' },
]);
const length = getLength(value);
const tooLong = length > MAX_LENGTH;
return (
<AiFieldInput
value={value}
onChange={setValue}
onSubmit={() => setValue([])}
error={tooLong ? 'Сообщение слишком длинное' : undefined}
length={{ current: length, max: MAX_LENGTH }}
send={tooLong ? { state: 'disabled' } : undefined}
/>
);
}Props
AiFieldInput
Types
AiFieldInputProps| Prop | Type | Default | Required | Description |
|---|---|---|---|---|
attachments | ReactNode | — | no | Плитки вложений (`AiAttachment` из `@cloud-ru/ds-ai-attachment`). Ряд не рендерится, если слот пуст. |
attachmentsScrollStep | number | 92 | no | Шаг сдвига ряда вложений стрелкой, px. По умолчанию — одна плитка с зазором (92). |
banner | ReactNode | — | no | Слот над полем: `AiFieldBanner` или `AiFieldNotice`. Пока открыт список по `/` или `@`, на месте баннера стоит список. |
className | string | — | no | Доп. класс корня. |
data-test-id | string | ai-field-input | no | |
defaultValue | AiFieldInputValue | — | no | Начальное содержимое (uncontrolled). |
disabled | boolean | false | no | Выключенное поле: ввод недоступен, кнопки футера выключены, ряд вложений скрыт. |
disclaimer | ReactNode | — | no | Текст под полем. По умолчанию — дисклеймер из локали; `null` скрывает текст, отступ сохраняется. |
error | string | — | no | Текст ошибки. Непустой — поле в состоянии ошибки: красная заливка рамки, в фокусе красная обводка, под рамкой строка ошибки. Ввод и отправку не блокирует: доступностью отправки управляет `send`. На выключенном поле (`disabled`) ош ибка не показывается. В режиме `secure` текст не должен повторять значение. |
footerLeftActions | ReactNode | — | no | Слот левых действий футера. |
footerRightActions | ReactNode | — | no | Слот дополнительных правых действий футера (перед кнопкой отправки). |
length | FieldLength | — | no | Счётчик `current/max` в строке ошибки, например `3002/3000`. Показывается только вместе с `error`, когда ошибка связана с длиной значения. |
mentions | (AiFieldInputActionListItem | AiFieldInputActionListGroup)[] | — | no | Строки списка по `@`: ресурсы и сущности. Не заданы — список по `@` не открывается. |
onActionSelect | ((item: AiFieldInputActionListItem, trigger: SearchTrigger) => void) | — | no | Выбор строки списка по `/` или `@`: строка уже стоит в поле чипом. |
onChange | ((value: AiFieldInputValue) => void) | — | no | Изменение содержимого. |
onSubmit | ((value: AiFieldInputValue) => void) | — | no | Отправка: Enter без Shift, когда поиск по `/` или `@` не активен, или нажатие кнопки в состоянии `active`. Пока кнопка в `loading` или `stop`, не вызывается. |
placeholder | string | — | no | Подсказка в пустом поле. |
scrollButton | AiFieldInputScrollButton | — | no | Кнопка прокрутки к последнему сообщению над полем. Не задана — кн опки нет. |
searchPlaceholder | AiFieldInputSearchPlaceholder | — | no | Подсказки в поиске после `/` и `@`. Не заданный ключ — текст из локали («Введите название» / «Type a name»). |
secure | boolean | false | no | Ввод чувствительных данных: пароля, API-ключа, токена. Вместо редактора — однострочное поле `type="password"`: значение скрыто, не копируется и не вырезается. В футере слева — кнопка «глаз», которая показывает и снова скрывает значение; после отправки значение снова скрыто. Чипов, проверки орфографии, автозамены и списков по `/` и `@` нет: эти знаки вводятся как обычный текст. При включении `secure` из значения убираются чипы, остаётся текст. При выключении значение очищается: пока родитель не пришлёт новое значение, редактор секрет не показывает. По умолчанию `false`. |
send | AiFieldInputSend | — | no | Кнопка отправки: состояние и нажатие. |
skills | (AiFieldInputActionListItem | AiFieldInputActionListGroup)[] | — | no | Строки списка по `/`: команды и скиллы. Не заданы — список по `/` не открывается. |
value | AiFieldInputValue | — | no | Содержимое поля (controlled). |
Types
AiFieldInputProps
AiFieldInputActionListGroup
AiFieldInputActionListItem
AiFieldInputScrollButton
AiFieldInputSearchPlaceholder
AiFieldInputSend
AiFieldInputValue
Related props
FieldLength
AiFieldInputActionList
Types
AiFieldInputActionListProps| Prop | Type | Default | Required | Description |
|---|---|---|---|---|
className | string | — | no | Доп. класс корня. |
data-test-id | string | — | no | |
items | (AiFieldInputActionListItem | AiFieldInputActionListGroup)[] | — | yes | Строки и группы строк. |
onClose | (() => void) | — | no | Нажатие Escape. |
padding | boolean | — | no | Отступ 8 со всех сторон; без него — только сверху и снизу. По умолчанию `false`. |
Types
AiFieldInputActionListProps
AiFieldInputActionListGroup
AiFieldInputActionListItem
Плитки вложений — AiAttachment из @cloud-ru/ds-ai-attachment.
Адаптивность
Раскладка берётся из AdaptiveProvider (@cloud-ru/ds-adaptive), пропа раскладки нет.
| Часть | Desktop | Mobile |
|---|---|---|
| Ряд вложений | стрелки при переполнении, полоса скрыта | свайп, полоса видна при листании |
| Крестик плитки | xs с подложкой, при наведении или фокусе | s с подложкой, виден всегда |
| Подсказка плитки | при наведении | нет |
| Высота текста | до 10 строк, дальше прокрутка | до 5 строк, дальше прокрутка |
| Списки кнопок футера | выпадающий список над кнопкой | шторка снизу по высоте списка; со searchable у кнопки модели — на весь экран |
/ и @ в тексте | открывают список над полем | печатаются как обычный текст |
openActionList из пункта меню кнопки | список над полем | список заменяет пункты в той же шторке; первая строка — возврат «Назад» |
openActionList из своей кнопки | список над полем | список в отдельной шторке |
Размер баннера в слоте выбирает потребитель.
На mobile скиллы и упоминания добавляются только через openActionList, например из пунктов меню кнопки добавления. Строки с переходом открывают следующий уровень в той же шторке, первой строкой уровня стоит возврат («Назад» или backLabel). Высота шторки подстраивается под список. Выбор строки закрывает шторку, ставит чип и курсор за ним.