Поле телефона
Поле телефона принимает международный номер: выбор кода страны, соединённый с полем номера, которое форматируется при вводе. Это голое поле; подпись, подсказку и ошибки даёт обёртка
<tk-field label="Phone number" required> <tk-phone-input name="phone" country="US"></tk-phone-input> </tk-field>
Анатомия
| Часть | Что это |
|---|---|
tk-phone-input |
сам элемент; две остановки Tab: код страны и номер |
part field |
рамка вокруг обеих частей |
part prefix |
компактный |
part number |
нативный <input type="tel"> для номера внутри страны |
Подпись, подсказку и сообщение об ошибке даёт country-label.
Размеры
<tk-phone-input aria-label="Medium phone input" country="GB"></tk-phone-input> <tk-phone-input aria-label="Large phone input" country="GB" size="large"></tk-phone-input>
size |
Высота |
|---|---|
medium (по умолчанию) |
32px |
large |
36px |
Поле телефона занимает всю ширину контейнера.
Состояния
<tk-phone-input aria-label="Office phone" value="+12133734253" readonly></tk-phone-input> <tk-phone-input aria-label="Office phone" value="+12133734253" disabled></tk-phone-input>
<tk-field label="Phone number" error="Enter a phone number, like 07700 900 982"> <tk-phone-input name="phone" country="GB" value="+44770"></tk-phone-input> </tk-field>
При наведении поле не меняется. Фокус на любой из частей подсвечивает общую рамку, и она утолщается внутрь.
readonly: номер можно прочитать и скопировать, но не изменить.disabled: на обе части нельзя перейти, их нельзя изменить, ничего не отправляется.- Ошибка: задайте
errorна Field. Рамка становится красной и остаётся красной в фокусе. - Обязательность: задайте
requiredна Field; он добавит звёздочку и сделает номер обязательным.
Формат и значение
- Номер форматируется при вводе так, как его принято записывать в каждой стране. Чтобы
оставить цифры как есть, задайте свойству
formatзначениеfalseиз кода; атрибутом форматирование не выключить. - Если ввести код через
+, страна переключится. Поле никогда не добавляет код, который не вводили. - Плейсхолдер — пример номера для выбранной страны, если вы не задали свой
placeholder. value— полный номер в формате E.164, например+12133734253. Его форма отправляет под именемname, и его же стоит хранить. Если задатьvalue, заполнятся обе части.country— двухбуквенный код выбранной страны;nationalNumber— номер без кода страны. Определять страну по местоположению или языку — ваша задача.
Проверка
Поле телефона не проверяет номер, пока вы не попросите. А когда показывать ошибку на Field, решаете вы.
validate: неверный номер не даёт отправить форму. Рамка не краснеет, сообщения нет.checkPhoneValidity(): возвращает{ valid, reason }. Вызовите при уходе с поля или при отправке и превратите результат вerrorна Field.
Проверка нужна, чтобы подсказать, что не так, а не чтобы переписать введённое.
Подпись, подсказка и ошибки
<tk-phone-input aria-label="Mobile number" country="DE"></tk-phone-input>
- Оберните поле телефона в
Field . Подпись, подсказка и ошибка Field называют и описывают поле номера. - Без видимой подписи задайте
aria-label(илиaria-labelledby) на поле телефона. - Плейсхолдер — не подпись: он исчезает, как только начинают вводить.
Когда использовать
- Поле телефона — когда номера могут быть из разных стран, например при регистрации или оформлении заказа.
- Для одной страны или если выбор страны только мешает, берите
Input сtype="tel". Пусть номер вводят целиком, с кодом страны, если он нужен. - Для кода подтверждения нужен
OTP input . - Чтобы выбрать страну без номера, берите
Country select .
<tk-field label="Phone number" helper="Include the country code for numbers outside the UK, like +33"> <tk-input type="tel" name="phone" autocomplete="tel"></tk-input> </tk-field>
Текст
- Подпишите «Номер телефона» или то, для чего он: «Мобильный», «Рабочий телефон».
- В ошибке скажите, что сделать: «Введите номер телефона, например 07700 900 982». Без «неверно».
- Объясните в подсказке, зачем нужен номер, если это неочевидно.
Подробнее в
Можно / нельзя
| ✅ Можно | ❌ Нельзя |
|---|---|
Обернуть в Field или задать aria-label |
Ждать, что поле само покажет подпись |
Хранить и отправлять value в E.164 |
Хранить отформатированный текст |
Задать country или дать выбрать |
Решать за пользователя, из какой он страны |
Обычное поле tel для одной страны |
Выбор страны, который только мешает |
| Проверять при уходе с поля или отправке, чтобы подсказать | Перекрашивать или переписывать номер во время ввода |
| OTP input для кодов подтверждения | Поле телефона для кода |
Связанные
Field : подпись, подсказка и ошибка.Country select : выбор страны сам по себе.Input : обычное полеtelдля одной страны.OTP input : код подтверждения, который часто идёт следом.
API
Атрибуты
| Атрибут | Тип | По умолчанию | Что делает |
|---|---|---|---|
value |
string | '' |
номер в формате E.164; если задать, заполнит обе части |
country |
string | выбранная страна, двухбуквенный код вроде US |
|
name |
string | имя поля формы; отправляет значение E.164 | |
format |
boolean | true |
форматирует номер при вводе; чтобы выключить, задайте свойству false |
validate |
boolean | false |
неверный номер блокирует отправку; внешне ничего не меняется |
placeholder |
string | заменяет пример номера | |
country-label |
string | Country calling code |
доступное имя выбора кода |
size |
medium | large |
medium |
высота 32 или 36px |
required |
boolean | false |
номер обязателен; внутри Field задавайте на Field |
disabled |
boolean | false |
не в фокусе, не меняется, не попадает в форму |
readonly |
boolean | false |
в фокусе и копируется, но не меняется |
locale |
string | язык названий стран в списке | |
inputmode |
string | tel |
клавиатура для поля номера |
autocomplete |
string | tel-national |
подсказка автозаполнения для поля номера |
Свойства
| Свойство | Тип | Что делает |
|---|---|---|
nationalNumber |
string, только чтение | номер без кода страны |
События
input срабатывает при каждой правке и при выборе страны. change — когда правку
подтверждают уходом с поля, и при выборе страны. Читайте value, country или
nationalNumber. change не выходит за пределы shadow root; слушайте его на самом элементе.
Сброс формы возвращает первое значение.
Методы
focus(): переводит фокус на поле номера.checkPhoneValidity(): возвращает промис с{ valid, reason }.
CSS
::part(field): рамка поля.::part(prefix): выбор кода страны.::part(number): нативный<input>номера.
Токены
| Роль | Покой | Фокус | Ошибка | Отключено | Только чтение |
|---|---|---|---|---|---|
| рамка | border/subtle |
border/accent/focus |
border/error |
border/disabled |
border/subtle |
| фон | surface/default |
surface/default |
surface/default |
surface/disabled |
surface/subtle |
Линия между частями border/subtle. Плейсхолдер text/placeholder. Углы radius-8. Токены
те же, что у
Доступность
Встроено:
- Две названные части: Field называет поле номера, а выбор кода — комбобокс с именем «Country calling code».
- Поле номера открывает телефонную клавиатуру и задаёт
autocomplete="tel-national"; выбор кода —autocomplete="tel-country-code". - Field связывает подсказку и ошибку с полем номера и помечает его как неверное.
- Рамка фокуса никогда не прячется.
На вашей стороне:
- Дайте полю имя: подпись Field или
aria-label. - Подумайте, помогает ли выбор страны. Для одной страны обычное поле
telчасто удобнее всем.
| Клавиша | Действие |
|---|---|
Tab |
переводит фокус с кода страны на поле номера |
| ввод текста, в выборе кода | фильтрует список стран; при фокусе код выделяется, поэтому первая же клавиша начинает поиск |
↓ / ↑, Enter, Esc, в выборе кода |
как в |
Пределы контраста
- Рамка в покое: 1.33:1 в светлой теме и 2.00:1 в тёмной, ниже минимума 3:1; в контрастной 4.22:1. Всегда давайте полю видимую подпись, чтобы рамка не была единственной подсказкой.