Popover

<sf-popover> открывает небольшую поверхность рядом с кнопкой: фильтр, настройки поля, список того, что можно добавить. Компонент держит состояние открытия, закрывает поверхность по Escape и нажатию снаружи и возвращает фокус на кнопку. Для меню действий над объектом берите Context Menu, для выбора значения в форме — Dropdown, для задачи, которая требует внимания целиком, — модальное окно.

Пример

<div class="flex flex-col gap-2 items-cross-start">
  <sf-popover label="Фильтр по статусу" placement="bottom-start">
    <sf-button slot="trigger" appearance="outline" scheme="on-surface" icon-start="filter_list" text="Статус"></sf-button>
    <div slot="content" class="flex flex-col gap-1 p-2">
      <label class="sf-checkbox sf-checkbox--size-1 flex">
        <span class="sf-checkbox-box transition flex"><input type="checkbox" name="status" value="open" checked><span class="sf-icon" aria-hidden="true"></span></span>
        <span class="sf-checkbox-container"><span class="sf-checkbox-label">Открытые</span></span>
      </label>
      <label class="sf-checkbox sf-checkbox--size-1 flex">
        <span class="sf-checkbox-box transition flex"><input type="checkbox" name="status" value="progress" checked><span class="sf-icon" aria-hidden="true"></span></span>
        <span class="sf-checkbox-container"><span class="sf-checkbox-label">В работе</span></span>
      </label>
      <label class="sf-checkbox sf-checkbox--size-1 flex">
        <span class="sf-checkbox-box transition flex"><input type="checkbox" name="status" value="closed"><span class="sf-icon" aria-hidden="true"></span></span>
        <span class="sf-checkbox-container"><span class="sf-checkbox-label">Закрытые</span></span>
      </label>
    </div>
  </sf-popover>
  <p class="m-0">Подготовить договор с поставщиком — открыта</p>
  <p class="m-0">Согласовать макет главной страницы — в работе</p>
  <p class="m-0">Перенести архив заказов — в работе</p>
  <p class="m-0">Обновить прайс-лист — закрыта</p>
</div>

Применение

Кнопка и поверхность

Внутрь <sf-popover> ставят два элемента: кнопку со slot="trigger" и поверхность со slot="content". Компонент не переносит их: оба остаются там, где написаны, поэтому их может рисовать любой шаблон. Нажатие в любом месте кнопки открывает и закрывает поверхность, нажатия внутри поверхности принадлежат её содержимому.

Поверхность получает фон, радиус, тень и собственную прокрутку, когда содержимое выше доступного места. Отступы внутри задаёт содержимое.

Положение и ширина

placement задаёт, от какого края кнопки открывается поверхность: bottom-end (по умолчанию), bottom-start, top-start, top-end, inline-start или inline-end. Логические значения отражаются при письме справа налево. Без width поверхность берёт ширину самой длинной строки; задайте width, например width="20rem", если в поверхности список строк разной длины.

Поверхность стоит в потоке рядом с кнопкой и не выносится в верхний слой страницы. Предок с overflow: hidden обрежет её, поэтому оставляйте под кнопкой место или открывайте поверхность в другую сторону.

Открытие и закрытие

Атрибут open показывает поверхность и отражает её состояние: его можно читать и ставить. show(), close() и toggle(force) делают то же из кода и возвращают новое состояние. При открытии отправляется событие sf-popover-open, при закрытии — sf-popover-close; в обоих event.detail.open содержит новое состояние.

По умолчанию поверхность закрывается по Escape и по нажатию за её пределами. dismissible="false" отключает оба способа — тогда страница закрывает поверхность сама, вызывая close(), например после шага мастера.

const popover = document.querySelector('sf-popover');

popover.addEventListener('sf-popover-open', () => {
  popover.querySelector('[slot="content"] input')?.focus();
});
popover.addEventListener('sf-popover-close', () => {
  applyFilter();
});

Доступность

• Поверхности нужно доступное имя: label на <sf-popover> передаётся ей как aria-label. Роль поверхности задаёт surface-role: dialog (по умолчанию), menu, listbox или group. Атрибут role на самом <sf-popover> компонент переносит на поверхность и предупреждает в консоли.
• Кнопке нужно доступное имя. aria-expanded и aria-haspopup компонент ставит ей сам по состоянию и роли поверхности.
• При открытии фокус остаётся на кнопке. Если пользователь работает в поверхности с клавиатуры, переведите фокус на её первое поле. После закрытия фокус возвращается на кнопку.
• Escape закрывает поверхность. Если dismissible="false", в поверхности должна быть своя кнопка закрытия.

Справочник API

Раздел собран из манифеста компонента выпуска ui-106d5901f8c3 и обновляется вместе с выпуском. Чтобы исправить описание, исправьте манифест.

Каждому атрибуту соответствует свойство элемента с тем же именем в camelCase: search-placeholder — searchPlaceholder. Свойство атрибута template называется templateName.

Атрибуты

• template — string, по умолчанию default. Имя варианта шаблона.
• open — boolean, по умолчанию false. Показана ли поверхность. Отражается в атрибуте, поэтому потребитель может читать и задавать его.
• placement — string, по умолчанию bottom-end, значения: bottom-start, bottom-end, top-start, top-end, inline-start, inline-end. От какого угла триггера отображается поверхность.
• label — string, по умолчанию пусто. Доступное имя поверхности. Поверхность с ролью, но без имени объявляется как безымянная.
• width — string, по умолчанию пусто. Собственная ширина. Без неё поверхность принимает ширину самой длинной строки, и список имён получается широким и неровным.
• dismissible — boolean, по умолчанию true. Esc и нажатие снаружи закрывают её. Потребитель, который сам обрабатывает эти действия, отключает это и вызывает close(), когда решит.
• surface-role — string, по умолчанию dialog, значения: dialog, menu, listbox, group. Чем поверхность является для читателя: dialog, menu, listbox или group. Задаётся на sf-popover; поверхность получает role, а триггер — aria-haspopup.

Прежние имена:

Методы

• toggle(force?: boolean) — возвращает boolean. Открыть или закрыть; логическое значение задаёт одно из состояний принудительно.
• show() — возвращает boolean. Открыть.
• close() — возвращает boolean. Закрыть.
• returnFocus() — возвращает null. Вернуть фокус на триггер.

События

Все события приходят на сам элемент и всплывают. Общие события базового элемента перечислены в главе Жизненный цикл → Этапы.

• sf-popover-open — detail: { component: object, tagName: string, template: string, open: boolean }. Поверхность открылась.
• sf-popover-close — detail: { component: object, tagName: string, template: string, open: boolean }. Поверхность закрылась.

Минимальная разметка

<sf-popover label="Settings"><button slot="trigger" type="button">Settings</button><div slot="content">…</div></sf-popover>

Источник

• simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/smart/popover
• simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/rule/rule.json#name=cl-popover

См. также

• Context Menu — меню действий над объектом.
• Drawer — боковая панель рабочего места.