Перейти к основному содержанию Перейти к навигации по документам
Cмотреть на GitHub

Информеры

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

Обзор

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

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

Эффект анимации этого компонента зависит от медиазапроса 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="Заголовок всплывающего сообщения" data-bs-content="А вот и потрясающий контент. Это очень интересно. Правильно?">Нажмите, чтобы переключить всплывающее окно</button>

Четыре направления

Четыре параметра выравнивания доступны: верх, право, низ, лево.

<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-content="Верхнее всплывающее окно">
  Всплывающее окно вверху
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="right" data-bs-content="Правое всплывающее окно">
  Всплывающее окно справа
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="bottom" data-bs-content="Нижнее всплывающее окно">
  Всплывающее окно внизу
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="left" data-bs-content="Левое всплывающее окно">
  Всплывающее окно слева
</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="Отклоняемое всплывающее окно" data-bs-content="А вот и потрясающий контент. Это очень интересно. Правильно?">Отклоняемое всплывающее окно</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" tabindex="0" data-bs-toggle="popover" data-bs-trigger="hover focus" data-bs-content="Disabled popover">
  <button class="btn btn-primary" type="button" disabled>Отключенная кнопка</button>
</span>

Sass

Переменные

$popover-font-size:                 $font-size-sm;
$popover-bg:                        $white;
$popover-max-width:                 276px;
$popover-border-width:              $border-width;
$popover-border-color:              rgba($black, .2);
$popover-border-radius:             $border-radius-lg;
$popover-inner-border-radius:       subtract($popover-border-radius, $popover-border-width);
$popover-box-shadow:                $box-shadow;

$popover-header-bg:                 shade-color($popover-bg, 6%);
$popover-header-color:              $headings-color;
$popover-header-padding-y:          .5rem;
$popover-header-padding-x:          $spacer;

$popover-body-color:                $body-color;
$popover-body-padding-y:            $spacer;
$popover-body-padding-x:            $spacer;

$popover-arrow-width:               1rem;
$popover-arrow-height:              .5rem;
$popover-arrow-color:               $popover-bg;

$popover-arrow-outer-color:         fade-in($popover-border-color, .05);

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

Активируйте поповеры через 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 переместит пользователя клавиатуры в сам поповер. Короче говоря, простое добавление интерактивных элементов управления в поповер может сделать эти элементы управления недоступными / непригодными для пользователей клавиатуры и пользователей вспомогательных технологий или, по крайней мере, создать нелогичный общий порядок фокусировки. В этих случаях рассмотрите возможность использования модального диалога.

Параметры

Параметры могут передаваться через атрибуты данных или JavaScript. Для атрибутов данных добавьте имя параметра к data-bs-, как в data-bs-animation="". Обязательно измените тип case имени опции с camelCase на kebab-case при передаче через атрибуты данных. Например: вместо использования data-bs-customClass="beautifier" используйте data-bs-custom-class="beautifier".

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

Наименование Тип По умолчанию Описание
animation boolean true Применить переход CSS fade к всплывающему окну
container string | element | false false

Добавляет всплывающее окно к определенному элементу. Пример: container: 'body'. Этот параметр особенно полезен тем, что позволяет Вам размещать всплывающее окно в потоке документа рядом с элементом запуска, что предотвращает отрыв всплывающего окна от элемента запуска во время изменения размера окна.

content string | element | function ''

Значение содержимого по умолчанию, если атрибут data-bs-content отсутствует.

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

delay number | object 0

Задержка показа и скрытия всплывающего окна (мс) - не относится к ручному типу триггера

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

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

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

Как разместить всплывающее сообщение - auto | top | bottom | left | right.
Когда auto, всплывающее окно будет динамически переориентировано.

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

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 всплывающего окна будет вставлен в .popover-header.

content всплывающего окна будет вставлен в .popover-body.

.popover-arrow станет стрелкой всплывающего окна.

Самый внешний элемент оболочки должен иметь класс .popover.

title string | element | function ''

Значение заголовка по умолчанию, если атрибут title отсутствует.

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

trigger string 'click' Как запускается всплывающее окно - click | hover | focus | manual. Вы можете передать несколько триггеров; разделите их пробелом. manual нельзя комбинировать с другими триггерами.
fallbackPlacements array ['top', 'right', 'bottom', 'left'] Определите резервные места размещения, предоставив список мест размещения в массиве (в порядке предпочтения). Дополнительную информацию смотрите в документации о поведении Popper.
boundary string | element 'clippingParents' Граница ограничения переполнения всплывающего окна. По умолчанию это 'clippingParents' и может принимать ссылку HTMLElement (только JavaScript). Дополнительную информацию смотрите в preventOverflow документации Popper.
customClass string | function ''

Добавляйте классы в всплывающее окно, когда оно отображается. Обратите внимание, что эти классы будут добавлены в дополнение к любым классам, указанным в шаблоне. Чтобы добавить несколько классов, разделите их пробелами: 'class-1 class-2'.

Вы также можете передать функцию, которая должна возвращать одну строку, содержащую дополнительные имена классов.

sanitize boolean true Включите или отключите дезинфекцию. Если активированы параметры 'template', 'content' и 'title', будут очищены. Смотрите раздел очистки в нашей документации по JavaScript.
allowList object Значение по умолчанию Объект, содержащий разрешенные атрибуты и теги
sanitizeFn null | function null Здесь Вы можете предоставить свою собственную функцию дезинфекции. Это может быть полезно, если Вы предпочитаете использовать специальную библиотеку для выполнения очистки.
offset array | string | function [0, 0]

Смещение всплывающего окна относительно его цели. Вы можете передать строку в атрибутах данных со значениями, разделенными запятыми, например: data-bs-offset="10,20"

Когда функция используется для определения смещения, она вызывается с объектом, содержащим размещение popper, ссылку и popper rects в качестве первого аргумента. Узел DOM запускающего элемента передается в качестве второго аргумента. Функция должна возвращать массив с двумя числами: [skidding, distance].

Дополнительную информацию смотрите в offset документации Popper.

popperConfig null | object | function null

Чтобы изменить конфигурацию Popper по умолчанию для Bootstrap, смотрите конфигурацию Popper.

Когда функция используется для создания конфигурации Popper, она вызывается с объектом, который содержит конфигурацию Popper по умолчанию для Bootstrap. Это поможет вам использовать и объединить настройки по умолчанию с вашей собственной конфигурацией. Функция должна возвращать объект конфигурации для Popper.

Атрибуты для индивидуальных всплывающих окон

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

Использование функции с popperConfig

var popover = new bootstrap.Popover(element, {
  popperConfig: function (defaultBsPopperConfig) {
    // var newPopperConfig = {...}
    // use defaultBsPopperConfig if needed...
    // return newPopperConfig
  }
})

Методы

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

Все методы 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 () {
  // сделайте что-нибудь...
})