CodeField

Компонент CodeField используется для ввода одноразовых OTP-кодов.

[!NOTE] Визуально код разделен на ячейки, но ввод выполняется через один нативный input. Благодаря этому компонент поддерживает вставку полного кода, системное автозаполнение из СМС, опциональный WebOTP и стандартную работу с HTML-формами.

Быстрый старт​

Live Editor
Result
Open in CodeSandbox

Без свойства value компонент работает в uncontrolled-режиме и самостоятельно хранит введенный код.

Размер​

Размер задается с помощью свойства size. Ширина компонента также может регулироваться при помощи свойства width:

Live Editor
Result
Open in CodeSandbox

Форма компонента и длина кода​

Форма компонента задается с помощью свойства shape, а длина кода с помощью codeLength:

Live Editor
Result
Open in CodeSandbox

Допустимые символы​

За допустимые символы для ввода отвечает свойство allowedSymbols. Задается строкой или регулярным выражением. Библиотека экспортирует наиболее используемые вариации допустимых символов: import { ONLY_DIGITS_PATTERN, ONLY_CHARS_PATTERN, ONLY_DIGITS_AND_CHARS_PATTERN } from '@salutejs/sdds-platform-ai';

Поведение при вводе​

Поведение ячейки при вводе некорректного символа регулируется свойством itemErrorBehavior. Когда введено codeLength символов, срабатывает колбэк onFullCodeEnter. Он вызывается как после ручного ввода, так и после вставки, системного автозаполнения или WebOTP. При неверном вводе кода поведение компонента управляется свойством codeErrorBehavior. Индикация ошибки задается с помощью флага isError и колбэка setIsError:

Live Editor
Result
Open in CodeSandbox

Тип клавиатуры на мобильных устройствах​

Свойство inputMode управляет типом виртуальной клавиатуры, отображаемой на мобильных устройствах. По умолчанию используется numeric — открывается числовая клавиатура. Значение text открывает стандартную текстовую клавиатуру:

Live Editor
Result
Open in CodeSandbox

Стрелки и клавиша Delete не изменяют позицию ввода: активная ячейка управляется самим компонентом. Для удаления последнего символа используется Backspace.

Нативный input и HTML-формы​

Внутри CodeField находится один нативный input, который хранит полное значение кода. Декоративные ячейки не участвуют в таб-навигации. Переданный ref указывает на этот HTMLInputElement.

Свойства name, form, required, autoComplete, inputMode и ARIA-атрибуты применяются к нативному полю. Поэтому значение можно получить через FormData, а компонент можно связать с подписью для скринридеров:

Live Editor
Result
Open in CodeSandbox

Работа с OTP-кодом из СМС​

По умолчанию CodeField использует autoComplete="one-time-code" для системного автозаполнения.

Системное автозаполнение​

Браузер или операционная система могут распознать код в СМС и показать его над клавиатурой либо в меню автозаполнения. Этот сценарий работает через нативный input и не требует поддержки WebOTP. Формат распознаваемого сообщения зависит от браузера и операционной системы.

Web OTP API​

Web OTP API используется как дополнительный механизм в поддерживающих его мобильных браузерах. По умолчанию WebOTP отключен. Чтобы разрешить компоненту запросить код через navigator.credentials.get(), передайте свойство enableWebOTP:

Live Editor
Result
Open in CodeSandbox

Для WebOTP страница должна работать в безопасном контексте, а последняя строка СМС должна содержать домен страницы и код:

Ваш код подтверждения: 123456.

@example.com #123456

Первая и вторая (пустая) строки являются необязательными и предназначены для удобства чтения пользователем. Последняя строка обязательна и должна состоять из:

  • доменной части URL-адреса сайта, который вызвал API; она начинается с символа @;
  • OTP-кода, перед которым стоит символ #.

После успешной автоподстановки компонент вызывает onChange, а при заполнении всех ячеек — onFullCodeEnter.

Свойство autoComplete управляет только нативным автозаполнением. Например, autoComplete="off" отключает системную подсказку, но не влияет на явно включенный enableWebOTP.

API​