PhoneField

Паттерны

Контактная форма с учётом страны

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

• продукт хранит международные номера телефонов

Заметки о композиции:

• держите выбор страны видимым
• нормализуйте значения при отправке
• показывайте в триггере компактное значение (здесь флаг), а полное название страны — в списке

Компромиссы:

• лучшая корректность для международных номеров
• более сложное поведение формы, чем у обычного текстового поля

import {
  Label,
  PhoneField,
  PhoneFieldInput,
  PhoneFieldSelect,
  PhoneFieldSelectCombobox,
  PhoneFieldSelectHiddenSelect,
  PhoneFieldSelectIcon,
  PhoneFieldSelectListbox,
  PhoneFieldSelectOption,
  PhoneFieldSelectValue,
} from '@vega-ui/react';

Ввод со строгой маской

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

• формат ввода должен быть жёстко ограничен

Заметки о композиции:

• strictMask включён по умолчанию: код страны из code зафиксирован, и принимаются только его цифры
• перепроверьте перемещение каретки и вставку

Компромиссы:

• более чистый отформатированный ввод
• менее снисходительное редактирование

import { Label, PhoneField, PhoneFieldInput } from '@vega-ui/react';
import { useId } from 'react';

export default function SimpleIsoBasedPhoneMask() {
  const id = useId();

  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-3)', width: '100%', maxWidth: 280 }}>
      <Label htmlFor={id}>Mobile number</Label>
      <PhoneField code='US'>
        <PhoneFieldInput id={id} name='phone' autoComplete='tel' placeholder='+1 201 555-0123' />
      </PhoneField>

Терпимая вставка

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

• пользователи часто вставляют номера телефонов из внешних систем

Заметки о композиции:

• используйте strictMask={false}
• вставленный номер с другим кодом страны переключает страну, и onChangeCode сообщает об этом
• нормализуйте на границе функции

Компромиссы:

• лучшая терпимость к вставке
• более слабые гарантии форматирования внутри поля

import {
  Label,
  PhoneField,
  PhoneFieldInput,
  PhoneFieldSelect,
  PhoneFieldSelectCombobox,
  PhoneFieldSelectIcon,
  PhoneFieldSelectListbox,
  PhoneFieldSelectOption,
  PhoneFieldSelectValue,
  Text,
} from '@vega-ui/react';

Сравнение

Быстрое правило выбора

Выбирайте PhoneField, когда значение телефона и выбор страны должны вести себя как одно согласованное поле.

PhoneField или TextField

Используйте PhoneField, когда:

• важно форматирование телефона с учётом страны
• интерфейсу нужна маска или выбор страны

Используйте TextField, когда:

• значение — просто текстовый ввод

PhoneField или Select + TextField

Используйте PhoneField, когда:

• выбор страны и форматирование телефона должны оставаться связанными
• во всём приложении нужно переиспользовать один канонический контракт ввода телефона

Используйте отдельные элементы, когда:

• продукт намеренно разделяет выбор страны и ввод телефона
• маска, валидация и смена страны не должны разделять один жизненный цикл поля

Выбирайте этот компонент, когда

• важно поведение маски
• выбор страны меняет валидацию или форматирование
• продукт рассматривает ввод телефона как одно семейство поля

Не выбирайте этот компонент, когда

• форматирование телефона не важно
• достаточно обычного текстового поля
• выбор страны должен быть полностью независим от поля ввода

Решение проблем

Смена страны неправильно переформатирует номер

Симптом

После смены выбранной страны видимый номер остаётся в невалидном или устаревшем формате.

Вероятная причина

Состояние страны и логика валидации не синхронизированы в родительском сценарии.

Как проверить

• переключите страну при уже введённом значении
• сравните поведение отображаемого и сохраняемого значения

Исправление

• рассматривайте страну и значение как один сценарий интеграции
• нормализуйте значение после смены страны

Вставка кажется слишком строгой

Симптом

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

Вероятная причина

strictMask слишком строг для реального источника ввода.

Как проверить

• протестируйте вставку на реалистичных строках с номерами

Исправление

• рассмотрите strictMask={false} для терпимых сценариев
• нормализуйте каноническое значение после ввода

Выбор страны выглядит правильно, но семантика формы слабая

Симптом

Визуально интерфейс работает, но выбранная страна не попадает в обычные сценарии формы.

Вероятная причина

Отсутствует PhoneFieldSelectHiddenSelect.

Как проверить

• изучите поведение нативной отправки формы

Исправление

• отрендерите PhoneFieldSelectHiddenSelect внутри композиции select