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

Информеры

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

На этой странице

Обзор

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

  • Поповеры полагаются на стороннюю библиотеку 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'
})

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

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

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

.custom-popover {
  --bs-popover-max-width: 200px;
  --bs-popover-border-color: var(--bs-primary);
  --bs-popover-header-bg: var(--bs-primary);
  --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"
        title="Пользовательское всплывающее окно"
        data-bs-content="Это всплывающее окно оформлено с помощью переменных CSS.">
  Пользовательское всплывающее окно
</button>

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

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

Обязательная специальная разметка для dismiss-on-next-click

Для правильного кроссбраузерного и кроссплатформенного поведения вы должны использовать тег <a>, не тег <button>, а также вы должны включить tabindex.

Отклоняемое всплывающее окно
html 
<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" 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:                        $white;
$popover-max-width:                 276px;
$popover-border-width:              $border-width;
$popover-border-color:              var(--#{$prefix}border-color-translucent);
$popover-border-radius:             $border-radius-lg;
$popover-inner-border-radius:       subtract($popover-border-radius, $popover-border-width);
$popover-box-shadow:                $box-shadow;

$popover-header-font-size:          $font-size-base;
$popover-header-bg:                 shade-color($popover-bg, 6%);
$popover-header-color:              var(--#{$prefix}heading-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;

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

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

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

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

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

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

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

Опции

Поскольку параметры можно передавать через атрибуты данных или 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}'.

Обратите внимание, что по соображениям безопасности параметры 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 '' Значение содержимого по умолчанию, если атрибут data-bs-content отсутствует. Если задана функция, она будет вызываться со ссылкой 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). Смотрите эту проблему и информативный пример.
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 '' Значение заголовка по умолчанию, если атрибут title отсутствует. Если задана функция, она будет вызываться со ссылкой 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
myPopover.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', () => {
  // сделайте что-нибудь...
})