Поповери
Документація та приклади додавання спливаючих вікон 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.
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 |
Додає спливаюче вікно до певного елемента. Приклад: |
content |
рядок | елемент | функція | '' |
Значення вмісту за умовчанням, якщо Якщо задано функцію, її буде викликано з |
delay |
номер | об'єкт | 0 |
Затримка показу та приховування спливаючого вікна (мс) - не стосується типу ручного запуску Якщо вказано число, затримка застосовується як для приховування, так і для показу Структура об'єкта: |
html |
логічний | false |
Вставте HTML у спливаюче вікно. Якщо значення false, innerText властивість використовуватиметься для вставки вмісту в DOM. Використовуйте текст, якщо вас турбують атаки XSS. |
placement |
рядок | функція | 'right' |
Як розташувати поповер - авто | верх | нижня | ліворуч | правильно. Коли функція використовується для визначення розміщення, вона викликається зі спливаючим вузлом DOM як першим аргументом і ініціюючим елементом DOM вузлом як другим. Контекст |
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 Popover's
Зовнішній елемент оболонки повинен мати |
title |
рядок | елемент | функція | '' |
Значення назви за умовчанням, якщо Якщо задано функцію, її буде викликано з |
trigger |
рядок | 'click' |
Як спрацьовує спливаюче вікно - натисніть | навести | фокус | посібник. Ви можете передати кілька тригерів; розділіть їх пробілом. manual не можна поєднувати з будь-яким іншим тригером. |
fallbackPlacements |
масив | ['top', 'right', 'bottom', 'left'] |
Визначте резервні місця розташування, надавши список місць розташування в масиві (у порядку переваги). Для отримання додаткової інформації зверніться до документів про поведінку Поппера |
boundary |
рядок | елемент | 'clippingParents' |
Межа обмеження переповнення спливного вікна (застосовується лише до модифікатора preventOverflow Попера). За замовчуванням він 'clippingParents' приймає посилання HTMLElement (тільки через JavaScript). Для отримання додаткової інформації зверніться до документів Popper's detectOverflow . |
customClass |
рядок | функція | '' |
Додайте класи до спливаючого вікна, коли воно відображається. Зауважте, що ці класи буде додано на додаток до будь-яких класів, указаних у шаблоні. Щоб додати кілька класів, розділіть їх пробілами: Ви також можете передати функцію, яка повинна повертати один рядок, що містить імена додаткових класів. |
sanitize |
логічний | true |
Увімкніть або вимкніть санітарну обробку. Якщо активовано 'template' , 'content' і 'title' параметри будуть очищені. Перегляньте розділ про дезінфікуючий засіб у нашій документації JavaScript . |
allowList |
об'єкт | Значення за замовчуванням | Об'єкт, який містить дозволені атрибути та теги |
sanitizeFn |
нуль | функція | null |
Тут ви можете встановити власну функцію дезінфекції. Це може бути корисним, якщо ви віддаєте перевагу використанню спеціальної бібліотеки для виконання санітарної обробки. |
offset |
масив | рядок | функція | [0, 8] |
Зміщення спливного вікна відносно його цілі. Ви можете передати рядок в атрибутах даних зі значеннями, розділеними комами, наприклад: Коли функція використовується для визначення зміщення, вона викликається з об’єктом, що містить розміщення поппера, посилання та прямокутники поппера як перший аргумент. Вузол DOM тригерного елемента передається як другий аргумент. Функція має повертати масив із двома числами: . Для отримання додаткової інформації зверніться до офсетної документації Поппера . |
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...
})