FieldMask

Обёртка над FieldText из @cloud-ru/ds-fields с предустановленной маской ввода на react-imask. Маска, плейсхолдер и inputMode выбираются по пропу mask — поле само форматирует ввод и отдаёт значение через onChange(value, mask).

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

Нужен ввод строго форматированного значения: идентификатор (UUID), код, паспорт, СНИЛС, IPv4-адрес.
Хочется готовую маску без ручной настройки react-imask.

Когда не нужен FieldMask:

Произвольный текст без формата — FieldText напрямую.
Телефон с выбором страны — FieldPhone.

Анатомия

Mask

Предустановленный набор масок (проп mask, константа MASK):

uuid — XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX (hex).
code — XXXX (числовой код).
passport — XXXX XXXXXX.
snils — XXXXXX-XXX XX.
ip-v4-address — 0[00].0[00].0[00].0[00].
ip-v4-address-with-mask — IPv4 с CIDR-суффиксом /NN.

Size (default `m`)

Размер поля наследуется от FieldText:

s — компактный.
m — средний.
l — крупный.

Примеры использования

Типы масок

Типы масокРазные предустановленные маски в одном ряду.

UUID

СНИЛС

IPv4

tsx

import { FieldMask, MASK } from '@cloud-ru/ds-uikit-product-fields-predefined';

export function FieldMaskMasks() {
  return (
    <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap', alignItems: 'flex-start' }}>
      <FieldMask label='UUID' mask={MASK.Uuid} />
      <FieldMask label='СНИЛС' mask={MASK.Snils} />
      <FieldMask label='IPv4' mask={MASK.IpV4Address} />
    </div>
  );
}

Controlled

ControlledКонтролируемое значение через value + onChange.

Код

value: —

tsx

import { FieldMask, MASK } from '@cloud-ru/ds-uikit-product-fields-predefined';
import { useState } from 'react';

export function FieldMaskControlled() {
  const [value, setValue] = useState('');

  return (
    <FieldMask
      label='Код'
      mask={MASK.Code}
      value={value}
      onChange={next => setValue(next)}
      caption={`value: ${value || '—'}`}
    />
  );
}

Props

Types

PropsFieldMaskProps

Prop	Type	Default	Required	Description
`allowMoreThanMaxLength`	`boolean`	`false`	no	Разрешить ввод свыше `maxLength` символов (счётчик продолжит расти).
`autoComplete`	`string \| boolean`	`false`	no	Включен ли автокомплит для поля
`autoFocus`	`boolean`	`false`	no	Включен ли авто-фокус для поля
`background`	`boolean`	`true`	no	Фон поля (acrylic)
`caption`	`string`	—	no	Вторичная подпись справа
`className`	`string`	—	no	CSS-класс CSS-класс корня `FieldDecorator`
`data-test-id`	`string`	—	no
`defaultValue`	`string`	—	no	Начальное значение (uncontrolled-режим)
`disabled`	`boolean`	`false`	no	Поле выключено Является ли поле деактивированным
`elementAfter`	`FieldElementSlot`	—	no	Слот справа (кнопка / селект с опциональным выпадающим списком)
`elementBefore`	`FieldElementSlot`	—	no	Слот слева (кнопка / селект с опциональным выпадающим списком)
`error`	`string`	—	no	Ошибка (приоритетнее `hint`; форсит `validationState=error`)
`fieldClassName`	`string`	—	no	CSS-класс оболочки поля ввода
`hint`	`string`	—	no	Подсказка
`iconAfter`	`ReactNode`	—	no	Иконка справа от строки ввода
`iconBefore`	`ReactNode`	—	no	Иконка слева от строки ввода
`id`	`string`	—	no	Значение html-атрибута id
`innerRef`	`Ref<HTMLDivElement>`	—	no	Ref на корневой DOM-элемент
`innerTestIds`	`{ shell?: string; input?: string; } \| undefined`	—	no	Идентификаторы внутренних слотов — оболочки и строки ввода. Нужны компонентам, которые рендерят `FieldCombo` под собственным именем (`FieldText`): их e2e адресует свои слоты, а не слоты `FieldCombo`.
`label`	`string`	—	no	Заголовок
`labelFor`	`string`	—	no	HTML-атрибут `for` для `<label>`
`labelTooltip`	`QuestionTooltipProps`	—	no	Подсказка (question-tooltip) у заголовка
`layoutPresets`	`Partial<Record<LayoutType, Partial<{ autoFocus: boolean; }>>>`	—	no	Переопределение адаптивных дефолтов по раскладке. Участвует `autoFocus`: на mobile он выключен (открывает клавиатуру без действия). Вернуть на mobile — `layoutPresets={{ mobile: { autoFocus: true } }}`.
`length`	`FieldLength`	—	no	Счётчик длины `current/max`
`mask`	`"code" \| "ip-v4-address" \| "ip-v4-address-with-mask" \| "passport" \| "snils" \| "uuid"`	—	yes	Предустановленная маска поля
`max`	`number`	—	no	Максимальное значение поля
`maxLength`	`number`	—	no	Максимальная длина вводимого значения
`min`	`number`	—	no	Минимальное значение поля
`name`	`string`	—	no	Значение html-атрибута name
`onBlur`	`FocusEventHandler<HTMLInputElement>`	—	no	Колбек обработки потери фокуса
`onChange`	`((value: string, mask: InputMask<Record<string, unknown>>) => void)`	—	no	Колбек смены значения; вторым аргументом — экземпляр маски imask
`onClearButtonClick`	`(() => void)`	—	no	Колбек клика по кнопке очистки
`onClick`	`MouseEventHandler<HTMLInputElement>`	—	no	Колбек обработки клика
`onCopyButtonClick`	`(() => void)`	—	no	Колбек после копирования значения в буфер
`onFocus`	`FocusEventHandler<HTMLInputElement>`	—	no	Колбек обработки получения фокуса
`onKeyDown`	`KeyboardEventHandler<HTMLInputElement>`	—	no	Колбек обработки начала нажатия клавиши клавиатуры
`onMouseDown`	`MouseEventHandler<HTMLInputElement>`	—	no	Колбек обработки нажатия кнопки мыши
`onPaste`	`ClipboardEventHandler<HTMLInputElement>`	—	no	Колбек обработки вставки значения
`outline`	`boolean`	`true`	no	Разделитель между основным полем и слотами `elementBefore` / `elementAfter`
`pattern`	`string`	—	no	Регулярное выражение валидного инпута
`placeholder`	`string`	—	no	Значение плейсхолдера
`postfix`	`ReactNode`	—	no	Постфикс (текст или нода)
`prefix`	`ReactNode`	—	no	Префикс (текст или нода)
`prefixIcon`	`ReactNode`	—	no	Ведущая иконка. @deprecated Используйте `iconBefore` — он приоритетнее, если заданы оба.
`readonly`	`boolean`	`false`	no	Только для чтения Является ли поле доступным только для чтения
`required`	`boolean`	—	no	Показать знак обязательности `*`
`showClearButton`	`boolean`	`true`	no	Показывать кнопку очистки значения (как в Search)
`showCopyButton`	`boolean`	`true`	no	Показывать кнопку копирования значения (только при `readonly = true` и непустом `value`)
`showHintIcon`	`boolean`	—	no	Отображение статус-иконки у подсказки (по умолчанию `true`)
`size`	`"l" \| "m" \| "s"`	`m`	no	Размер
`spellCheck`	`boolean`	`true`	no	Значение атрибута spellcheck (проверка орфографии)
`step`	`string \| number`	—	no	Максимальное значение поля
`tabIndex`	`number`	`0`	no	Значение атрибута tab-index
`type`	`"email" \| "number" \| "password" \| "tel" \| "text" \| "url"`	—	no	Тип инпута
`validationState`	`"default" \| "error" \| "success" \| "warning"`	—	no	Состояние валидации
`value`	`string`	—	no	Значение поля (controlled-режим)

Unions

Related props

`FieldElementButtonProps`interface

Prop	Type	Default	Required	Description
`action`	`string \| number \| boolean \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal \| null \| undefined`	—	yes	Содержимое (иконка и т.д.)
`className`	`string \| undefined`	—	no	CSS-класс (передаётся обёрткой `Droplist` / `PopoverPrivate` на триггер)
`data-test-id`	`string \| undefined`	—	no	data-test-id кнопки-слота
`disabled`	`boolean \| undefined`	—	no	Деактивировано
`loading`	`boolean \| undefined`	—	no	Состояние загрузки
`onClick`	`(() => void) \| undefined`	—	no	Обработчик клика
`onKeyDown`	`((event: KeyboardEvent<HTMLButtonElement>) => void) \| undefined`	—	no	Обработчик нажатия клавиш (передаётся обёрткой `Droplist` для ArrowDown/ArrowUp)
`open`	`boolean \| undefined`	—	no	Контролируемое состояние раскрытия (используется обёрткой `FieldElementButtonList`). Если задано — шеврон отражает это значение; иначе кнопка управляет шевроном сама.
`size`	`"l" \| "m" \| "s"`	—	no	Размер (совпадает с размером поля)
`tabIndex`	`number \| undefined`	—	no	HTML tabIndex (`-1` — исключить кнопку из tab-order, фокус по Tab уходит в поле)
`variant`	`"after" \| "before"`	—	yes	Положение относительно поля
`withDropdownList`	`boolean \| undefined`	—	no	Показать шеврон раскрытия

`FieldElementSlot`interface

Prop	Type	Default	Required	Description
`action`	`string \| number \| boolean \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal \| null \| undefined`	—	yes	Содержимое (иконка и т.д.)
`className`	`string \| undefined`	—	no	CSS-класс (передаётся обёрткой `Droplist` / `PopoverPrivate` на триггер)
`data-test-id`	`string \| undefined`	—	no	data-test-id кнопки-слота
`disabled`	`boolean \| undefined`	—	no	Деактивировано
`droplist`	`FieldElementDroplistProps \| undefined`	—	no	Встроенный выпадающий список (действия / выбор) на `@cloud-ru/ds-list` `Droplist`
`loading`	`boolean \| undefined`	—	no	Состояние загрузки
`onClick`	`(() => void) \| undefined`	—	no	Обработчик клика
`size`	`"l" \| "m" \| "s"`	—	no	Размер (совпадает с размером поля)
`tabIndex`	`number \| undefined`	—	no	HTML tabIndex (`-1` — исключить кнопку из tab-order, фокус по Tab уходит в поле)
`withDropdownList`	`boolean \| undefined`	—	no	Показать шеврон раскрытия

Prop	Type	Default	Required
`desktop`	`any`	—	no
`desktopSmall`	`any`	—	no
`mobile`	`any`	—	no
`tablet`	`any`	—	no

Prop	Type	Default	Required	Description
`current`	`number`	—	yes	Текущая длина текста
`max`	`number \| undefined`	—	no	Максимально допустимая длина

`QuestionTooltipProps`interface

Prop	Type	Default	Required	Description
`children`	`ReactNode \| ChildrenFunction`	—	no	Триггер поповера (подробнее читайте ниже)
`className`	`string \| undefined`	—	no
`closeOnPopstate`	`boolean \| undefined`	—	no	Закрывать ли поповер при переходе по истории браузера
`data-test-id`	`string \| undefined`	—	no
`disableMaxWidth`	`boolean \| undefined`	—	no	Отключение ограничения ширины тултипа
`disableSpanWrapper`	`boolean \| undefined`	—	no	Отключает для `isValidElement` внешнюю обертку триггера <br/> Пригодится для элементов с `position: absolute` <br/> Работает для триггеров, которые умеют отдать свою DOM-ноду: нативные элементы, `forwardRef`-компоненты и компоненты, помеченные `withInnerRefSupport` из `@cloud-ru/ds-utils`. Остальные всё равно получают `<span>` — без ноды поповеру не от чего считать позицию; в dev-режиме об этом печатается предупреждение.
`fallbackPlacements`	`Placement[] \| undefined`	—	no	Цепочка расположений которая будет применяться к поповеру от первого к последнему если при текущем он не влезает.
`hoverDelayClose`	`number \| undefined`	—	no	Задержка закрытия по ховеру
`hoverDelayOpen`	`number \| undefined`	—	no	Задержка открытия по ховеру
`offset`	`number \| undefined`	—	no	Отступ поповера от его триггер-элемента (в пикселях).
`onOpenChange`	`((isOpen: boolean) => void) \| undefined`	—	no	Колбек отображения компонента. Срабатывает при изменении состояния open.
`open`	`boolean \| undefined`	—	no	Управляет состоянием показан/не показан.
`placement`	`"bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "left-end" \| "left-start" \| "right" \| "right-end" \| "right-start" \| "top" \| "top-end" \| "top-start"`	—	no	Положение поповера относительно своего триггера (children).
`size`	`"s" \| "xs"`	—	no	Размер
`tabIndex`	`number \| undefined`	—	no	Tab index для кнопки-триггера
`tip`	`string \| number \| boolean \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal \| null \| undefined`	—	yes	Содержимое тултипа (текст или разметка)
`tooltipClassname`	`string \| undefined`	—	no	CSS-класс контейнера подсказки
`trigger`	`"click" \| "clickAndFocusVisible" \| "focus" \| "focusVisible" \| "hover" \| "hoverAndFocus" \| "hoverAndFocusVisible"`	—	no	Условие отображения поповера: <br/> - `click` - открывать по клику <br/> - `hover` - открывать по ховеру <br/> - `focusVisible` - открывать по focus-visible <br/> - `focus` - открывать по фокусу <br/> - `hoverAndFocusVisible` - открывать по ховеру и focus-visible <br/> - `hoverAndFocus` - открывать по ховеру и фокусу <br/> - `clickAndFocusVisible` - открывать по клику и focus-visible
`triggerClassName`	`string \| undefined`	—	no	CSS-класс триггера
`triggerLabel`	`string \| undefined`	—	no	Доступное имя для иконки-триггера
`triggerRef`	`ForwardedRef<HTMLElement \| ReferenceType \| null> \| undefined`	—	no	Ref ссылка на триггер

Types

FieldMaskProps

Unions

Адаптивность

autoFocus на mobile выключается (наследуется из @cloud-ru/ds-fields) — автофокус там открывает экранную клавиатуру без действия пользователя. Раскладка читается из AdaptiveProvider (@cloud-ru/ds-adaptive); отдельного пропа layoutType нет. Вернуть автофокус на mobile — пропом layoutPresets:

<FieldMask mask='uuid' autoFocus layoutPresets={{ mobile: { autoFocus: true } }} />

size от раскладки не зависит — задаётся пропом (по умолчанию m) одинаково на всех раскладках.

Storybook

Открыть в Storybook →

FieldMask

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

Анатомия

Mask

Size (default m)

Примеры использования

Типы масок

Controlled

Props

Types

Unions

Maskunion

Related props

FieldElementButtonPropsinterface

FieldElementSlotinterface

FieldLayoutPresetsinterface

FieldLengthinterface

QuestionTooltipPropsinterface

Sizeunion

Typeunion

ValidationStateunion

Types

FieldMaskProps

Unions

Mask

Related props

FieldElementButtonProps

FieldElementSlot

FieldLayoutPresets

FieldLength

QuestionTooltipProps

Size

Type

ValidationState

Адаптивность

Storybook

Size (default `m`)

`Mask`union

`FieldElementButtonProps`interface

`FieldElementSlot`interface

`FieldLayoutPresets`interface

`FieldLength`interface

`QuestionTooltipProps`interface

`Size`union

`Type`union

`ValidationState`union