Выбор времени
Time picker — поле формы для времени суток. Время вводят любое или выбирают из подсказок; форма получает 24-часовое время, например 19:30.
<tk-field label="Start time" helper="For example, 2:30 PM"> <tk-time-picker name="start" interval="15" min="09:00" max="17:00"></tk-time-picker> </tk-field>
Оберните поле в aria-label. Внутри Field ставьте required и disabled на
сам Field.
Анатомия
| Часть | Что это |
|---|---|
tk-time-picker |
сам элемент; одна остановка Tab |
part field |
рамка поля; занимает ширину контейнера |
part input |
нативное текстовое поле; в него всегда можно печатать |
| иконка часов | в конце поля; украшение, не кнопка |
part listbox |
список подсказок; шириной с поле; открывается под ним, а у нижнего края экрана — над ним |
Список только подсказывает. Можно ввести 7:37 PM, даже если список идёт с шагом 30 минут.
Размеры
<tk-time-picker aria-label="Pickup time" value="09:30"></tk-time-picker> <tk-time-picker size="large" aria-label="Return time" value="17:00"></tk-time-picker>
size |
Высота | Отступы по бокам | Текст значения | Строка подсказки |
|---|---|---|---|---|
medium (по умолчанию) |
32px | space-8 |
Body Small (14/20) | 32px |
large |
36px | space-10 |
Body Medium (16/24) | 36px |
Высоты совпадают с Input и Button.
Состояния
<tk-time-picker aria-label="Opens at" value="08:00" readonly></tk-time-picker> <tk-time-picker aria-label="Closes at" value="18:00" disabled></tk-time-picker>
<tk-field label="Reminder time" error="Enter a real time"> <tk-time-picker name="reminder"></tk-time-picker> </tk-field>
При наведении поле не меняется. В фокусе рамка окрашивается в цвет фокуса и утолщается внутрь; так остаётся, пока открыт список.
readonly: время можно выделить и скопировать; список не открывается.disabled: ничего не работает, время не уходит с формой.- Ошибка: задайте
errorна Field. Рамка станет красной, под полем появится текст.
Ввод времени
Текст разбирается, когда человек нажимает Enter или уходит из поля. Регистр не важен, «p.m.» тоже подходит.
21:30,9:30или14.009или21: целый час930,0930или1730- любое из этого с AM или PM:
9:30pm,9 PM,930p
Без AM и PM время читается как 24-часовое: 9:30 — утро. С AM или PM часы идут от 1 до
12; 12 AM — полночь. Слова вроде «noon» не работают.
Разобранное время поле показывает как «9:30 AM» или «09:30» при hour-cycle="h23". Если
текст не похож на время, поле оставляет его, сбрасывает значение и не даёт отправить
форму.
Подсказки
<tk-time-picker aria-label="Quiet hours start" hour-cycle="h23" interval="60" min="22:00" max="07:00"></tk-time-picker>
intervalзадаёт шаг подсказок в минутах: 30 по умолчанию, 15 для расписаний. 60 должно делиться на него нацело. Введённое время он никогда не отклоняет.minиmaxограничивают и список, и значение. Еслиminпозжеmax, окно переходит через полночь: от22:00до07:00список идёт с 22:00 до 07:00.- Список открывает клик в поле или
Down. Набор текста его не открывает и не фильтрует. - Список открывается на выбранном времени или на ближайшей подсказке после текущего. Выбранное время отмечено галочкой.
- Фокус остаётся в поле. Перемещение по списку не меняет значение; меняют Enter, клик или Tab на подсвеченной строке.
Escили клик снаружи закрывают список без выбора.
Когда использовать
- Time picker — когда время выбирает человек: начало встречи, напоминание.
- Когда набор времён задаёт продукт, берите
Select : слоты записи, окна доставки. - Для длительности —
Number input с единицей, например 90 минут. - Для даты и времени поставьте рядом
Date picker и time picker. Не сливайте их в одно поле. - Для промежутка времени — два time picker, соединённые словом «до».
- Часовой пояс — отдельным
Select или текстом: «9:00 AM PST».
Текст
- Назовите в подписи роль времени: «Время начала», «Время подачи», а не «Время».
- Формат дайте в подсказке с примером: «Например, 2:30 PM». Не в плейсхолдере.
- AM и PM пишите заглавными, без точек: «2:30 PM».
- Покажите первую подходящую ошибку:
| Проблема | Текст ошибки |
|---|---|
| пусто, а поле обязательное | «Введите время начала» |
| такого времени нет | «Enter a real time» (пишет поле) |
вне min / max |
«Время начала должно быть между 9:00 и 17:00» |
Правила между полями, например «конец позже начала», проверяете вы. Подробнее в
Можно / нельзя
| ✅ Можно | ❌ Нельзя |
|---|---|
| Назвать роль времени: «Время начала» | Подписать поле просто «Время» |
| Дать «Например, 2:30 PM» в подсказке | Дать формат только в плейсхолдере |
Задать interval под задачу |
Перечислять каждую минуту суток |
| Поставить рядом поле даты и поле времени | Сливать дату и время в одно поле |
| Брать select для слотов, которые задаёт продукт | Брать time picker для фиксированных слотов |
| Брать number input с единицей для длительности | Брать time picker для «сколько длится» |
Связанные
Field : подпись, подсказка и ошибка вокруг поля.Date picker : дата рядом со временем.Select : фиксированные слоты и часовые пояса.Combobox : список, который фильтруется при вводе; этот — нет.Input : рамка, общая с этим полем.
API
Атрибуты
| Атрибут | Тип | По умолчанию | Что делает |
|---|---|---|---|
value |
24-часовое HH:mm |
'' |
время; в этом виде отправляется под name, как бы оно ни показывалось |
name |
строка | — | имя поля в форме |
hour-cycle |
h12 | h23 |
h12 |
показывает «9:30 AM» или «09:30» |
interval |
минуты | 30 |
шаг подсказок; 60 должно делиться на него |
min / max |
HH:mm |
— | допустимое время; min позже max — окно через полночь |
required |
boolean | false |
пустое поле блокирует отправку; видимой отметки нет (звёздочку ставит Field) |
readonly |
boolean | false |
можно выделить и скопировать; список не открывается |
disabled |
boolean | false |
не получает фокус, не уходит с формой |
placeholder |
строка | — | текст в пустом поле; лучше не использовать |
size |
medium | large |
medium |
высота 32 / 36px |
События
change срабатывает, когда время меняется: после ввода разборчивого времени или выбора
подсказки. input срабатывает на каждое нажатие клавиши. Установка value из кода
событий не вызывает. Сброс формы возвращает первое значение.
CSS
::part(field): рамка поля.::part(input): нативное текстовое поле.::part(listbox): список подсказок.
Токены
Рамка поля берёт
| Часть | Токены |
|---|---|
| иконка часов | icon/secondary, icon-size-16; неактивная icon/disabled |
| список | surface/raised + shadow-2, radius-16, отступ space-4 |
| строка подсказки | text/default, Label Medium (14/20), radius-12; подсвеченная state/hover |
| выбранная строка | галочка, icon/accent |
В высококонтрастной теме у списка ещё и рамка 1px border/default. Значения для каждой
темы:
Доступность
Встроено:
- Нативное текстовое поле, которое объявляется как комбобокс со списком, открытым или закрытым, и с подсвеченной подсказкой.
- Одна остановка Tab: иконка часов — украшение, фокус остаётся в поле.
- Значение всегда отправляется в 24-часовом виде, как бы оно ни показывалось.
- Неразборчивое время, пустое обязательное поле или время вне границ блокируют отправку и переводят фокус в поле.
- Каждая строка не ниже 32px.
Ваша часть:
- Дайте каждому полю имя: подпись Field с ролью времени или
aria-label. - Положите пример формата в подсказку.
- Задайте
interval,minиmaxпод задачу. - Если часовой пояс важен, назовите его в тексте.
| Клавиша | Список закрыт | Список открыт |
|---|---|---|
Down / Up / Alt + Down |
открывает список на выбранном или ближайшем времени | двигает подсветку; на краях останавливается |
Enter |
разбирает введённое время, затем отправляет форму | выбирает подсвеченную строку или разбирает введённое время; закрывает |
Esc |
— | закрывает список |
Tab |
уводит дальше | выбирает подсвеченную строку и уводит дальше |
Home / End / Left / Right |
двигают курсор в тексте | двигают курсор в тексте |
Пределы контраста
- Рамка поля: 1.33:1 в светлой теме и 2.00:1 в тёмной, ниже минимума 3:1; 4.22:1 в высококонтрастной. Всегда показывайте подпись.