Field
Field даёт одному полю формы видимую подпись, подсказку и сообщение об ошибке и называет поле для скринридеров.
<tk-field label="Email address" helper="We only use this for the receipt"> <tk-input type="email" name="email" autocomplete="email"></tk-input> </tk-field>
Анатомия
| Часть | Что это |
|---|---|
tk-field |
обёртка; своей остановки Tab и своего значения в форме у неё нет |
| подпись | текст из label, а при required — звёздочка |
| подсказка | текст из helper, между подписью и полем |
| слот по умолчанию | поле, ровно одно |
| ошибка | сообщение из error с иконкой, под полем |
Подпись, подсказку и ошибку Field рисует сам по своим атрибутам. Значение, остановка Tab и клавиатура остаются у поля.
Состояния
<tk-field label="Company name" required> <tk-input name="company"></tk-input> </tk-field> <tk-field label="Email address" required error="Enter an email address, like name@example.com"> <tk-input type="email" name="email" value="ada@"></tk-input> </tk-field>
<tk-field label="Username" helper="Usernames can't be changed" disabled> <tk-input name="username" value="ada"></tk-input> </tk-field>
required: добавляет звёздочку после подписи и делает поле обязательным. Звёздочка серая, не красная: пустое обязательное поле ещё не ошибка.error: показывает сообщение под полем, красит рамку в красный и отмечает поле как неверное. Чтобы убрать ошибку, уберитеerror.disabled: на поле нельзя перейти и нельзя его изменить. Подпись и подсказка остаются читаемыми, чтобы в подсказке можно было объяснить, почему поле закрыто.requiredиdisabledзадавайте у Field, а не у поля. Field перезаписывает собственные значения поля.
Field ничего не проверяет. Когда задать error и что в нём написать, решаете вы.
Подпись, подсказка и ошибки
<tk-field label="Card number" helper="The 16 digits on the front of your card"> <tk-input inputmode="numeric" name="card" autocomplete="cc-number"></tk-input> </tk-field>
<tk-input aria-label="Filter by name"></tk-input>
- Field называет поле по
label, а подсказку и ошибку добавляет в его описание. Клик по подписи переводит фокус в поле. - Если видимой подписи нет, обойдитесь без Field и задайте
aria-labelу поля. Только когда назначение поля понятно из того, что вокруг. - Каждому полю нужно одно из двух. Плейсхолдер никогда не заменяет подпись.
Search field сам называет себя «Search»; внутри Field это имя заменяет подпись Field.
Когда использовать
- Оборачивайте поле в Field всякий раз, когда ему нужна видимая подпись. Field работает
с
Input ,Textarea ,Number input ,OTP input ,Phone input ,Search field ,Select ,Combobox ,Multiselect ,Date picker иTime picker . Форма — это стопка Field. - В одном Field — одно поле.
- Не оборачивайте
Checkbox ,Radio иSwitch . Их подпись стоит рядом и сама их называет; Field их пропускает и пишет предупреждение в консоль. - Для набора радиокнопок или чекбоксов берите
группу радиокнопок илигруппу чекбоксов . У группы своя подпись.
Текст
- Подпись: называйте, что спрашиваете. Коротко, заглавная буква только в начале, без двоеточия: «Email», «Страна».
- Подсказка: одна короткая строка, например формат или где найти значение. Ничего важного, без ссылок.
- Ошибка: скажите, что случилось и как исправить, словами из подписи: «Введите имя и фамилию». Без «пожалуйста», «извините» и «неверно».
- Обязательные поля: если форма отмечает их звёздочкой, добавьте сверху одну строку: «* — обязательное поле».
Подробнее в
Можно / нельзя
| ✅ Можно | ❌ Нельзя |
|---|---|
Задавать label у Field |
Ждать, что голое поле покажет подпись |
| Класть в каждый Field одно поле | Оборачивать чекбокс, радиокнопку или переключатель |
Задавать required и disabled у Field |
Задавать их у поля внутри Field |
| Объяснять в подсказке, почему поле отключено | Отключать поле без объяснения |
| Давать имя каждому полю | Использовать плейсхолдер вместо подписи |
Связанные
Input : однострочное поле, которое чаще всего оборачивают в Field.Checkbox ,Radio иSwitch : называют себя сами, без Field.Errors : как писать сообщения об ошибках.
API
Атрибуты
| Атрибут | Тип | По умолчанию | Что делает |
|---|---|---|---|
label |
string | '' |
видимая подпись и доступное имя поля; обязателен |
helper |
string | — | подсказка под подписью; добавляется в описание поля |
error |
string | — | сообщение об ошибке; красит рамку и отмечает поле как неверное |
required |
boolean | false |
показывает звёздочку и ставит полю required |
disabled |
boolean | false |
ставит полю disabled; подпись и подсказка остаются читаемыми |
value, name, placeholder и size задаются у поля, а не у Field.
Слоты
| Слот | Содержимое |
|---|---|
| слот по умолчанию | одно поле, например tk-input или tk-select |
События
Своих событий нет. События input и change от поля проходят насквозь.
Методы
focus(): переводит фокус в поле.
Токены
| Роль | Токен |
|---|---|
| подпись | text/default, средняя насыщенность |
| звёздочка и подсказка | text/secondary |
| сообщение об ошибке и иконка | text/error, icon/error |
| от подписи до подсказки | space-4 |
| от подсказки или подписи до поля | space-8 |
| от поля до ошибки | space-4 |
Токены рамки поле приносит само; рамка при ошибке — border/error. Значения по темам:
Доступность
Встроено:
- Field называет внутренний элемент поля, и скринридер читает подпись один раз.
- Подсказка и ошибка читаются как описание поля, а
errorставитaria-invalid. - Перед сообщением об ошибке для скринридеров стоит скрытое «Error:».
- Звёздочка скрыта от скринридеров; поле само сообщает, что оно обязательное.
- Клик по подписи переводит фокус в поле.
На вашей стороне:
- Дайте каждому полю имя:
labelу Field илиaria-labelу поля. - Ошибку зачитывают, когда поле получает фокус, а не в момент появления. Если вы проверяете форму при отправке, покажите сводку ошибок вверху и переведите на неё фокус.
- Если поле отключено, объясните почему в подсказке.
Своих клавиш у Field нет, клавиатурой управляет поле. В браузерах без ARIA element reflection (до 2025 года) скринридер может не прочитать подсказку и ошибку.