Перейти до основного вмісту Перейти до навігації документами
in English

Поповери

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

Огляд

Що потрібно знати під час використання плагіна Popover:

  • Popovers покладаються на сторонню бібліотеку Popper для позиціонування. Ви повинні включити popper.min.js перед bootstrap.js або використовувати bootstrap.bundle.min.js/ bootstrap.bundle.js, який містить Popper, щоб поповери працювали!
  • Поповерам потрібен плагін підказки як залежність.
  • Поповерси можна використовувати з міркувань продуктивності, тому ви повинні ініціалізувати їх самостійно .
  • Нульова довжина titleта contentзначення ніколи не показуватимуть спливаюче зображення.
  • Укажіть container: 'body', щоб уникнути проблем із відтворенням у більш складних компонентах (як-от наші групи вводу, групи кнопок тощо).
  • Запуск спливаючих вікон на прихованих елементах не працюватиме.
  • Поповер для елементів .disabledабо має запускатися на елементі-оболонці.disabled
  • Коли запускаються з прив’язок, які перетинають кілька ліній, спливаючі елементи будуть зосереджені між загальною шириною прив’язок. Використовуйте .text-nowrapна вашому <a>s, щоб уникнути такої поведінки.
  • Поповери мають бути приховані до того, як їхні відповідні елементи будуть видалені з 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="Popover title" data-bs-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>

Чотири напрямки

Доступні чотири варіанти: вирівнювання вгорі, праворуч, внизу та ліворуч. Напрямки віддзеркалюються під час використання Bootstrap у RTL.

<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-content="Top popover">
  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="Right popover">
  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="Bottom popover">
  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="Left popover">
  Popover on left
</button>

Відхилити після наступного натискання

Використовуйте focusтригер, щоб закрити спливаючі вікна під час наступного натискання користувачем іншого елемента, ніж елемент перемикання.

Спеціальна розмітка потрібна для відхилення при наступному клацанні

Для належної поведінки між браузерами та платформами ви повинні використовувати <a>тег, а не<button> тег, і ви також повинні включити 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>, в ідеалі, з можливістю фокусування клавіатури за допомогою tabindex="0".

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

<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>Disabled button</button>
</span>

Сасс

Змінні

$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>s) можна зробити доступними для фокусування, додавши tabindex="0"атрибут, це додасть потенційно дратівливі та заплутані позиції табуляції на неінтерактивних елементах для користувачів клавіатури, і більшість допоміжних технологій наразі не повідомляють вміст спливаючого вікна в цій ситуації . Крім того, не покладайтеся лише на hoverтригер для ваших спливаючих повернень, оскільки це унеможливить їх ініціювання для користувачів клавіатури.

Хоча ви можете вставляти насичений, структурований HTML у спливаючих вікнах за допомогою цієї htmlопції, ми настійно рекомендуємо вам уникати додавання надмірної кількості вмісту. Те, як спливаючі елементи зараз працюють, полягає в тому, що після відображення їхній вміст прив’язується до тригерного елемента за допомогою aria-describedbyатрибута. У результаті весь вміст popover буде оголошено користувачам допоміжних технологій як один довгий безперервний потік.

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

Опції

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

Зауважте, що з міркувань безпеки параметри sanitize, sanitizeFn, і allowListне можуть бути надані за допомогою атрибутів даних.
Ім'я Тип За замовчуванням опис
animation логічний true Застосуйте CSS-зникнення переходу до спливаючого вікна
container рядок | елемент | помилковий false

Додає спливаюче вікно до певного елемента. Приклад: container: 'body'. Цей параметр особливо корисний тим, що він дозволяє розташувати спливне вікно в потоці документа поблизу елемента запуску, що запобігатиме відпливу спливного вікна від елемента запуску під час зміни розміру вікна.

content рядок | елемент | функція ''

Значення вмісту за умовчанням, якщо data-bs-contentатрибут відсутній.

Якщо задано функцію, її буде викликано з thisпосиланням на елемент, до якого приєднано спливаюче зображення.

delay номер | об'єкт 0

Затримка показу та приховування спливаючого вікна (мс) - не стосується типу ручного запуску

Якщо вказано число, затримка застосовується як для приховування, так і для показу

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

html логічний false Вставте HTML у спливаюче вікно. Якщо значення false, innerTextвластивість використовуватиметься для вставки вмісту в DOM. Використовуйте текст, якщо вас турбують атаки XSS.
placement рядок | функція 'right'

Як розташувати поповер - авто | верх | нижня | ліворуч | правильно.
Якщо autoвказано, він динамічно переорієнтує спливне вікно.

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

selector рядок | помилковий false Якщо надано селектор, спливаючі об’єкти будуть делеговані вказаним цілям. На практиці це використовується, щоб увімкнути додавання спливаючих зображень до динамічного вмісту HTML. Перегляньте це та інформативний приклад .
template рядок '<div class="popover" role="tooltip"><div class="popover-arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'

Базовий HTML для створення спливаючого вікна.

Popover's titleбуде введено в .popover-header.

Popover's contentбуде введено в .popover-body.

.popover-arrowстане стрілкою поповера.

Зовнішній елемент оболонки повинен мати .popoverклас.

title рядок | елемент | функція ''

Значення назви за умовчанням, якщо titleатрибут відсутній.

Якщо задано функцію, її буде викликано з thisпосиланням на елемент, до якого приєднано спливаюче зображення.

trigger рядок 'click' Як спрацьовує спливаюче вікно - натисніть | навести | фокус | посібник. Ви можете передати кілька тригерів; розділіть їх пробілом. manualне можна поєднувати з будь-яким іншим тригером.
fallbackPlacements масив ['top', 'right', 'bottom', 'left'] Визначте резервні місця розташування, надавши список місць розташування в масиві (у порядку переваги). Для отримання додаткової інформації зверніться до документів про поведінку Поппера
boundary рядок | елемент 'clippingParents' Межа обмеження переповнення спливного вікна (застосовується лише до модифікатора preventOverflow Попера). За замовчуванням він 'clippingParents'приймає посилання HTMLElement (тільки через JavaScript). Для отримання додаткової інформації зверніться до документів Popper's detectOverflow .
customClass рядок | функція ''

Додайте класи до спливаючого вікна, коли воно відображається. Зауважте, що ці класи буде додано на додаток до будь-яких класів, указаних у шаблоні. Щоб додати кілька класів, розділіть їх пробілами: 'class-1 class-2'.

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

sanitize логічний true Увімкніть або вимкніть санітарну обробку. Якщо активовано 'template', 'content'і 'title'параметри будуть очищені. Перегляньте розділ про дезінфікуючий засіб у нашій документації JavaScript .
allowList об'єкт Значення за замовчуванням Об'єкт, який містить дозволені атрибути та теги
sanitizeFn нуль | функція null Тут ви можете встановити власну функцію дезінфекції. Це може бути корисним, якщо ви віддаєте перевагу використанню спеціальної бібліотеки для виконання санітарної обробки.
offset масив | рядок | функція [0, 8]

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

Коли функція використовується для визначення зміщення, вона викликається з об’єктом, що містить розміщення поппера, посилання та прямокутники поппера як перший аргумент. Вузол DOM тригерного елемента передається як другий аргумент. Функція має повертати масив із двома числами: .[skidding, distance]

Для отримання додаткової інформації зверніться до офсетної документації Поппера .

popperConfig нуль | об'єкт | функція 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 для отримання додаткової інформації .

шоу

Виявляє спливаюче зображення елемента. Повертається до абонента до того, як спливаюче повідомлення буде фактично показано (тобто до того , як відбудеться shown.bs.popoverподія). Це вважається «ручним» запуском спливаючого повідомлення. Поповер, заголовок і вміст яких мають нульову довжину, ніколи не відображаються.

myPopover.show()

приховати

Приховує спливаюче вікно елемента. Повертається до абонента, перш ніж спливаюче повідомлення було фактично приховано (тобто до того , як відбудеться hidden.bs.popoverподія). Це вважається «ручним» запуском спливаючого повідомлення.

myPopover.hide()

перемикач

Перемикає спливаюче вікно елемента. Повертається до абонента до того, як спливаюче повідомлення було фактично показано або приховано (тобто до того, як відбудеться подія shown.bs.popoverабо ). hidden.bs.popoverЦе вважається «ручним» запуском спливаючого повідомлення.

myPopover.toggle()

розпоряджатися

Приховує та знищує спливаюче вікно елемента (видаляє збережені дані в елементі DOM). Поповери, які використовують делегування (які створюються за допомогою параметра selector) , не можуть бути окремо знищені на нащадкових тригерних елементах.

myPopover.dispose()

включити

Надає можливість показу спливаючого вікна елемента. Поповери ввімкнено за умовчанням.

myPopover.enable()

відключити

Усуває можливість показу спливаючого вікна елемента. Спливаюче вікно можна буде показати, лише якщо його повторно ввімкнути.

myPopover.disable()

toggleEnabled

Перемикає можливість показувати або приховувати спливаюче вікно елемента.

myPopover.toggleEnabled()

оновлення

Оновлює позицію спливного вікна елемента.

myPopover.update()

getInstance

Статичний метод, який дозволяє отримати екземпляр спливаючого зображення, пов’язаний з елементом DOM

var exampleTriggerEl = document.getElementById('example')
var popover = bootstrap.Popover.getInstance(exampleTriggerEl) // Returns a Bootstrap popover instance

getOrCreateInstance

Статичний метод, який дозволяє отримати екземпляр спливаючого повідомлення, пов’язаний з елементом DOM, або створити новий, якщо він не був ініціалізований

var exampleTriggerEl = document.getElementById('example')
var popover = bootstrap.Popover.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap popover instance

Події

Тип події опис
show.bs.popover Ця подія запускається негайно, коли showвикликається метод екземпляра.
показано.bs.popover Ця подія запускається, коли спливаюче вікно стає видимим для користувача (чекатиме, поки завершаться переходи CSS).
hide.bs.popover Ця подія запускається негайно після hideвиклику методу екземпляра.
hidden.bs.popover Ця подія запускається, коли спливаюче вікно перестає бути прихованим від користувача (чекатиме, поки завершаться переходи CSS).
вставлений.bs.popover Ця подія запускається після show.bs.popoverподії, коли шаблон спливаючого зображення було додано до DOM.
var myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', function () {
  // do something...
})