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

Всплывающие окна

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

Обзор

Что нужно знать при использовании плагина popover:

  • Поповеры полагаются на стороннюю библиотеку Popper для позиционирования. Вы должны включить popper.min.js перед bootstrap.js или использовать один bootstrap.bundle.min.js, который содержит Popper.
  • Для всплывающих окон требуется плагин popover в качестве зависимости.
  • Всплывающие окна добавляются из соображений производительности, поэтому вы должны инициализировать их самостоятельно.
  • Значения нулевой длины title и content никогда не будут показывать всплывающее окно.
  • Укажите container: 'body', чтобы избежать проблем с рендерингом в более сложных компонентах (таких как наши группы ввода, группы кнопок и т. д.).
  • Запуск всплывающих окон на скрытых элементах не будет работать.
  • Всплывающие окна для элементов .disabled или disabled должны запускаться для элемента-оболочки.
  • При запуске от якорей, которые охватывают несколько строк, всплывающие окна будут центрированы между общей шириной якорей. Используйте .text-nowrap для <a>, чтобы избежать такого поведения.
  • Всплывающие окна должны быть скрыты до того, как соответствующие им элементы будут удалены из DOM.
  • Всплывающие окна могут быть вызваны благодаря элементу внутри теневого DOM.
По умолчанию этот компонент использует встроенное средство очистки содержимого, которое удаляет все элементы HTML, которые не разрешены явно. Дополнительные сведения смотрите в разделе очистки в нашей документации по JavaScript.
Эффект анимации этого компонента зависит от медиазапроса prefers-reduced-motion. См. раздел с уменьшенным движением в нашей документации по специальным возможностям.

Продолжайте читать, чтобы увидеть, как работают всплывающие окна с некоторыми примерами.

Примеры

Включить всплывающие окна

Как упоминалось выше, вы должны инициализировать всплывающие окна, прежде чем их можно будет использовать. Один из способов инициализировать все всплывающие окна на странице — выбрать их по их атрибуту data-bs-toggle, например:

const popoverTriggerList = document.querySelectorAll('[data-bs-toggle="popover"]')
const popoverList = [...popoverTriggerList].map(popoverTriggerEl => new bootstrap.Popover(popoverTriggerEl))

Живая демонстрация

Мы используем JavaScript, аналогичный приведенному выше фрагменту кода, для отображения следующего живого всплывающего окна. Заголовки устанавливаются с помощью data-bs-title, а содержимое тела устанавливается с помощью data-bs-content.

Не стесняйтесь использовать title или data-bs-title в своем HTML. Когда используется title, Popper автоматически заменяет его на data-bs-title при отображении элемента.
html
<button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" data-bs-title="Заголовок всплывающего окна" data-bs-content="А вот и потрясающий контент. Это очень увлекательно. Верно?">Нажмите, чтобы переключить всплывающее окно</button>

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

Доступны четыре варианта: верхний, правый, нижний и левый. Направления отражаются при использовании Bootstrap в RTL. Установите data-bs-placement, чтобы изменить направление.

html
<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>

Пользовательский container

Если у вас есть некоторые стили в родительском элементе, которые мешают всплывающему меню, вам нужно указать пользовательский container, чтобы HTML-код всплывающего окна вместо этого отображался внутри этого элемента. Это часто встречается в адаптивных таблицах, группах ввода и т.п.

const popover = new bootstrap.Popover('.example-popover', {
  container: 'body'
})

Другая ситуация, когда вы захотите установить явный пользовательский container, — это всплывающие окна внутри модального диалога, чтобы убедиться, что само всплывающее окно добавлено к модальный. Это особенно важно для всплывающих окон, содержащих интерактивные элементы — модальные диалоги перехватывают фокус, поэтому, если всплывающее окно не является дочерним элементом модального окна, пользователи не смогут сфокусировать или активировать эти интерактивные элементы.

const popover = new bootstrap.Popover('.example-popover', {
  container: '.modal-body'
})

Пользовательские всплывающие окна

Добавлено в версии 5.2.0

Вы можете настроить внешний вид всплывающих окон, используя CSS-переменные. Мы устанавливаем пользовательский класс с data-bs-custom-class="custom-popover", чтобы ограничить наш пользовательский внешний вид и использовать его для переопределения некоторых локальных переменных CSS.

.custom-popover {
  --bs-popover-max-width: 200px;
  --bs-popover-border-color: var(--bd-violet-bg);
  --bs-popover-header-bg: var(--bd-violet-bg);
  --bs-popover-header-color: var(--bs-white);
  --bs-popover-body-padding-x: 1rem;
  --bs-popover-body-padding-y: .5rem;
}
html
<button type="button" class="btn btn-secondary"
        data-bs-toggle="popover" data-bs-placement="right"
        data-bs-custom-class="custom-popover"
        data-bs-title="Пользовательское всплывающее окно"
        data-bs-content="Это всплывающее окно оформлено с помощью переменных CSS.">
  Пользовательское всплывающее окно
</button>

Закрыть при следующем клике

Используйте триггер focus, чтобы закрыть всплывающие окна при следующем клике пользователя по элементу, отличному от переключаемого элемента.

Для закрытия при следующем нажатии требуется специальный HTML-код для правильного кросс-браузерного и кросс-платформенного поведения. Вы можете использовать только элементы <a>, но не <button>, и вы должны включить tabindex.
html
<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" data-bs-title="Отклоняемое всплывающее окно" data-bs-content="А вот и потрясающий контент. Это очень увлекательно. Верно?">Отклоняемое всплывающее окно</a>
const popover = new bootstrap.Popover('.popover-dismiss', {
  trigger: 'focus'
})

Отключенные элементы

Элементы с атрибутом disabled не являются интерактивными, то есть пользователи не могут навести на них курсор или щелкнуть их, чтобы вызвать всплывающее окно (или всплывающую подсказку). В качестве обходного пути вы захотите вызвать всплывающее окно из обертки <div> или <span>, в идеале сделать фокус на клавиатуре с помощью tabindex="0".

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

html
<span class="d-inline-block" tabindex="0" data-bs-toggle="popover" data-bs-trigger="hover focus" data-bs-content="Отключено всплывающее окно">
  <button class="btn btn-primary" type="button" disabled>Кнопка отключена</button>
</span>

CSS

Переменные

Добавлено в версии 5.2.0

Как часть развивающегося подхода Bootstrap к переменным CSS, всплывающие окна теперь используют локальные переменные CSS в .popover для расширенной настройки в реальном времени. Значения переменных CSS задаются через Sass, поэтому настройка Sass по-прежнему поддерживается.

--#{$prefix}popover-zindex: #{$zindex-popover};
--#{$prefix}popover-max-width: #{$popover-max-width};
@include rfs($popover-font-size, --#{$prefix}popover-font-size);
--#{$prefix}popover-bg: #{$popover-bg};
--#{$prefix}popover-border-width: #{$popover-border-width};
--#{$prefix}popover-border-color: #{$popover-border-color};
--#{$prefix}popover-border-radius: #{$popover-border-radius};
--#{$prefix}popover-inner-border-radius: #{$popover-inner-border-radius};
--#{$prefix}popover-box-shadow: #{$popover-box-shadow};
--#{$prefix}popover-header-padding-x: #{$popover-header-padding-x};
--#{$prefix}popover-header-padding-y: #{$popover-header-padding-y};
@include rfs($popover-header-font-size, --#{$prefix}popover-header-font-size);
--#{$prefix}popover-header-color: #{$popover-header-color};
--#{$prefix}popover-header-bg: #{$popover-header-bg};
--#{$prefix}popover-body-padding-x: #{$popover-body-padding-x};
--#{$prefix}popover-body-padding-y: #{$popover-body-padding-y};
--#{$prefix}popover-body-color: #{$popover-body-color};
--#{$prefix}popover-arrow-width: #{$popover-arrow-width};
--#{$prefix}popover-arrow-height: #{$popover-arrow-height};
--#{$prefix}popover-arrow-border: var(--#{$prefix}popover-border-color);

Sass переменные

$popover-font-size:                 $font-size-sm;
$popover-bg:                        var(--#{$prefix}body-bg);
$popover-max-width:                 276px;
$popover-border-width:              var(--#{$prefix}border-width);
$popover-border-color:              var(--#{$prefix}border-color-translucent);
$popover-border-radius:             var(--#{$prefix}border-radius-lg);
$popover-inner-border-radius:       calc(#{$popover-border-radius} - #{$popover-border-width}); // stylelint-disable-line function-disallowed-list
$popover-box-shadow:                var(--#{$prefix}box-shadow);

$popover-header-font-size:          $font-size-base;
$popover-header-bg:                 var(--#{$prefix}secondary-bg);
$popover-header-color:              $headings-color;
$popover-header-padding-y:          .5rem;
$popover-header-padding-x:          $spacer;

$popover-body-color:                var(--#{$prefix}body-color);
$popover-body-padding-y:            $spacer;
$popover-body-padding-x:            $spacer;

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

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

Включить всплывающие окна через JavaScript:

const exampleEl = document.getElementById('example')
const popover = new bootstrap.Popover(exampleEl, options)

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

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

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

Опции

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

Начиная с Bootstrap 5.2.0, все компоненты поддерживают экспериментальный зарезервированный атрибут данных data-bs-config, который может содержать простую конфигурацию компонента в виде строки JSON. Когда элемент имеет атрибуты data-bs-config='{"delay":0, "title":123}' и data-bs-title="456", окончательное значение title будет 456, а отдельные атрибуты данных переопределяют значения, указанные в data-bs-config. Кроме того, существующие атрибуты данных могут содержать значения JSON, такие как data-bs-delay='{"show":0,"hide":150}'.

Окончательный объект конфигурации — это объединенный результат data-bs-config, data-bs- и js object, где последний заданный ключ-значение переопределяет другие.

Обратите внимание, что по соображениям безопасности параметры sanitize, sanitizeFn и allowList не могут быть предоставлены с использованием атрибутов данных.
Название Тип По умолчанию Описание
allowList object Значение по умолчанию Объект, который содержит разрешенные атрибуты и теги.
animation boolean true Применить CSS-переход затухания к поповеру.
boundary string, element 'clippingParents' Граница ограничения переполнения поповера (применяется только к Popper модификатору preventOverflow). По умолчанию это 'clippingParents', и он может принимать ссылку HTMLElement (только через JavaScript). Для получения дополнительной информации обратитесь к документации обнаружения переполнения Popper.
container string, element, false false Добавляет всплывающее окно к определенному элементу. Пример: container: 'body'. Этот параметр особенно удобен тем, что позволяет расположить всплывающее окно в потоке документа рядом с инициирующим элементом, что предотвратит перемещение всплывающего окна от инициирующего элемента во время изменения размера окна.
content string, element, function '' Текстовое содержимое всплывающего окна. Если задана функция, она будет вызываться со ссылкой this, установленной на элемент, к которому прикреплено всплывающее окно.
customClass string, function '' Добавляйте классы во всплывающее окно, когда оно отображается. Обратите внимание, что эти классы будут добавлены в дополнение к любым классам, указанным в шаблоне. Чтобы добавить несколько классов, разделите их пробелами: 'class-1 class-2'. Вы также можете передать функцию, которая должна возвращать одну строку, содержащую дополнительные имена классов.
delay number, object 0 Задержка отображения и скрытия всплывающего окна (мс) — не относится к ручному типу триггера. Если указано число, задержка применяется как для скрытия, так и для показа. Структура объекта: delay: { "show": 500, "hide": 100 }.
fallbackPlacements string, array ['top', 'right', 'bottom', 'left'] Определите резервные места размещения, предоставив список мест размещения в виде массива (в порядке предпочтения). Для получения дополнительной информации обратитесь к документации о поведении Popper.
html boolean false Разрешить HTML во всплывающем окне. Если true, теги HTML в title всплывающего окна будут отображаться во всплывающем окне. Если false, свойство innerText будет использоваться для вставки содержимого в DOM. Используйте текст, если вы беспокоитесь о XSS-атаках.
offset number, string, function [0, 0] Смещение всплывающего окна относительно его цели. Вы можете передать строку в атрибутах данных со значениями, разделенными запятыми, например: data-bs-offset="10,20". Когда функция используется для определения смещения, она вызывается с объектом, содержащим размещение поппера, ссылку и прямоугольники поппера в качестве первого аргумента. Узел триггерного элемента DOM передается в качестве второго аргумента. Функция должна вернуть массив с двумя числами: skidding, distance. Для получения дополнительной информации обратитесь к документации смещения Popper.
placement string, function 'top' Как расположить поповер: авто, сверху, снизу, слева, справа. Когда указано auto, всплывающее окно будет динамически переориентироваться. Когда функция используется для определения размещения, она вызывается с узлом DOM всплывающего окна в качестве первого аргумента и узлом DOM триггерного элемента в качестве второго. Контекст this установлен на экземпляр всплывающего окна.
popperConfig null, object, function null Чтобы изменить конфигурацию Popper по умолчанию в Bootstrap, смотрите Конфигурация Popper. Когда функция используется для создания конфигурации Popper, она вызывается с объектом, который содержит конфигурацию Bootstrap по умолчанию Popper. Это поможет вам использовать и объединить настройки по умолчанию с вашей собственной конфигурацией. Функция должна возвращать объект конфигурации для Popper.
sanitize boolean true Включите или отключите очистку. Если активированы параметры 'template', 'content' и 'title', они будут очищены.
sanitizeFn null, function null Здесь вы можете указать свою собственную функцию sanitize. Это может быть полезно, если вы предпочитаете использовать выделенную библиотеку для выполнения санитарной обработки.
selector string, false false Если предоставлен селектор, объекты всплывающих окон будут делегированы указанным целям. На практике это также используется для применения всплывающих окон к динамически добавляемым элементам DOM (поддержка jQuery.on). Смотрите эту проблему и информативный пример. Примечание: Атрибут title нельзя использовать в качестве селектора.
template string '<div class="popover" role="popover"><div class="popover-arrow"></div><div class="popover-inner"></div></div>' Базовый HTML для использования при создании всплывающего окна. title всплывающего окна будет внедрен в .popover-inner. .popover-arrow станет стрелкой всплывающего окна. Самый внешний элемент-оболочка должен иметь класс .popover и role="popover".
title string, element, function '' Заголовок всплывающего окна. Если задана функция, она будет вызываться со ссылкой this, установленной на элемент, к которому прикреплено всплывающее окно.
trigger string 'hover focus' Как срабатывает всплывающее окно: клик, наведение, фокус, вручную. Вы можете передать несколько триггеров; разделяйте их пробелом. 'manual' указывает, что всплывающее окно будет вызываться программно с помощью методов .popover('show'), .popover('hide') и .popover('toggle'); это значение нельзя комбинировать ни с каким другим триггером. 'hover' сам по себе приведет к всплывающим окнам, которые нельзя вызвать с помощью клавиатуры, и их следует использовать только в том случае, если существуют альтернативные методы передачи той же информации для пользователей клавиатуры.

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

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

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

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

Методы

Все методы API являются асинхронными и запускают переход. Они возвращаются вызывающей стороне сразу после начала перехода, но до его завершения. Кроме того, вызов метода переходного компонента будет игнорироваться. Подробнее читайте в нашей документации по JavaScript.
Метод Описание
disable Удаляет возможность отображения всплывающего окна элемента. Всплывающее окно будет отображаться только в том случае, если оно будет повторно включено.
dispose Скрывает и уничтожает всплывающее окно элемента (удаляет сохраненные данные в элементе DOM). Всплывающие окна, использующие делегирование (которые создаются с помощью опции selector) не могут быть уничтожены по отдельности в элементах-триггерах-потомках.
enable Позволяет отображать всплывающее окно элемента. Поповеры включены по умолчанию.
getInstance Статический метод, который позволяет вам получить экземпляр всплывающего окна, связанный с элементом DOM.
getOrCreateInstance Статический метод, который позволяет вам получить экземпляр всплывающего окна, связанный с элементом DOMили создать новый, если он не был инициализирован.
hide Скрывает всплывающее окно элемента. Возвращается к вызывающей стороне до того, как всплывающее окно будет фактически скрыто (т.е. до того, как произойдет событие hidden.bs.popover). Это считается “ручным” запуском всплывающего окна.
setContent Дает возможность изменить содержимое всплывающего окна после его инициализации.
show Отображает всплывающее окно элемента. Возврат к вызывающей стороне до того, как всплывающее окно действительно будет показано (т.е. до того, как произойдет событие shown.bs.popover). Это считается “ручным” запуском всплывающего окна. Всплывающие окна, заголовок и содержимое которых имеют нулевую длину, никогда не отображаются.
toggle Переключает всплывающее окно элемента. Возврат к вызывающей стороне до того, как всплывающее окно будет действительно показано или скрыто (т.е. до того, как произойдет событие shown.bs.popover или hidden.bs.popover). Это считается “ручным” запуском всплывающего окна.
toggleEnabled Переключает возможность отображения или скрытия всплывающего окна элемента.
update Обновляет позицию всплывающего окна элемента.
// getOrCreateInstance example
const popover = bootstrap.Popover.getOrCreateInstance('#example') // Возвращает экземпляр всплывающего окна Bootstrap

// setContent example
popover.setContent({
  '.popover-header': 'another title',
  '.popover-body': 'another content'
})
Метод setContent принимает аргумент object, где каждый ключ свойства является допустимым селектором string в шаблоне всплывающего окна, а каждое связанное значение свойства может быть string | element | function | null.

События

Событие Описание
hide.bs.popover Это событие запускается сразу после вызова метода экземпляра hide.
hidden.bs.popover Это событие запускается, когда всплывающее окно перестает быть скрытым от пользователя (будет ждать завершения переходов CSS).
inserted.bs.popover Это событие запускается после события show.bs.popover, когда шаблон всплывающего окна был добавлен в DOM.
show.bs.popover Это событие срабатывает сразу же, когда вызывается метод экземпляра show.
shown.bs.popover Это событие запускается, когда всплывающее окно становится видимым для пользователя (будет ждать завершения переходов CSS).
const myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', () => {
  // сделайте что-нибудь...
})