Группа переключателей
Группа переключателей объединяет несколько кнопок-переключателей в одну панель инструментов, где включено может быть сколько угодно.
<tk-toggle-button-group label="Text formatting"> <tk-toggle-button value="bold" pressed><tk-button variant="ghost">Bold</tk-button></tk-toggle-button> <tk-toggle-button value="italic"><tk-button variant="ghost">Italic</tk-button></tk-toggle-button> <tk-toggle-button value="underline"><tk-button variant="ghost">Underline</tk-button></tk-toggle-button> </tk-toggle-button-group>
Анатомия
| Часть | Что это |
|---|---|
tk-toggle-button-group |
сам элемент; role="toolbar"; одна остановка Tab на всю группу |
| слот по умолчанию | два и больше tk-toggle-buttonvalue |
| крайние углы и стыки | та же геометрия соединённого блока, что у |
Расположение
Группа располагает переключатели точно так же, как
- Вместе (по умолчанию) или
spaced: один блок с линией 1px между переключателями или отдельные переключатели с промежутком 8px. orientation="vertical": столбец; клавиши-стрелки следуют за ним.shape="round": полностью скруглённые края, а у вертикального блока скругление 16px. Задавайте его группе, а не внутренним кнопкам.
<tk-toggle-button-group shape="round" label="Filters"> <tk-toggle-button value="unread" pressed><tk-button>Unread</tk-button></tk-toggle-button> <tk-toggle-button value="starred"><tk-button>Starred</tk-button></tk-toggle-button> <tk-toggle-button value="mentions" pressed><tk-button>Mentions</tk-button></tk-toggle-button> </tk-toggle-button-group>
Размеры
Задайте size один раз на группе, и его возьмёт каждый переключатель: small, medium или
large, высотой 24, 32 или 36px, как у
<tk-toggle-button-group size="small" label="View"> <tk-toggle-button value="grid"><tk-button>Grid lines</tk-button></tk-toggle-button> <tk-toggle-button value="rulers"><tk-button>Rulers</tk-button></tk-toggle-button> </tk-toggle-button-group>
Состояния
<tk-toggle-button-group disabled label="Alignment guides"> <tk-toggle-button value="snap" pressed><tk-button>Snap</tk-button></tk-toggle-button> <tk-toggle-button value="guides"><tk-button>Guides</tk-button></tk-toggle-button> </tk-toggle-button-group>
disabled: отключает все переключатели, и группа выпадает из порядка Tab. Переключатель, который вы отключили отдельно, останется отключённым, когда группу снова включат.- Включённое состояние и вид каждого переключателя — от
Toggle button .
Значение
value— свойство с массивомvalueвключённых переключателей, например["bold", "underline"]. Если его задать, включатся ровно эти переключатели.changeсрабатывает один раз при каждом переключении пользователем. Значение читайте изevent.target.value. Когдаvalueилиpressedменяет код, ничего не срабатывает.
Когда использовать
- Для связанных переключателей, из которых включено может быть сколько угодно, например панель форматирования или набор фильтров вида.
- Если включён ровно один вариант, берите
Segmented control . - Для разовых команд, которые не остаются включёнными, берите
Button group . - Если выбор отправляется с формой, берите группу
Checkbox . - Чтобы переключать разделы или панели, берите
Tab bar .
Текст
labelназывает панель: «Форматирование текста», «Фильтры». Если его нет, группа предупреждает в консоли.- Подписи переключателей не меняются, как у любой
Toggle button . - Держите от 2 до 6 переключателей. Остальные уберите в
Menu .
Можно / нельзя
| ✅ Можно | ❌ Нельзя |
|---|---|
| Группа там, где включено может быть несколько | Группа там, где включён ровно один: для этого есть Segmented control |
value у каждого переключателя и value группы |
Собирать включённые переключатели вручную |
Назвать панель через label |
Панель без имени |
| От 2 до 6 переключателей | Переполненная панель: лишнее уберите в меню |
| Для режимов и фильтров | Для значения формы: для него есть чекбоксы |
Связанные
Toggle button : каждый участник группы.Button group : то же расположение для разовых команд.Segmented control : включён ровно один вариант.Checkbox : несколько вариантов, которые отправляются с формой.
API
Атрибуты
| Атрибут | Тип | По умолчанию | Что делает |
|---|---|---|---|
label |
string | обязателен | доступное имя панели |
orientation |
horizontal | vertical |
horizontal |
ряд или столбец; задаёт aria-orientation и клавиши-стрелки |
spaced |
boolean | false |
отдельные переключатели с промежутком 8px вместо одного блока |
shape |
rect | round |
rect |
скруглённые или полностью скруглённые крайние углы; середина прямая |
size |
small | medium | large |
не задан | задаёт размер всем переключателям |
disabled |
boolean | false |
отключает все переключатели |
Свойства
| Свойство | Тип | Что делает |
|---|---|---|
value |
string[] |
value включённых переключателей; если задать, включатся ровно они |
Слоты
| Слот | Содержимое |
|---|---|
| по умолчанию | два и больше tk-toggle-button, у каждого свой value |
События
| Событие | Когда |
|---|---|
change |
пользователь включил или выключил переключатель; всплывает, отменить нельзя. Значение в event.target.value |
Токены
Цвета рисуют сами переключатели: см. border/subtle, крайние углы radius-8 (при shape="round" radius-full, а у
вертикального блока radius-16) и промежуток space-8 при spaced.
Доступность
Встроено:
role="toolbar"сaria-orientation, имя даётlabel.- Одна остановка Tab: Tab приводит в группу на последний переключатель в фокусе, следующий Tab выводит из неё.
- Стрелки только переводят фокус и никогда не переключают. Отключённые переключатели пропускаются.
- У каждого переключателя свой
aria-pressed. - Переключатель в фокусе выходит вперёд, поэтому рамка фокуса не обрезается на стыке.
На вашей стороне:
- Назовите панель через
label. - Дайте каждому переключателю неизменную подпись и
value.
| Клавиша | Действие |
|---|---|
Tab |
приводит в группу или выводит из неё |
Left / Right |
переводит фокус в ряду, по кругу |
Up / Down |
переводит фокус в столбце, по кругу |
Home / End |
переводит фокус на первый / последний переключатель |
Space / Enter |
включает или выключает переключатель в фокусе |