Popover API

Концепции и использование

Очень распространённый паттерн в Интернете — отображение контента поверх другого содержимого, привлекая внимание пользователя к конкретной важной информации или действиям, которые необходимо предпринять. Такой контент может иметь несколько разных названий — оверлеи, всплывающие окна, поповеры, диалоги и т. д. В документации мы будем называть их всплывающими окнами. В общем случае это могут быть:

• Модальные, означающие, что во время показа всплывающего окна остальная часть страницы становится неинтерактивной до тех пор, пока с всплывающим окном не будет произведено какое-либо действие (например, сделан важный выбор).
• Немодальные, означающие, что с остальной частью страницы можно взаимодействовать во время показа всплывающего окна.

Всплывающие окна, созданные с помощью Popover API, всегда являются немодальными. Если необходимо создать модальное всплывающее окно, следует использовать элемент <dialog>. Эти два элемента во многом пересекаются — например, может понадобиться создать всплывающее окно, которое будет постоянно отображаться, но при этом управляться с помощью декларативного HTML. Можно превратить элемент <dialog> во всплывающее окно (<dialog popover> вполне допустимо), если вы намерены совместить управление всплывающим окном с семантикой диалога.

Типичные варианты использования Popover API включают интерактивные элементы, такие как меню действий, пользовательские всплывающие уведомления, предложения по элементам формы, средства выбора контента или обучающий пользовательский интерфейс.

Всплывающие окна можно создавать двумя разными способами:

• Декларативно, с помощью набора новых HTML атрибутов. Простое всплывающее окно с кнопкой переключения можно создать с помощью следующего кода:

  <button popovertarget="mypopover">Toggle the popover</button>
  <div id="mypopover" popover>Popover content</div>

• Через API JavaScript. Например, можно использовать HTMLElement.togglePopover() для переключения всплывающего окна между отображаемым и скрытым.

Также появились новые события, реагирующие на переключение всплывающих окон, и CSS-функции для стилизации всплывающих окон. Все новые возможности перечислены ниже.

Подробное руководство по использованию Popover API см. в разделе Использование Popover API.

HTML атрибуты

popover

Глобальный атрибут popover используется для обозначения HTML элемента как popover-элемента.

Popover-элементы скрыты с помощью display: none, пока не будут открыты с помощью вызывающего/контрольного элемента (например, <button> или <input type="button"> с атрибутом popovertarget) или вызова HTMLElement.showPopover().

При открытии popover-элементы будут отображаться над всеми остальными элементами в верхнем слое, и на них не будет влиять позиция родительских элементов или стилизация переполнения.

Атрибут popover может иметь значения auto (по умолчанию) или manual. Всплывающие окна, имеющие состояние auto, могут быть легко убраны путём выделения за пределами области всплывающего окна, и обычно позволяют отображать на экране только одно всплывающее окно одновременно. В отличие от него, всплывающие окна manual всегда должны быть явно скрыты, однако они допускают такие варианты использования, как вложенные всплывающие окна в меню.

popovertarget

Превращает элемент <button> или <input> в кнопку управления всплывающим окном; в качестве значения принимает ID popover-элемента, которым нужно управлять.

popovertargetaction

Определяет действие, которое будет выполняться над popover-элементом, управляемым элементом управления <button>. Возможные значения:

• hide — Кнопка скрывает показанный popover-элемент. Если попытаться скрыть уже скрытое всплывающее окно, никаких действий не будет предпринято.
• show — Кнопка покажет скрытый popover-элемент. Если попытаться показать уже отображаемое всплывающее окно, никаких действий не будет предпринято.
• toggle — Кнопка переключает popover-элемент между show и hide. Если popover-элемент скрыт, он будет показан; если popover-элемент показан, он будет скрыт. Если значение popovertargetaction опущено, toggle будет действием по умолчанию, выполняемое управляющей кнопкой.

CSS возможности

::backdrop

Псевдоэлемент ::backdrop — это полноэкранный элемент, размещаемый непосредственно за popover-элементами, позволяющий при желании добавлять эффекты к содержимому страницы за popover-элементами (например, размывать его).

:popover-open

Псевдокласс :popover-open соответствует popover-элементу, только когда он находится в состоянии show — может быть использован для стилизации popover-элементов, когда они показываются.

Интерфейсы

ToggleEvent

ToggleEvent — это событие, уведомляющее пользователя, когда состояние popover-элемента переключается между show и hide. Это объект события для событий beforetoggle и toggle, срабатывающих на popover-элементах при изменении их состояния.

Расширения других интерфейсов

Свойства экземпляра

HTMLElement.popover — Получает и устанавливает состояние popover-элемента с помощью JavaScript (auto или manual) и может быть использовано для определения возможностей. Отражает значение глобального HTML атрибута popover.

HTMLButtonElement.popoverTargetElement и HTMLInputElement.popoverTargetElement — Получают и устанавливают popover-элемент, которым управляет управляющая кнопка. JavaScript-эквивалент HTML-атрибута popovertarget.

HTMLButtonElement.popoverTargetAction и HTMLInputElement.popoverTargetAction — Получают и задают действие, которое должно быть выполнено (hide, show или toggle) над popover-элементом, управляемым кнопкой управления. Отражает значение HTML атрибута popovertargetaction.

Методы экземпляра

HTMLElement.hidePopover()

Метод hidePopover() интерфейса HTMLElement скрывает popover-элемент (т. е. тот, который имеет валидный атрибут popover), удаляя его из верхнего слоя и стилизуя его с display: none.

При вызове hidePopover() на отображаемом элементе с атрибутом popover будет запущено событие beforetoggle, затем popover-элемент будет скрыт, а затем сработает событие toggle. Если элемент уже скрыт, будет выдана ошибка.

HTMLElement.showPopover()

Метод showPopover() интерфейса HTMLElement показывает popover-элемент (т.е. тот, который имеет валидный атрибут popover), добавляя его в верхний слой.

Когда showPopover() вызывается на элементе с атрибутом popover, который в данный момент скрыт, срабатывает событие beforetoggle, затем показывается popover-элемент, а затем срабатывает событие toggle. Если элемент уже отображается, будет выдана ошибка.

HTMLElement.togglePopover()

Метод togglePopover() интерфейса HTMLElement переключает popover-элемент (т.е. тот, который имеет валидный атрибут popover) между состояниями hide и show.

Когда togglePopover() вызывается на элементе с атрибутом popover:

• Возникает событие beforetoggle.
• Popover-элемент переключается между состояниями hide и show:
  • Если он изначально был показан, он переключается на hide.
  • Если он был изначально скрыт, он переключается на show.
• Возникает событие toggle.

События

Событие beforetoggle

Событие beforetoggle интерфейса HTMLElement срабатывает на popover-элементе (т.е. элементе, имеющем валидный атрибут popover) непосредственно перед тем, как он будет показан или скрыт.

• Если popover-элемент переходит от hide к show, свойство event.oldState будет установлено в closed, а свойство event.newState — в open.
• Если popover-элемент переходит от show к hide, то event.oldState будет open, а event.newState — closed.

Событие toggle

Событие toggle интерфейса HTMLElement срабатывает для popover-элемента (т.е. элемента, имеющего валидный атрибут popover) сразу после его показа или скрытия.

• Если popover-элемент переходит из состояния hide в show, свойство event.oldState будет установлено в closed, а свойство event.newState — в open.
• Если popover-элемент переходит от show к hide, то event.oldState будет open, а event.newState — closed.

Примеры

Смотрите страницу Popover API examples, чтобы получить доступ к полной коллекции примеров всплывающих окон MDN.

Также различные примеры доступны в статье Введение в Popover API

Спецификации

• HTML Standard # dom-popover