Smart-код страны

<sf-country-code> — телефонное поле с кнопкой выбора страны: флаг и код страны стоят перед номером, а маска подстраивается под выбранную страну. Оно собирает разметку кода страны из атрибутов. Для телефона без выбора страны хватит поля ввода с маской.

Пример

<sf-country-code
  label="Телефон"
  name="phone"
  required="true"
  iso2="RU"
  value="+7 903 123-45-67"
  use-mask="true"
  hint="Выберите страну и введите номер."
></sf-country-code>

Применение

Подпись и подсказка

label — видимая подпись поля; без него поле подписано английским словом «Label», поэтому задавайте его всегда. hint — пояснение под полем, placeholder — пример номера в пустом поле. required делает номер обязательным.

Выбор страны и фиксированный код

iso2 задаёт начальную страну двухбуквенным кодом, dial-code — телефонным кодом. По умолчанию пользователь может сменить страну кнопкой с флагом. multi-country="false" оставляет страну фиксированной: список не создаётся, код остаётся перед номером.

<div class="grid grid-col-1 md:grid-col-2 gap-3">
  <sf-country-code label="Выбор страны" iso2="RU" value="+7 " use-mask="true"></sf-country-code>
  <sf-country-code label="Фиксированная страна" iso2="TR" dial-code="+90" value="+90 " multi-country="false"></sf-country-code>
</div>

Маска номера

use-mask="true" включает маску номера. Маска берётся из данных выбранной страны и меняется вместе с ней; use-country-masks="false" отключает маски стран, и тогда действует общий шаблон из mask-pattern. Маска помогает вводить номер, но существование номера не проверяет: это задача приложения и сервера.

Размер

size выбирает ступень размерной шкалы: 1/2, 1 или 2. Подпись, поле и подсказка сохраняют одну структуру на всех ступенях.

<div class="grid grid-col-1 gap-2">
  <sf-country-code label="Размер 1/2" size="1/2" iso2="RU" multi-country="false"></sf-country-code>
  <sf-country-code label="Размер 1" size="1" iso2="RU" multi-country="false"></sf-country-code>
  <sf-country-code label="Размер 2" size="2" iso2="RU" multi-country="false"></sf-country-code>
</div>

Значение в форме

Номер хранит обычный <input type="tel"> с переданными name, form и required, поэтому он попадает в FormData, проходит нативную проверку обязательности, а сброс формы возвращает исходные номер и страну.

<form class="grid gap-3">
  <sf-country-code label="Телефон" name="phone" required="true" iso2="RU" value="+7 9991234567" hint="Измените номер или страну, затем восстановите исходное значение."></sf-country-code>
  <div class="flex flex-wrap gap-2">
    <button class="sf-button sf-button--default sf-button--primary sf-button--size-1" type="submit"><span class="sf-button-text-container">Проверить заполнение</span></button>
    <button class="sf-button sf-button--outline sf-button--on-surface sf-button--size-1" type="reset"><span class="sf-button-text-container">Сбросить</span></button>
  </div>
</form>

Свой набор стран

Свойство countries принимает массив объектов с полями iso2, code или dialCode, label и необязательным maskPattern. Для известных кодов ISO пропущенные поля дополняются встроенным справочником. max-items ограничивает число стран в списке. Присваивайте свойство после регистрации элемента — await customElements.whenDefined('sf-country-code').

<sf-country-code label="Телефон" hint="Выберите страну: формат номера изменится." iso2="DE" value="+49 1511234567"></sf-country-code>
<script>
(() => {
  const field = document.currentScript.previousElementSibling;
  customElements.whenDefined('sf-country-code').then(() => {
    field.countries = [
      {iso2: 'DE', code: '+49', label: 'Германия (+49)', maskPattern: '+49 000 0000000'},
      {iso2: 'RU', code: '+7', label: 'Россия (+7)', maskPattern: '+7 000 000-00-00'},
    ];
    field.setAttribute('use-mask', 'true');
  });
})();
</script>

Флаги и язык

Флаг по умолчанию — символ эмодзи страны. flag-base задаёт папку с изображениями флагов: компонент берёт из неё файл <iso2>.svg.

Названия стран и собственные подписи поля следуют языку страницы: на странице с lang="ru" — русские, на любой другой — английские. locale="ru" или locale="en" задаёт язык явно.

Оформление

root-class добавляет корню утилиты Framework: поверхность, отступы и радиус контейнера меняются без своих стилей, а само поле сохраняет системный радиус.

<div class="grid gap-3">
  <sf-country-code label="Телефон" hint="Поверхность контейнера и внутренний отступ." iso2="RU" root-class="p-2 bg-surface-container radius-surface"></sf-country-code>
  <sf-country-code label="Телефон" hint="Приподнятая поверхность и отступ побольше." iso2="RU" root-class="p-3 bg-surface-2 radius-surface"></sf-country-code>
</div>

Состояние из кода и событие change

Когда номер или страна зафиксированы, нативное событие change внутреннего поля всплывает через <sf-country-code>; detail у него нет. Номер читайте из event.target.value, а страну и код — из свойства state: value, iso2, dialCode, open и disabled.

setState() принимает те же поля: iso2 меняет страну и сохраняет местную часть номера, value заменяет номер, open открывает список. Смена номера или страны из setState() тоже отправляет change.

const phone = document.querySelector('sf-country-code[name="phone"]');
phone.addEventListener('change', () => {
  const {value, iso2, dialCode} = phone.state;
  savePhone({value, iso2, dialCode});
});
phone.setState({iso2: 'KZ'});

Доступность

• Задайте видимую подпись в label: компонент связывает её с полем номера.
• Кнопка с флагом открывает список стран с одиночным выбором. Стрелки, Home, End и набор первых букв перемещают по списку, не меняя номер; Enter или Space выбирают страну, Escape закрывает список без выбора. В обоих случаях фокус возвращается на кнопку.
• Tab выходит из компонента и не удерживается в списке. Недоступное поле список не открывает.

Справочник API

Раздел собран из манифеста компонента выпуска ui-106d5901f8c3 и обновляется вместе с выпуском. Чтобы исправить описание, исправьте манифест.

Каждому атрибуту соответствует свойство элемента с тем же именем в camelCase: search-placeholder — searchPlaceholder. Свойство атрибута template называется templateName.

Атрибуты

• size — string, по умолчанию 1, значения: 1/2, 1, 2.
• label — string, по умолчанию пусто.
• required — boolean, по умолчанию false. Нативное обязательное поле телефона; одного префикса страны недостаточно для выполнения требования.
• name — string, по умолчанию пусто. Нативное имя поля ввода, используемое FormData и отправкой формы.
• form — string, по умолчанию пусто. Необязательный id нативной формы-владельца, если поле находится вне её.
• hint — string, по умолчанию пусто.
• value — string, по умолчанию пусто.
• placeholder — string, по умолчанию +7(___)___-__-__.
• disabled — boolean, по умолчанию false.
• open — boolean, по умолчанию false.
• locale — string, по умолчанию пусто. Язык названий стран и собственных текстов поля: ru или en. Если не задан, следует языку страницы: русский на русской странице, иначе английский.
• use-mask — boolean, по умолчанию false.
• use-country-masks — boolean, по умолчанию true.
• show-code — boolean, по умолчанию true.
• mask-style — string, по умолчанию native.
• multi-country — boolean, по умолчанию true.
• iso2 — string, по умолчанию пусто.
• dial-code — string, по умолчанию пусто.
• mask-pattern — string, по умолчанию пусто.
• flag-base — string, по умолчанию пусто.
• lazy-flags — boolean, по умолчанию true.
• show-mask-placeholder — boolean, по умолчанию false.
• mask-placeholder-char — string, по умолчанию _.
• max-items — number, по умолчанию 0.

Прежние имена:

Методы

• setState(nextState?: object) — возвращает boolean. Применяет disabled, open (или active), value, iso2 и dialCode к отрисованному полю; установка value отправляет нативные input и change от внутреннего input. Возвращает true, если применено, и false до отрисовки.

События

Все события приходят на сам элемент и всплывают. Общие события базового элемента перечислены в главе Жизненный цикл → Этапы.

• change — detail: null. Номер телефона или страна зафиксированы; нативное событие всплывает от внутреннего input, который является его целью. detail не передаётся. Имя для привязки.

Доступность

• Доступное имя: рекомендуется.
• Клавиши: Tab, Enter, Space, Escape, ArrowDown, ArrowUp, Home, End, поиск по первым буквам.
• Фокус: Кнопка кода страны открывает список с одиночным выбором (listbox). Стрелки, Home, End и поиск по первым буквам перемещают фокус, не меняя телефон; Enter/Space подтверждают выбор, Escape отменяет. При закрытии подтверждением или по Escape фокус возвращается на кнопку; Tab уводит фокус без ловушки. Отключённые поля не открываются.

Минимальная разметка

<sf-country-code></sf-country-code>

Источник

• simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/smart/country-code
• simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/rule/rule.json#name=cl-country-code