Підказки
Документація та приклади додавання спеціальних підказок Bootstrap із CSS і JavaScript із використанням CSS3 для анімації та атрибутів даних для локального зберігання заголовків.
Огляд
Що потрібно знати під час використання плагіна підказок:
- Підказки покладаються на сторонню бібліотеку Popper для позиціонування. Ви повинні включити popper.min.js перед bootstrap.js або використовувати
bootstrap.bundle.min.js
/bootstrap.bundle.js
, який містить Popper, щоб підказки працювали! - Якщо ви створюєте наш JavaScript із вихідного коду, для цього потрібно
util.js
. - Спливаючі підказки є доступними з міркувань продуктивності, тому ви повинні ініціалізувати їх самостійно .
- Підказки з заголовками нульової довжини ніколи не відображаються.
- Укажіть
container: 'body'
, щоб уникнути проблем із відтворенням у більш складних компонентах (як-от наші групи вводу, групи кнопок тощо). - Запуск підказок для прихованих елементів не працюватиме.
- Спливаючі підказки для елементів
.disabled
абоdisabled
мають бути викликані на елементі-обгортці. - Під час запуску з гіперпосилань, які охоплюють кілька рядків, підказки будуть відцентровані. Використовуйте
white-space: nowrap;
на вашому<a>
s, щоб уникнути такої поведінки. - Спливаючі підказки мають бути приховані до того, як їхні відповідні елементи будуть видалені з DOM.
- Підказки можна викликати завдяки елементу всередині тіньової DOM.
prefers-reduced-motion
медіа-запиту. Перегляньте розділ про
обмежений рух нашої документації щодо спеціальних можливостей .
Зрозуміли все це? Чудово, давайте подивимося, як вони працюють, на прикладах.
Приклад: увімкніть спливаючі підказки всюди
Одним із способів ініціалізації всіх підказок на сторінці є вибір їх за data-toggle
атрибутом:
$(function () {
$('[data-toggle="tooltip"]').tooltip()
})
Приклади
Наведіть курсор на посилання нижче, щоб переглянути підказки:
Текст-заповнювач для демонстрації деяких вбудованих посилань із підказками. Тепер це просто наповнювач, а не вбивця. Вміст, розміщений тут лише для імітації присутності справжнього тексту . І все це лише для того, щоб дати вам уявлення про те, як виглядатимуть підказки під час використання в реальних ситуаціях. Тож, сподіваємося, тепер ви побачили, як ці підказки для посилань можуть працювати на практиці, коли ви використовуєте їх на власному сайті чи проекті.
Наведіть курсор на кнопки нижче, щоб побачити чотири напрямки підказок: зверху, справа, знизу та зліва.
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="top" title="Tooltip on top">
Tooltip on top
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="right" title="Tooltip on right">
Tooltip on right
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="bottom" title="Tooltip on bottom">
Tooltip on bottom
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="left" title="Tooltip on left">
Tooltip on left
</button>
І з додаванням спеціального HTML:
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-html="true" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
Tooltip with HTML
</button>
Використання
Плагін підказки створює вміст і розмітку за запитом і за замовчуванням розміщує підказки після елемента запуску.
Запустити підказку через JavaScript:
$('#example').tooltip(options)
Перелив auto
іscroll
Положення спливаючої підказки намагається автоматично змінитися, якщо батьківський контейнер має overflow: auto
або overflow: scroll
подібно до нашого .table-responsive
, але все ще зберігає початкове розташування розташування. Щоб вирішити проблему, установіть для boundary
параметра значення, відмінне від значення за замовчуванням 'scrollParent'
, наприклад 'window'
:
$('#example').tooltip({ boundary: 'window' })
Розмітка
Необхідна розмітка для спливаючої підказки – це лише data
атрибут, а title
в елементі HTML, який ви хочете мати спливаючу підказку. Згенерована розмітка спливаючої підказки досить проста, хоча для неї потрібна позиція (за замовчуванням встановлена top
плагіном).
Зробіть підказки функціональними для користувачів клавіатури та допоміжних технологій
Підказки слід додавати лише до елементів HTML, які традиційно доступні для фокусування з клавіатури та інтерактивні (наприклад, посилання чи елементи керування формою). Хоча довільні HTML-елементи (такі як <span>
s) можна зробити фокусними, додавши tabindex="0"
атрибут, це додасть потенційно дратівливі та заплутані позиції табуляції на неінтерактивних елементах для користувачів клавіатури, і більшість допоміжних технологій наразі не оголошують спливаючу підказку в цій ситуації. Крім того, не покладайтеся лише на hover
тригер для вашої підказки, оскільки це зробить ваші підказки неможливими для запуску для користувачів клавіатури.
<!-- HTML to write -->
<a href="#" data-toggle="tooltip" title="Some tooltip text!">Hover over me</a>
<!-- Generated markup by the plugin -->
<div class="tooltip bs-tooltip-top" role="tooltip">
<div class="arrow"></div>
<div class="tooltip-inner">
Some tooltip text!
</div>
</div>
Відключені елементи
Елементи з disabled
атрибутом не є інтерактивними, тобто користувачі не можуть фокусуватися, наводити курсор або клацати на них, щоб викликати спливаючу підказку (або спливаюче вікно). Як обхідний шлях, ви захочете запустити спливаючу підказку з обгортки <div>
або <span>
, в ідеалі з можливістю фокусування клавіатури за допомогою tabindex="0"
, і замінити pointer-events
на вимкненому елементі.
<span class="d-inline-block" tabindex="0" data-toggle="tooltip" title="Disabled tooltip">
<button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button>
</span>
Опції
Параметри можна передати через атрибути даних або JavaScript. Для атрибутів даних додайте назву опції до data-
, як у data-animation=""
.
sanitize
,
sanitizeFn
і
whiteList
не можна надавати за допомогою атрибутів даних.
Ім'я | Тип | За замовчуванням | опис |
---|---|---|---|
анімація | логічний | правда | Застосуйте згасання CSS до підказки |
контейнер | рядок | елемент | помилковий | помилковий | Додає підказку до певного елемента. Приклад: |
затримка | номер | об'єкт | 0 | Затримка показу та приховування спливаючої підказки (мс) - не стосується типу ручного запуску Якщо вказано число, затримка застосовується як для приховування, так і для показу Структура об'єкта: |
html | логічний | помилковий | Дозволити HTML у спливаючій підказці. Якщо встановлено значення true, теги HTML у спливаючій підказці Використовуйте текст, якщо вас турбують атаки XSS. |
розміщення | рядок | функція | "топ" | Як розташувати спливаючу підказку - авто | верх | нижня | ліворуч | правильно. Коли функція використовується для визначення розміщення, вона викликається з вузлом DOM спливаючої підказки як першим аргументом і вузлом DOM елемента запуску як другим. Контекст |
селектор | рядок | помилковий | помилковий | Якщо надано селектор, об’єкти підказки будуть делеговані вказаним цілям. На практиці це також використовується для застосування підказок до динамічно доданих елементів DOM ( jQuery.on підтримка). Перегляньте це та інформативний приклад . |
шаблон | рядок | '<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>' |
Базовий HTML для створення підказки. Підказку
Зовнішній елемент оболонки повинен мати |
назва | рядок | елемент | функція | '' | Значення назви за умовчанням, якщо Якщо задано функцію, її буде викликано з |
тригер | рядок | 'hover focus' | Як спрацьовує підказка - клацніть | навести | фокус | посібник. Ви можете передати кілька тригерів; розділіть їх пробілом.
|
зсув | номер | рядок | функція | 0 | Зміщення спливаючої підказки відносно її цілі. Коли функція використовується для визначення зсуву, вона викликається з об’єктом, що містить дані зсуву як перший аргумент. Функція повинна повертати об’єкт з такою ж структурою. Вузол DOM тригерного елемента передається як другий аргумент. Для отримання додаткової інформації зверніться до офсетної документації Поппера . |
резервне розміщення | рядок | масив | 'фліп' | Дозволяє вказати, яку позицію використовуватиме Поппер у резервному режимі. Для отримання додаткової інформації зверніться до документів про поведінку Поппера |
customClass | рядок | функція | '' | Додайте класи до спливаючої підказки, коли вона відображається. Зауважте, що ці класи буде додано на додаток до будь-яких класів, указаних у шаблоні. Щоб додати кілька класів, розділіть їх пробілами: Ви також можете передати функцію, яка повинна повертати один рядок, що містить імена додаткових класів. |
межа | рядок | елемент | 'scrollParent' | Межа обмеження переповнення підказки. Приймає значення 'viewport' , 'window' , 'scrollParent' або посилання HTMLElement (тільки для JavaScript). Для отримання додаткової інформації зверніться до документів PreventOverflow Поппера . |
продезінфікувати | логічний | правда | Увімкніть або вимкніть санітарну обробку. Якщо активовано 'template' , 'title' параметри будуть очищені. Перегляньте розділ про дезінфікуючий засіб у нашій документації JavaScript . |
whiteList | об'єкт | Значення за замовчуванням | Об'єкт, який містить дозволені атрибути та теги |
очиститиFn | нуль | функція | нуль | Тут ви можете встановити власну функцію дезінфекції. Це може бути корисним, якщо ви віддаєте перевагу використанню спеціальної бібліотеки для виконання санітарної обробки. |
popperConfig | нуль | об'єкт | нуль | Щоб змінити конфігурацію Bootstrap за замовчуванням Popper, перегляньте конфігурацію Popper |
Атрибути даних для окремих підказок
Параметри для окремих підказок можна альтернативно вказати за допомогою використання атрибутів даних, як пояснено вище.
методи
Асинхронні методи та переходи
Усі методи API є асинхронними та починають перехід . Вони повертаються до абонента, щойно перехід починається, але до його завершення . Крім того, виклик методу компонента, що переходить, ігноруватиметься .
Дивіться нашу документацію JavaScript для отримання додаткової інформації .
$().tooltip(options)
Додає обробник спливаючої підказки до колекції елементів.
.tooltip('show')
Показує спливаючу підказку елемента. Повертається до абонента, перш ніж спливаюча підказка була фактично показана (тобто до shown.bs.tooltip
події). Це вважається «ручним» запуском підказки. Підказки з заголовками нульової довжини ніколи не відображаються.
$('#element').tooltip('show')
.tooltip('hide')
Приховує спливаючу підказку елемента. Повертається до абонента, перш ніж спливаюча підказка була фактично прихована (тобто до того , як відбудеться hidden.bs.tooltip
подія). Це вважається «ручним» запуском підказки.
$('#element').tooltip('hide')
.tooltip('toggle')
Перемикає спливаючу підказку елемента. Повертається до абонента до того, як спливаюча підказка була фактично показана або прихована (тобто до події shown.bs.tooltip
або ). hidden.bs.tooltip
Це вважається «ручним» запуском підказки.
$('#element').tooltip('toggle')
.tooltip('dispose')
Приховує та знищує підказку елемента. Підказки, які використовують делегування (які створюються за допомогою параметра selector
) , не можуть бути окремо знищені на нащадкових елементах тригера.
$('#element').tooltip('dispose')
.tooltip('enable')
Надає можливість показу спливаючої підказки елемента. Підказки ввімкнено за умовчанням.
$('#element').tooltip('enable')
.tooltip('disable')
Усуває можливість показу спливаючої підказки елемента. Спливаючу підказку можна буде показати, лише якщо її повторно ввімкнути.
$('#element').tooltip('disable')
.tooltip('toggleEnabled')
Перемикає можливість показувати або приховувати підказку елемента.
$('#element').tooltip('toggleEnabled')
.tooltip('update')
Оновлює положення спливаючої підказки елемента.
$('#element').tooltip('update')
Події
Тип події | опис |
---|---|
show.bs.tooltip | Ця подія запускається негайно, коли show викликається метод екземпляра. |
показано.bs.tooltip | Ця подія запускається, коли спливаюча підказка стає видимою для користувача (буде очікувати завершення переходів CSS). |
hide.bs.tooltip | Ця подія запускається негайно після hide виклику методу екземпляра. |
hidden.bs.tooltip | Ця подія запускається, коли спливаюча підказка перестає бути прихованою від користувача (чекатиме, поки завершаться переходи CSS). |
inserted.bs.tooltip | Ця подія запускається після show.bs.tooltip події, коли шаблон підказки було додано до DOM. |
$('#myTooltip').on('hidden.bs.tooltip', function () {
// do something...
})