Информеры
Документация и примеры добавления всплывающих окон Bootstrap к любому элементу на вашем сайте, подобных тем, какие есть в iOS.
Обзор
Вот что надо знать для эффективного использования плагина всплывающих элементов подсказки (поповеров):
- Плагин использует стороннюю библиотеку Popper.js для позиционирования. Чтобы всплывающие окна работали Вы должны подключать popper.min.js перед bootstrap.js или использовать
bootstrap.bundle.min.js
/bootstrap.bundle.js
– содержащие Popper.js! - Поповеры требуют плагина всплывающих подсказок в качестве зависимости.
- Всплывающие подсказки (поповеры) не подключены по умолчанию по причинам производительности, так что вы должны инициализировать их самостоятельно.
- Для работы плагина значения
title
andcontent
не должны быть нулевыми. - Задавайте
container: 'body'
для избегания проблем с отрисовкой в более сложных компонентах (таких как группы ввода, кнопок, т.д.) - Запуск поповеров на скрытых элементах не работает.
- Поповеры для элементов класса
.disabled
ordisabled
должны запускаться на «оборачивающем» элементе. - Когда поповеры запущены из ссылок, которые оборачивают множественные строки, всплывающие элементы будут центрироваться по общей ширине ссылок. Используйте
white-space: nowrap;
в ваших<a>
, чтобы избежать этого. - Поповеры должны быть скрыты до того, как соответствующие им элементы будут удалены из DOM.
- Всплывающие подсказки могут запускаться благодаря элементу внутри теневой DOM.
Эффект анимации этого компонента зависит от медиазапроса prefers-reduced-motion
. Смотрите раздел с ограниченным движением в нашей документации о доступности.
Ниже несколько примеров.
Пример: включайте поповеры везде
Один из способов инициализации всех поповеров на странице – выбрать их по атрибутам data-bs-toggle
:
var popoverTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="popover"]'))
var popoverList = popoverTriggerList.map(function (popoverTriggerEl) {
return new bootstrap.Popover(popoverTriggerEl)
})
Пример: использование параметра container
Когда у вас есть некие стили родительского элемента, которые взаимодействуют с поповером, вам потребуется создать обычный container
- так, чтобы HTML-код отображался внутри этого элемента.
var popover = new bootstrap.Popover(document.querySelector('.example-popover'), {
container: 'body'
})
Пример
<button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="Popover title" data-bs-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>
Четыре направления
Четыре параметра выравнивания доступны: верх, право, низ, лево.
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
Popover on top
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="right" data-bs-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
Popover on right
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="bottom" data-bs-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
Popover on bottom
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="left" data-bs-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
Popover on left
</button>
Отмена по клику
Используйте триггер focus
для закрытия поповеров по клику на другом элементе или вне поповера.
Для такого поведения нужна специальная разметка
Для правильного кросс-браузерного и кросс-платформенного поведения, описанного в «Отмене по клику» выше – надо использовать не тэг <button>
, а <a>
, также вы можете подключить атрибут tabindex
.
<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" title="Dismissible popover" data-bs-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a>
var popover = new bootstrap.Popover(document.querySelector('.popover-dismiss'), {
trigger: 'focus'
})
Отключение элементов
Неактивные элементы с атрибутом disabled
не являются интерактивными, т.е. юзеры не могут кликать на них для вызова поповера (или всплывающей подсказки) и по наведению их стиль не изменится. Как один из "обходных способов" - можно запустить поповер из оборачивающего элемента <div>
или <span>
и "преодолеть" событие pointer-events
дезактивированных элементов.
Для дезактивированных элементов-триггеров поповеров также можно задать data-bs-trigger="hover"
, что заставит поповер визуально "откликаться" на наведение, т.к. юзеры могут и не захотеть кликнуть на дезактивированный элемент.
<span class="d-inline-block" data-bs-toggle="popover" data-bs-content="Disabled popover">
<button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button>
</span>
Использование
Активируйте поповеры через JavaScript:
var exampleEl = document.getElementById('example')
var popover = new bootstrap.Popover(exampleEl, options)
Заставка всплывающих окон работает для клавиатуры и вспомогательных технологий
Чтобы пользователи клавиатуры могли активировать всплывающие окна, вы должны добавить их только в те элементы HTML, которые традиционно ориентированы на клавиатуру и интерактивны (например, ссылки или элементы управления формой). Хотя произвольные элементы HTML (такие как <span>
) можно сделать фокусируемыми, добавив атрибут tabindex="0"
, это добавит потенциально раздражающие и сбивающие с толку позиции табуляции для неинтерактивных элементов для пользователей клавиатуры, и большинство вспомогательных технологий в настоящее время делают это Не объявляйте содержание поповера в этой ситуации. Кроме того, не полагайтесь исключительно на hover
в качестве триггера для ваших всплывающих окон, поскольку это сделает невозможным их запуск для пользователей клавиатуры.
Хотя вы можете вставить расширенный структурированный HTML-код в всплывающие окна с помощью параметров html
, мы настоятельно рекомендуем вам избегать добавления чрезмерного количества контента. В настоящее время всплывающие окна работают так, что после отображения их содержимое привязывается к элементу триггера с атрибутом aria-describedby
. В результате весь контент будет объявлен как один длинный непрерывный поток.
Кроме того, хотя вы можно включить интерактивные элементы управления (например, элементы формы или ссылки) (добавив эти элементы в whiteList
или разрешенные атрибуты и теги), имейте в виду, что в данный момент поповер не управляет порядком фокусировки клавиатуры. Когда пользователь клавиатуры открывает поповер, фокус остается на триггерном элементе, и поскольку поповер обычно не следует сразу за триггером в структуре документа, нет гарантии, что перемещение вперед / нажатие клавиши TAB переместит пользователя клавиатуры в сам поповер. Короче говоря, простое добавление интерактивных элементов управления в поповер может сделать эти элементы управления недоступными / непригодными для пользователей клавиатуры и пользователей вспомогательных технологий или, по крайней мере, создать нелогичный общий порядок фокусировки. В этих случаях рассмотрите возможность использования модального диалога.
Параметры
Параметры можно передавать через атрибуты или JS. В случае атрибутов добавляйте нужное название к data-bs-
, как в data-bs-animation=""
.
Обратите внимание, что по соображениям безопасности параметры sanitize
, sanitizeFn
и whiteList
не могут быть предоставлены с использованием атрибутов данных.
Название | Тип | По умолчанию | Описание |
---|---|---|---|
animation |
boolean | true |
Применяет CSS переход «угасание» к поповеру. |
container |
string | element | false | false |
Добавляет поповер к элементу. Пример: |
content |
string | element | function | '' |
Дефолтное значение содержимого, если атрибут Если функция задана, этот параметр будет вызван к элементу, к которому прикреклен поповер, ее экземпляром |
delay |
number | object | 0 |
Откладывает показ и скрытие поповера (милисекунды) – не применяется к типу «триггер вручную». Если число задано, отсрочка применяется и к показу, и к скрытию. Структура объекта такова: |
html |
boolean | false |
Вводит HTML-код в поповер. Если «false», для вставки контента в DOM будет использован текстовый метод jQuery. Используйте, если вы беспокоитесь насчет XSS-атак. |
placement |
string | function | 'right' |
Позволяет позиционировать поповер – авто | верх | низ | лево | право. Когда функция используется для определения расположения, она вызывается «узлом» поповера в DOM, который выступает как первый аргумент, и запускающий элемент «узла» DOM – как второй. Контекст |
selector |
string | false | false |
Если селектор задан, объекты поповера будут «делегированы» определенным «целям». На практике это используется для активации возможности добавления поповеров в динамическое содержимое HTML. Смотрите здесь и здесь. |
template |
string | '<div class="popover" role="tooltip"><div class="popover-arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>' |
Обычный HTML для использования при создании поповера.
Элемент, куда обернуты все остальные – должен иметь класс |
title |
string | element | function | '' |
Дефолтное название, если Если функция задана, этот параметр будет вызван к элементу, к которому прикреклен поповер, ее экземпляром |
trigger |
string | 'click' |
Задает то, как поповер вызывается - клик | hover | focus | вручную. Вы можете передать множественные триггеры: разделите их пробелом. «Вручную» (manual) нельзя сочетать с прочими. |
offset |
number | string | 0 |
Отступ поповера относитеьлно его «цели». Для информации идите обратитесь к документам по отступам в Popper.js |
fallbackPlacement |
string | array | 'flip' |
Позволяет задать, на какой позиции Popper встанет при откате. Для информации - сюда. |
boundary |
string | element | 'scrollParent' |
Ограничивает отображение границ поповера, если он целиком не помещается и выходит за область заданных размеров. Принимает значения 'viewport' , 'window' , 'scrollParent' , или отсылку к элементу HTML (через JavaScript). Для информации – документы по предотвращению Оверфлоу. |
customClass |
string | function | '' |
Добавmnt классы в всплывающее окнопри отображении. Обратите внимание, что эти классы будут добавлены в дополнение к любым классам, указанным в шаблоне. Чтобы добавить несколько классов, разделите их пробелами: Вы также можете передать функцию, которая должна возвращать одну строку, содержащую дополнительные имена классов. |
sanitize |
boolean | true |
Включить или отключить санацию. Если активированы 'template' , 'content' и 'title' будут очищены. |
allowList |
object | Default value | Объект, содержащий разрешенные атрибуты и теги |
sanitizeFn |
null | function | null |
Здесь вы можете предоставить свою собственную функцию очистки. Это может быть полезно, если вы предпочитаете использовать выделенную библиотеку для выполнения очистки. |
popperConfig |
null | object | null |
Чтобы изменить конфигурацию Popper.js по умолчанию в Bootstrap, смотрите Конфигурацию Popper.js |
Атрибуты для индивидуальных поповеров
Параметры для индивидуальных поповеров могут также задаваться через использование атрибутов, как показано ниже.
Методы
Асинхронные методы и переходы
Все методы API асинхронны и запускают переход. Они возвращаются функции, вызвавшей их, с началом перехода, но до его конца. Плюс, вызов метода к компоненту, выполняющему переход, будет проигнорирован.
Для информации смотрите документацию по JavaScript
show
Выявляет поповер элемента. Возвращается к функции-вызову до того, как поповер показан (т.е. до того, как произойдет событие shown.bs.popover
). Расценивается как «ручной» запуск поповера. Поповеры, чьи название и содержимое есть значения нулевой длины – никогда не отображаются.
myPopover.show()
hide
Скрывает поповер элемента. Возвращается к функции-вызову до того, как модальный элемент скрыт. (т.е. до того, как произойдет событие hidden.bs.popover
). Расценивается как «ручной» запуск поповера.
myPopover.hide()
toggle
Изменяет состояние поповера. Возвращается к функции-вызову до того, как модальный элемент скрыт. (т.е. до того, как произойдут события shown.bs.popover
или hidden.bs.popover
). Расценивается как «ручной» запуск поповера.
myPopover.toggle()
dispose
Скрывает и уничтожает поповер элемента. Поповеры, которые используют делегирование (т.е. которые созданы параметром селектора), не могут быть уничтожены по одному из нижестоящих элементов-триггеров.
myPopover.dispose()
enable
Дает поповеру элемента возможность быть показанным. Поповеры включены по умолчанию.
myPopover.enable()
disable
Удаляет у поповера элемента возможность быть показанным. Поповер будет иметь возможность показанным лишь если он пере-включен.
myPopover.disable()
toggleEnabled
Переключает возможность поповера элемента быть показанным или скрытым.
myPopover.toggleEnabled()
update
Обновляет позицию поповера элемента.
myPopover.update()
getInstance
Статический метод, который позволяет вам получить экземпляр всплывающего окна, связанный с элементом DOM
var exampleTriggerEl = document.getElementById('example')
var popover = bootstrap.Popover.getInstance(exampleTriggerEl) // Returns a Bootstrap popover instance
События
Тип события | Описание |
---|---|
show.bs.popover | Это событие наступает немедленно, когда вызван экземпляр метода show . |
shown.bs.popover | Это событие наступает, когда поповер только что сделан видимым юзеру (будет ждать завершения переходов CSS). |
hide.bs.popover | Это событие наступает немедленно, когда только что вызван экземпляр метода hide . |
hidden.bs.popover | Это событие наступает, когда поповер только что перестал быть скрытым от юзера (будет ждать завершения переходов CSS). |
inserted.bs.popover | Это событие наступает после события show.bs.popover , когда шаблон поповера только что добавлен в DOM. |
var myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', function () {
// do something...
})