Поповер
Поповер — небольшая панель, которая открывается рядом с кнопкой. В ней могут быть кнопки, ссылки и поля. Страницу он не блокирует.
<tk-popover label="Filters"> <tk-button slot="trigger">Filters</tk-button> <tk-checkbox>Open</tk-checkbox> <tk-checkbox>Closed</tk-checkbox> <tk-button size="small" variant="primary">Apply</tk-button> </tk-popover>
Анатомия
| Часть | Что это |
|---|---|
tk-popover |
сам элемент; открывает и закрывает панель и расставляет ARIA |
слот trigger |
одна кнопка, которая его открывает: tk-button или tk-icon-button |
| слот по умолчанию | содержимое, интерактивное или нет |
part surface |
панель |
Стрелки, шапки, подвала и кнопки закрытия нет. Если нужны, соберите их сами внутри содержимого.
Режимы открытия
Engineer in London. 168 followers.
<tk-popover trigger="hover" label="Ada Lovelace"> <tk-button slot="trigger" variant="ghost">Ada Lovelace</tk-button> <p>Engineer in London. 168 followers.</p> <tk-button size="small">Follow</tk-button> </tk-popover>
click(по умолчанию): клик,EnterилиSpaceна кнопке открывают и закрывают панель. Подходит для всего, что открывают намеренно.hover: открывается при наведении указателя, при фокусе с клавиатуры и по касанию, поэтому доступен всем. Подходит для превью, содержимое которых есть и в другом месте.- При открытии фокус в панель не переходит. С клавиатуры до содержимого доходят клавишей
Tab: оно идёт сразу после кнопки.
Открытие и закрытие
- Панель закрывается по
Esc, по нажатию снаружи, когда из неё уходит фокус и когда кнопка уезжает за край экрана при прокрутке.Escвозвращает фокус на кнопку. - В режиме
hoverпанель открывается через 400 мс наведения и закрывается через 300 мс после того, как указатель ушёл, чтобы на неё можно было перевести указатель. Фокус и касание открывают её сразу. - Сама по себе по таймеру она не закрывается.
- Открывается под кнопкой, а если места внизу нет, над ней. Появляется сразу, без анимации.
show(),hide()иtoggle()открывают и закрывают её из кода.
Пояснение к настройке
Чтобы объяснить настройку или поле, поместите за кнопку с иконкой info короткий заголовок, одно-два предложения и не больше одной ссылки.
Billing cycles
Your cycle starts the day you subscribe and renews on the same date each month.
<tk-popover label="About billing cycles"> <tk-icon-button slot="trigger" label="About billing cycles"><tk-icon name="info"></tk-icon></tk-icon-button> <h4>Billing cycles</h4> <p>Your cycle starts the day you subscribe and renews on the same date each month.</p> <tk-link href="/billing">Read more about billing</tk-link> </tk-popover>
- Используйте
click, а неhover: пояснение открывают намеренно. - Назовите кнопку с иконкой через
label, и панель тоже. - Не держите здесь единственную копию важной информации. Если без неё не справиться, она должна быть на странице.
Размеры
- Панель подстраивается под содержимое, но не шире 320px. Меняется через
--tk-popover-max-width. --tk-popover-max-heightограничивает высоту; тогда содержимое прокручивается по вертикали.--tk-popover-padding: 0даёт картинке дойти до края панели.
Когда использовать
- Поповер — для того, с чем работают рядом с кнопкой: панель фильтров, карточка профиля, панель «Поделиться», короткое пояснение к настройке.
- Для короткого текста, где нечего нажимать, берите
Tooltip . - Для списка команд берите
Menu . - Если задача должна блокировать страницу, или содержимое слишком широкое или важное
для маленькой панели, берите
Dialog .
Текст
- Держите его коротким: заголовок, несколько строк, несколько контролов.
- Называйте панель как кнопку: кнопка «Фильтры» открывает панель с именем «Фильтры».
- Заглавная буква только в начале.
Можно / нельзя
| ✅ Можно | ❌ Нельзя |
|---|---|
| Класть в поповер контролы, с которыми работают | Класть короткий текст, где нечего нажимать; для него есть tooltip |
| Брать меню для списка команд | Класть список команд в поповер |
Брать hover для превью, которые есть и в другом месте |
Прятать за наведением единственную копию важной информации |
| Называть кнопку без текста | Оставлять кнопку или панель без имени |
| Брать диалог, когда задача должна блокировать страницу | Вкладывать поповер в поповер |
Связанные
Tooltip : короткий текст, нажимать нечего.Menu : список команд.Dialog : модальное окно для задачи, которая блокирует страницу.Sheet : модальная панель с края экрана.
API
Атрибуты
| Атрибут | Тип | По умолчанию | Что делает |
|---|---|---|---|
trigger |
click | hover |
click |
как открывается: кликом или наведением, с фокусом и касанием |
label |
string | имя кнопки | доступное имя панели |
Слоты
| Слот | Содержимое |
|---|---|
trigger |
один tk-button или tk-icon-button, можно обёрнутый в |
| по умолчанию | содержимое, в том числе интерактивное |
Методы и свойства
| Имя | Что делает |
|---|---|
show() |
открывает панель |
hide() |
закрывает её |
toggle() |
открывает или закрывает |
open |
true, пока панель открыта; атрибут open повторяет его, но ничего не открывает |
События
Своих событий нет.
CSS
::part(surface): панель.--tk-popover-padding: внутренний отступ. По умолчаниюspace-16.--tk-popover-max-width: наибольшая ширина. По умолчанию320px.--tk-popover-max-height: наибольшая высота. По умолчаниюnone.
Токены
| Часть | Токены |
|---|---|
| панель | surface/raised, shadow-2, radius-16; в контрастной теме рамка 1px border/default |
| текст | text/default |
| отступ | space-16 |
| зазор до кнопки | space-4 |
Значения по темам:
Доступность
Встроено:
- Кнопка получает
aria-haspopup="dialog"иaria-expanded. - Панель — немодальный
role="dialog"; имя даётlabelили имя кнопки. - При открытии фокус остаётся на месте;
Tabведёт в содержимое в порядке страницы, а уход из него закрывает панель. Escзакрывает только поповер, а не окно вокруг него, и возвращает фокус на кнопку.- В режиме
hoverпанель закрывается поEsc, не исчезает, пока на неё наводят указатель, и не закрывается по таймеру.
На вашей стороне:
- Всё внутри должно работать с клавиатуры, без ловушек фокуса.
- Назовите кнопку без текста через
label. - Не кладите поповер в другой поповер.
| Клавиша | Действие |
|---|---|
Enter / Space |
на кнопке в режиме click: открывает или закрывает |
Tab |
ведёт с кнопки в содержимое; после последнего элемента уходит и закрывает |
Esc |
закрывает и возвращает фокус на кнопку |