Кнопка-переключатель
Кнопка-переключатель остаётся включённой или выключенной. Одно нажатие включает режим, второе выключает.
<tk-toggle-button pressed><tk-button>Bold</tk-button></tk-toggle-button> <tk-toggle-button><tk-button>Italic</tk-button></tk-toggle-button>
Анатомия
| Часть | Что это |
|---|---|
tk-toggle-button |
сам элемент; хранит состояние «вкл/выкл» и переключает его |
| слот по умолчанию | одна tk-button или tk-icon-button; она задаёт вид и принимает фокус Tab |
Варианты
<tk-toggle-button pressed><tk-button>Show grid</tk-button></tk-toggle-button> <tk-toggle-button pressed><tk-button variant="outline">Show grid</tk-button></tk-toggle-button> <tk-toggle-button pressed><tk-button variant="ghost">Show grid</tk-button></tk-toggle-button>
Вариант задаётся внутренней кнопке: secondary (по умолчанию), outline или ghost.
Выключенная кнопка выглядит как обычно. Включённая получает нейтральную подсветку и
нейтральный текст, а у outline рамка становится заметнее. Не используйте для
переключателя primary и tone="danger".
Форма
Чтобы кнопка была полностью скруглённой, задайте shape="round" внутренней кнопке. В
соединённой
<tk-toggle-button pressed><tk-button shape="round">Following</tk-button></tk-toggle-button>
Состояния
<tk-toggle-button pressed><tk-button disabled>Pin to top</tk-button></tk-toggle-button> <tk-toggle-button><tk-button disabled>Pin to top</tk-button></tk-toggle-button>
pressed: включено. Нажатие мышью, Space или Enter переключает его и вызываетchange.- Отключение: задайте
disabledвнутренней кнопке. Она не переключается, а включённая сохраняет приглушённую подсветку и по-прежнему выглядит включённой. - Наведение, нажатие и фокус берутся у кнопки. Включённая кнопка под курсором темнеет на одну ступень.
Переключатель-иконка
Для переключателя без текста положите внутрь tk-icon-buttonpressed.
<tk-toggle-button>
<tk-icon-button label="Bookmark">
<tk-icon name="bookmark"></tk-icon>
<tk-icon slot="pressed" name="bookmark-filled"></tk-icon>
</tk-icon-button>
</tk-toggle-button>Управляемый и неуправляемый
- Неуправляемый (по умолчанию): нажатие переключает
pressedи вызываетchange. Значение читайте изevent.target.pressed. - Управляемый: задавайте
pressedнаtk-toggle-buttonиз своего состояния. Когда его меняет код,changeне срабатывает; только когда переключает пользователь. - Не задавайте
pressedвнутренней кнопке. Его ставит переключатель.
Когда использовать
- Для команды или режима, который остаётся включённым: жирный, показать сетку, закрепить, без звука.
- Для настройки, которая применяется сразу, в виде строки с подписью, берите
Switch . - Если значение отправляется с формой, берите
Checkbox . - Если включён ровно один вариант, берите
Segmented control . - Для нескольких переключателей на одной панели берите
Toggle button group .
Текст
- Подпись называет действие и не меняется: «Жирный» остаётся «Жирный» и во включённом состоянии. Скринридер сам добавит «нажата».
- У переключателя-иконки называйте действие: «Добавить в закладки», а не «В закладках».
- Пишите подпись как у любой
Button . Подробнее вAction labels .
Можно / нельзя
| ✅ Можно | ❌ Нельзя |
|---|---|
| Переключатель для режима, который остаётся включённым: жирный, закрепить | Переключатель для значения формы: для него есть Checkbox |
| Одна подпись: «Жирный» и вкл, и выкл | Менять подпись с состоянием: «Жирный» → «Сделано жирным» |
secondary, outline или ghost |
primary или опасный переключатель |
| Toggle button group для нескольких независимых переключателей | Переключатели там, где включён ровно один: для этого есть Segmented control |
Связанные
Button иIcon button : что кладут внутрь.Toggle button group : несколько переключателей на одной панели.Switch иCheckbox : «вкл/выкл» для настроек и форм.Segmented control : включён ровно один вариант.
API
Атрибуты
| Атрибут | Тип | По умолчанию | Что делает |
|---|---|---|---|
pressed |
boolean | false |
включено или выключено; переключается нажатием |
value |
string | не задан | обозначает переключатель внутри |
Слоты
| Слот | Содержимое |
|---|---|
| по умолчанию | одна tk-button или tk-icon-button; вариант, размер, disabled и иконки задавайте ей |
События
| Событие | Когда |
|---|---|
change |
пользователь переключил pressed; всплывает, отменить нельзя. Когда pressed меняет код, не срабатывает |
Токены
Все цвета рисует внутренняя кнопка: см.
| Часть | Токен |
|---|---|
| фон | state/on; под курсором state/on-hover |
рамка, outline |
border/selected |
| текст | text/default |
Доступность
Встроено:
- Внутренняя нативная кнопка получает
aria-pressed="true"или"false", поэтому её всегда объявляют как переключатель. aria-pressedсохраняется у отключённой кнопки.- Остановка Tab одна, на внутренней кнопке; Space и Enter её переключают.
На вашей стороне:
- Подпись одинаковая в обоих состояниях.
- Не полагайтесь только на подсветку: скринридер сообщает состояние, а переключатель-иконка может менять иконку на залитую.
| Клавиша | Действие |
|---|---|
Tab |
переводит фокус на переключатель |
Space / Enter |
переключает его |
Пределы контраста
- Включённый и наведённый: в светлой и тёмной теме включённый переключатель выглядит так же, как наведённый выключенный; в контрастной они различаются. Скринридер всегда сообщает состояние. Если оно должно читаться с первого взгляда, покажите его ещё где-то.