Number stepper
Number stepper задаёт небольшое целое число кнопками − и +: количество товара, гостей, билетов.
<tk-number-stepper label="Adults" unit="adults" value="2" min="1" max="8"></tk-number-stepper>
Анатомия
| Часть | Что это |
|---|---|
tk-number-stepper |
сам элемент; одна остановка Tab |
part field |
рамка ряда |
part decrement |
кнопка −; удерживайте, чтобы повторять |
part value |
число посередине; это spinbutton, и фокус получает оно |
part increment |
кнопка +; удерживайте, чтобы повторять |
Stepper занимает ровно столько места, сколько нужно содержимому. Своей подписи он не показывает.
Подпись
Guests
<div style="display: flex; align-items: center; justify-content: space-between; max-width: 280px"> <span>Guests</span> <tk-number-stepper label="Guests" unit="guests" value="3" min="1" max="10"></tk-number-stepper> </div>
- Поставьте рядом видимую подпись и повторите те же слова в
label.label— это имя, которое слышат скринридеры; сам stepper его не рисует. unitдобавляет слово к тому, что слышат скринридеры: «3 guests»; на экране остаётся «3».- Не оборачивайте stepper в
Field . Он называет себя сам.
Значение
value— целое число (по умолчанию 0); отправляется под именемname.minпо умолчанию 0. Для «хотя бы один» задайтеmin="1". Уmaxзначения по умолчанию нет; задайте его, если есть настоящий предел, иначе + никогда не отключится.stepпо умолчанию 1 и должен быть целым. Значение всегда лежит на сетке шага и внутри диапазона.- Каждое нажатие — это изменение: приходят
inputиchange. Если удерживать кнопку, пара событий приходит на каждый повтор.
Размеры
<tk-number-stepper label="Medium stepper" value="2"></tk-number-stepper> <tk-number-stepper label="Large stepper" size="large" value="2"></tk-number-stepper>
size |
Высота и ширина кнопки | Текст значения | Иконка |
|---|---|---|---|
medium (по умолчанию) |
32px | Body Small (14/20) | icon-size-16 |
large |
36px | Body Medium (16/24) | icon-size-16 |
Оба размера не меньше минимальной цели нажатия 24px. Размера small нет: с
size="small" stepper рисуется как medium и пишет предупреждение в консоль.
Состояния
<tk-number-stepper label="Tickets at minimum" value="1" min="1" max="4"></tk-number-stepper> <tk-number-stepper label="Tickets" value="2" disabled></tk-number-stepper>
При наведении рамка не меняется, а при фокусе окрашивается в цвет фокуса и утолщается внутрь. Кнопки − и + под курсором подсвечиваются.
- На
minилиmaxсоответствующая кнопка отключается. disabled: на stepper нельзя перейти и нельзя его изменить, а в форму он не попадает.
Ошибки у stepper не бывает: значение не может выйти из диапазона.
Удаление на минимуме и кнопка «Добавить»
Два сценария корзины вы собираете вокруг stepper сами:
- Удаление на минимуме: задайте
min="1"и поставьте рядомIcon button с корзиной. - Сначала «Добавить»: пока товар не добавлен, показывайте
Button «Добавить», а потом stepper.
Когда использовать
| Если значение — | Берите |
|---|---|
| небольшое целое, которое меняют кнопками − и +: товары в корзине, гости, порции | Number stepper |
| число, которое вводят: дроби, деньги, проценты, большой или открытый диапазон | |
| значение на шкале, которое задают перетаскиванием | |
| количество из длинного списка или «10+» | |
| цифры, которые не количество: индекс, номер карты | inputmode="numeric" |
Ввести число с клавиатуры в stepper нельзя. Если это нужно, берите
Можно / нельзя
| ✅ Можно | ❌ Нельзя |
|---|---|
| Брать stepper для небольшого целого числа | Брать его для денег, дробей или большого диапазона |
Задавать max, если есть настоящий предел |
Оставлять ограниченное количество без max |
Показывать видимую подпись и повторять её в label |
Оставлять stepper без видимой подписи |
| Брать Select для «10+» и длинных списков | Заставлять нажимать + двадцать раз |
Связанные
Number input : число, которое вводят с клавиатуры.Slider : значение задают перетаскиванием.Select : количество выбирают из списка.Icon button : кнопка с корзиной для удаления на минимуме.
API
Атрибуты
| Атрибут | Тип | По умолчанию | Что делает |
|---|---|---|---|
label |
string | '' |
доступное имя; обязателен, на экране не виден |
unit |
string | — | слово, которое скринридер читает после значения, например guests |
value |
number | 0 |
целое число; отправляется под именем name |
name |
string | — | имя поля в форме |
min |
number | 0 |
наименьшее значение |
max |
number | — | наибольшее значение; без него верхней границы нет |
step |
number | 1 |
на сколько меняют значение − и +; целое число |
large-step |
number | — | шаг для Page Up / Page Down и Shift |
disabled |
boolean | false |
не в фокусе, не меняется, не попадает в форму |
size |
medium | large |
medium |
высота 32 / 36px |
События
| Событие | Когда |
|---|---|
input |
на каждом шаге |
change |
на каждом шаге |
Текущее значение — в свойстве value.
Методы
focus(): переводит фокус на значение.
CSS
::part(field): рамка ряда.::part(decrement)и::part(increment): кнопки − и +.::part(value): число посередине.
Токены
| Роль | Покой | Наведение / нажатие | Отключено |
|---|---|---|---|
| глиф − / + | icon/secondary |
icon/default |
text/disabled |
| фон − / + | нет | state/accent/hover |
нет |
| текст значения | text/default |
— | text/disabled |
| рамка ряда | border/subtle |
— | border/disabled |
| фон ряда | surface/default |
— | surface/disabled |
Наведение и нажатие выглядят одинаково. Тонкие линии border/subtle отделяют значение от
кнопок. Рамка в фокусе — border/accent/focus, углы — radius-8. Значения по темам:
Доступность
Встроено:
- Значение — это spinbutton и единственная остановка Tab. Скринридер сообщает
label, значение (сunit) и диапазон. - Кнопки − и + скрыты от скринридеров и пропускаются при Tab; то же самое делают стрелки, а нажатие на кнопку оставляет фокус на значении.
На вашей стороне:
- Покажите рядом видимую подпись и повторите те же слова в
label. - Задайте
min,maxиstepпо реальному диапазону.
| Клавиша | Действие |
|---|---|
↑ / ↓ |
шаг вверх или вниз на step |
Shift + ↑ / ↓, Page Up / Page Down |
шаг на large-step |
Home / End |
к min / max, если они заданы |
Пределы контраста
У рамки в покое те же пределы, что у Input: см.