Информеры

Документация и примеры добавления всплывающих подсказок Bootstrap, таких как в iOS, к любому элементу на вашем сайте.

Обзор

Вот что надо знать для эффективного использования плагина всплывающих элементов (поповеров):

  • Таковой плагин использует для позиционирования 3-ю часть библиотеки Popper.js. Чтобы плагин работал, Вы должны подключать popper.min.js ПЕРЕД bootstrap.js, или использовать bootstrap.bundle.min.js / bootstrap.bundle.js – содержащие Popper.js!
  • Поповеры требуют плагина всплывающих подсказок в качестве зависимости.
  • Если вы подключаете ваш JavaScript в виде файла, вам потребуется util.js.
  • Поповеры не подключены по умолчанию по причинам производительности, так что вы должны инициализировать их самостоятельно.
  • Для работы плагина значения title and content не должны быть нулевыми.
  • Задавайте container: 'body' для избегания проблем с отрисовкой в более сложных компонентах (таких как группы ввода, кнопок, т.д.)
  • Запуск поповеров на скрытых элементах не работает.
  • Поповеры для элементов класса .disabled or disabled должны запускаться на «оборачивающем» элементе.
  • Когда поповеры запущены из ссылок, которые оборачивают множественные строки, всплывающие элементы будут центрироваться по общей ширине ссылок. Используйте white-space: nowrap; в ваших <a>, чтобы избежать этого.
  • Поповеры должны быть скрыты до того, как соответствующие им элементы будут удалены из DOM.

Эффект анимации этого компонента зависит от медиазапроса prefers-reduced-motion. Смотрите раздел с ограниченным движением в нашей документации о доступности.

Ниже несколько примеров.

Пример: включайте поповеры везде

Один из способов инициализации всех поповеров на странице – выбрать их по атрибутам data-toggle:

$(function () {
  $('[data-toggle="popover"]').popover()
})

Пример: использование параметра container

Когда у вас есть некие стили родительского элемента, которые взаимодействуют с поповером, вам потребуется создать обычный container - так, чтобы HTML ВЭ появлялся внутри того элемента.

$(function () {
  $('.example-popover').popover({
    container: 'body'
  })
})

Пример

<button type="button" class="btn btn-lg btn-danger" data-toggle="popover" title="Popover title" data-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-container="body" data-toggle="popover" data-placement="top" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  Popover on top
</button>

<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="right" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  Popover on right
</button>

<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="bottom" data-content="Vivamus
sagittis lacus vel augue laoreet rutrum faucibus.">
  Popover on bottom
</button>

<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="left" data-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-toggle="popover" data-trigger="focus" title="Dismissible popover" data-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a>
$('.popover-dismiss').popover({
  trigger: 'focus'
})

Отключение элементов

Неактивные элементы с атрибутом disabled не являются интерактивными, т.е. юзеры не могут кликать на них для вызова поповера (или всплывающей подсказки) и по наведению их стиль не изменится. Как один из "обходных способов" - можно запустить поповер из оборачивающего элемента <div> или <span> и "преодолеть" событие pointer-events дезактивированных элементов.

Для дезактивированных элементов-триггеров поповеров также можно задать data-trigger="hover", что заставит поповер визуально "откликаться" на наведение, т.к. юзеры могут и не захотеть кликнуть на дезактивированный элемент.

<span class="d-inline-block" data-toggle="popover" data-content="Disabled popover">
  <button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button>
</span>

Использование

Активируйте поповеры через JavaScript:

$('#example').popover(options)
GPU ускорение

Всплывающие окна иногда выглядят размытыми на устройствах с Windows 10 из-за ускорения графического процессора и измененного системного DPI. Чтобы решить эту проблему в версии 4, необходимо отключить ускорение графического процессора в ваших всплывающих окнах.

Предлагаемое исправление:

Popper.Defaults.modifiers.computeStyle.gpuAcceleration = !(window.devicePixelRatio < 1.5 && /Win/.test(navigator.platform))

Заставка всплывающих окон работает для клавиатуры и вспомогательных технологий

Чтобы пользователи клавиатуры могли активировать всплывающие окна, вы должны добавить их только в те элементы HTML, которые традиционно ориентированы на клавиатуру и интерактивны (например, ссылки или элементы управления формой). Хотя произвольные элементы HTML (такие как <span>) можно сделать фокусируемыми, добавив атрибут tabindex="0", это добавит потенциально раздражающие и сбивающие с толку позиции табуляции для неинтерактивных элементов для пользователей клавиатуры, и большинство вспомогательных технологий в настоящее время делают это Не объявляйте содержание поповера в этой ситуации. Кроме того, не полагайтесь исключительно на hover в качестве триггера для ваших всплывающих окон, поскольку это сделает невозможным их запуск для пользователей клавиатуры.

Хотя вы можете вставить расширенный структурированный HTML-код в всплывающие окна с помощью параметров html, мы настоятельно рекомендуем вам избегать добавления чрезмерного количества контента. В настоящее время всплывающие окна работают так, что после отображения их содержимое привязывается к элементу триггера с атрибутом aria-describedby. В результате весь контент будет объявлен как один длинный непрерывный поток.

Кроме того, хотя вы можно включить интерактивные элементы управления (например, элементы формы или ссылки) (добавив эти элементы в whiteList или разрешенные атрибуты и теги), имейте в виду, что в данный момент поповер не управляет порядком фокусировки клавиатуры. Когда пользователь клавиатуры открывает поповер, фокус остается на триггерном элементе, и поскольку поповер обычно не следует сразу за триггером в структуре документа, нет гарантии, что перемещение вперед / нажатие клавиши TAB переместит пользователя клавиатуры в сам поповер. Короче говоря, простое добавление интерактивных элементов управления в поповер может сделать эти элементы управления недоступными / непригодными для пользователей клавиатуры и пользователей вспомогательных технологий или, по крайней мере, создать нелогичный общий порядок фокусировки. В этих случаях рассмотрите возможность использования модального диалога.

Параметры

Параметры можно передавать через атрибуты или JS. В случае атрибутов добавляйте нужное название к data-, как в data-animation="".

Обратите внимание, что по соображениям безопасности параметры sanitize, sanitizeFn и whiteList не могут быть предоставлены с использованием атрибутов данных.

Название Тип По умолчанию Описание
animation boolean true Применяет CSS переход «угасание» к поповеру.
container string | element | false false

Добавляет поповер к элементу. Пример: container: 'body'. Этот параметр в частности позволяет позиционировать поповер в «потоке документа» рядом с элементом-триггером – что предотвратит «уплывание» поповера при изменении размера экрана.

content string | element | function ''

Дефолтное значение содержимого, если атрибут data-content не существует.

Если функция задана, этот параметр будет вызван к элементу, к которому прикреклен поповер, ее экземпляром this.

delay number | object 0

Откладывает показ и скрытие поповера (милисекунды) – не применяется к типу «триггер вручную».

Если число задано, отсрочка применяется и к показу, и к скрытию.

Структура объекта такова: delay: { "show": 500, "hide": 100 }.

html boolean false Вводит HTML-код в поповер. Если «false», для вставки контента в DOM будет использован текстовый метод jQuery. Используйте, если вы беспокоитесь насчет XSS-атак.
placement string | function 'right'

Позволяет позиционировать поповер – авто | верх | низ | лево | право.
Когда auto - динамически переориентирует поповер.

Когда функция используется для определения расположения, она вызывается «узлом» поповера в DOM, который выступает как первый аргумент, и запускающий элемент «узла» DOM – как второй. Контекст this задается экземпляру поповера.

selector string | false false Если селектор задан, объекты поповера будут «делегированы» определенным «целям». На практике это используется для активации возможности добавления поповеров в динамическое содержимое HTML. Смотри сюда и сюда.
template string '<div class="popover" role="tooltip"><div class="arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'

Обычный HTML для использования при создании поповера.

title поповера будет введен в класс .popover-header.

content поповера будет введен в класс .popover-body.

.arrow станет «стрелочкой» поповера.

Элемент, куда обернуты все остальные – должен иметь класс .popover.

title string | element | function ''

Дефолтное название, если title не задан.

Если функция задана, этот параметр будет вызван к элементу, к которому прикреклен поповер, ее экземпляром this.

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). Для информации – документы по предотвращению Оверфлоу.
sanitize boolean true Включить или отключить санацию. Если активированы 'template', 'content' и 'title' будут очищены.
whiteList object Default value Объект, который содержит допустимые атрибуты и теги
sanitizeFn null | function null Здесь вы можете предоставить свою собственную функцию очистки. Это может быть полезно, если вы предпочитаете использовать выделенную библиотеку для выполнения очистки.
popperConfig null | object null Чтобы изменить конфигурацию Popper.js по умолчанию в Bootstrap, смотрите Конфигурацию Popper.js.

Атрибуты для индивидуальных поповеров

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

Методы

Асинхронные методы и переходы

Все методы API асинхронны и запускают переход. Они возвращаются функции, вызвавшей их, с началом перехода, но до его конца. Плюс, вызов метода к компоненту, выполняющему переход, будет проигнорирован.

Смотрите документацию JavaScript для информации.

$().popover(options)

Инициализирует поповеры для коллекции элементов.

.popover('show')

Выявляет поповер элемента. Возвращается к функции-вызову до того, как поповер показан (т.е. до того, как произойдет событие shown.bs.popover). Расценивается как «ручной» запуск поповера. Поповеры, чьи название и содержимое есть значения нулевой длины – никогда не отображаются.

$('#element').popover('show')

.popover('hide')

Скрывает поповер элемента. Возвращается к функции-вызову до того, как модальный элемент скрыт. (т.е. до того, как произойдет событие hidden.bs.popover). Расценивается как «ручной» запуск поповера.

$('#element').popover('hide')

.popover('toggle')

Изменяет состояние поповера. Возвращается к функции-вызову до того, как модальный элемент скрыт. (т.е. до того, как произойдут события shown.bs.popover или hidden.bs.popover). Расценивается как «ручной» запуск поповера.

$('#element').popover('toggle')

.popover('dispose')

Скрывает и уничтожает поповер элемента. Поповеры, которые используют делегирование (т.е. которые созданы параметром селектора), не могут быть уничтожены по одному из нижестоящих элементов-триггеров.

$('#element').popover('dispose')

.popover('enable')

Дает поповеру элемента возможность быть показанным. Поповеры включены по умолчанию.

$('#element').popover('enable')

.popover('disable')

Удаляет у поповера элемента возможность быть показанным. Поповер будет иметь возможность показанным лишь если он пере-включен.

$('#element').popover('disable')

.popover('toggleEnabled')

Переключает возможность поповера элемента быть показанным или скрытым.

$('#element').popover('toggleEnabled')

.popover('update')

Обновляет позицию поповера элемента.

$('#element').popover('update')

События

Тип события Описание
show.bs.popover Это событие наступает немедленно, когда вызван экземпляр метода show.
shown.bs.popover Это событие наступает, когда поповер только что сделан видимым юзеру (будет ждать завершения переходов CSS).
hide.bs.popover Это событие наступает немедленно, когда только что вызван экземпляр метода hide.
hidden.bs.popover Это событие наступает, когда поповер только что перестал быть скрытым от юзера (будет ждать завершения переходов CSS).
inserted.bs.popover Это событие наступает после события show.bs.popover, когда шаблон поповера только что добавлен в DOM.
$('#myPopover').on('hidden.bs.popover', function () {
  // do something…
})