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

Подсказки

Документация и примеры добавления настраиваемых всплывающих подсказок Bootstrap с CSS и JavaScript, используя CSS3 для анимации, и атрибуты данных для локального хранения заголовков.

Обзор

Вот что надо знать перед началом работы с плагином подсказок:

  • Плагин использует стороннюю библиотеку Popper.js для позиционирования. Чтобы всплывающие подсказки работали Вы должны подключать popper.min.js перед bootstrap.js или использовать bootstrap.bundle.min.js / bootstrap.bundle.js – содержащие Popper.js!
  • Подсказки не инициализируются и не используются по умолчанию по причинам производительности, так что вам надо сделать это самому.
  • Подсказки с названием нулевой длины никогда не отображаются.
  • Задайте container: 'body' чтобы избежать проблем с отрисовкой более сложных компонентов (таких как группы ввода, кнопок и т.д.).
  • Нельзя запускать подсказки из скрытых элементов.
  • Подсказки для элементов класса .disabled или с атрибутом disabled должны запускаться из элемента-«обертки».
  • Когда подсказка запускается из многострочных ссылок, подсказки будут центрированы. Используйте white-space: nowrap; в ваших <a>, чтобы избежать этого.
  • Подсказки должны быть спрятаны до того, как связанные с ними элементы удалены из DOM.
  • Всплывающие подсказки могут запускаться благодаря элементу внутри теневой модели DOM.

По умолчанию этот компонент использует встроенное средство очистки содержимого, которое удаляет все элементы HTML, которые не разрешены явно. Дополнительные сведения смотрите в разделе очистки в нашей документации по JavaScript.

Эффект анимации этого компонента зависит от медиазапроса prefers-reduced-motion. Смотрите раздел по ограничении анимации в нашей документации.

Вы всё поняли? Отлично, посмотрим, как это работает на конкретных примерах.

Пример: задействуйте подсказки везде

Один из способов инициализировать все подсказки на странице – обратиться к ним по атрибуту data-bs-toggle:

var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
  return new bootstrap.Tooltip(tooltipTriggerEl)
})

Примеры

Наведите курсор на ссылки – увидите подсказку:

Tight pants next level keffiyeh you probably haven't heard of them. Photo booth beard raw denim letterpress vegan messenger bag stumptown. Farm-to-table seitan, mcsweeney's fixie sustainable quinoa 8-bit american apparel have a terry richardson vinyl chambray. Beard stumptown, cardigans banh mi lomo thundercats. Tofu biodiesel williamsburg marfa, four loko mcsweeney's cleanse vegan chambray. A really ironic artisan whatever keytar, scenester farm-to-table banksy Austin twitter handle freegan cred raw denim single-origin coffee viral.

Наведите курсор на кнопки, чтобы увидеть четыре разные расположения подсказок: сверху, справа, внизу и влево.

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" title="Подсказка вверху">
  Подсказка вверху
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" title="Подсказка справа">
  Подсказка справа
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Подсказка внизу">
  Подсказка внизу
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="left" title="Подсказка слева">
  Подсказка слева
</button>

И с добавлением обычного HTML:

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-html="true" title="<em>Подсказка</em> <u>с</u> <b>HTML</b>">
  Всплывающая подсказка с HTML
</button>

С SVG:

Sass

Переменные

$tooltip-font-size:                 $font-size-sm;
$tooltip-max-width:                 200px;
$tooltip-color:                     $white;
$tooltip-bg:                        $black;
$tooltip-border-radius:             $border-radius;
$tooltip-opacity:                   .9;
$tooltip-padding-y:                 $spacer / 4;
$tooltip-padding-x:                 $spacer / 2;
$tooltip-margin:                    0;

$tooltip-arrow-width:               .8rem;
$tooltip-arrow-height:              .4rem;
$tooltip-arrow-color:               $tooltip-bg;

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

Плагин подсказок создает содержимое и разметку по требованию, и по умолчанию размещает подсказки после их элемента-триггера.

Запустите подсказку через JavaScript:

var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)
Переполнение Overflow auto и scroll

Положение всплывающей подсказки пытается автоматически измениться, если у родительского контейнера переполнение overflow: auto или overflow: scroll как наш .table-responsive, но при этом сохранит исходное положение размещения. Для решения проблемы, установите для параметра boundary любое значение, отличное от значения по умолчанию 'scrollParent', например 'window':

var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, {
  boundary: 'window'
})

Разметка

Для использования подсказок требуется лишь атрибут data и title в том элементе HTML, который вы хотите оснастить подсказкой. Генерированная разметка подсказки – проще, хотя и требует установить позицию (по умолчанию позиция задается плагином как top).

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

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

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

<!-- HTML для записи -->
<a href="#" data-bs-toggle="tooltip" title="Текст всплывающей подсказки!">Наведите на меня</a>

<!-- Разметка, созданная плагином -->
<div class="tooltip bs-tooltip-top" role="tooltip">
  <div class="tooltip-arrow"></div>
  <div class="tooltip-inner">
    Текст всплывающей подсказки!
  </div>
</div>

Дезактивированные элементы

Элементы с атрибутом disabled не есть интерактивные, что означает, что подсказка (или поповер) не возникнут при фокусировании, наведении или клике на них юзеров. Как полумера в решении этого вопроса – можно запустить подсказки из оборачивающего элемента <div> или <span>, в идеале придав им возможность фокусировки с клавиатуры атрибутом tabindex="0", и т.о. преодолев событие pointer-events в дезактивированном элементе.

<span class="d-inline-block" tabindex="0" data-bs-toggle="tooltip" title="Отключенная подсказка">
  <button class="btn btn-primary" type="button" disabled>Отключенная кнопка</button>
</span>

Параметры

Параметры можно передавать через атрибуты или JavaScript. С атрибутами: добавьте название атрибута к data-bs-, как в data-bs-animation="".

Обратите внимание, что по соображениям безопасности параметры sanitize, sanitizeFn и whiteList не могут быть предоставлены с использованием атрибутов данных.

Наименование Тип По умолчанию Описание
animation boolean true Применить переход CSS fade к всплывающей подсказке
container string | element | false false

Добавляет всплывающую подсказку к определенному элементу. Пример: container: 'body'. Этот параметр особенно полезен тем, что позволяет Вам размещать всплывающую подсказку в потоке документа рядом с элементом запуска, что предотвратит отрыв всплывающей подсказки от элемента запуска во время изменения размера окна.

delay number | object 0

Задержка показа и скрытия всплывающей подсказки (мс) - не относится к ручному типу триггера

Если указан номер, задержка применяется как к скрытию, так и к отображению.

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

html boolean false

Разрешить HTML во всплывающей подсказке.

Если `true`, HTML-теги в title всплывающей подсказки будут отображаться во всплывающей подсказке. Если `false`, свойство innerText будет использоваться для вставки содержимого в DOM.

Используйте текст, если Вас беспокоят XSS-атаки.

placement string | function 'top'

Как разместить всплывающую подсказку - auto | top | bottom | left | right.
Если задано auto всплывающая подсказка будет динамически переориентирована.

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

selector string | false false Если предусмотрен селектор, объекты всплывающей подсказки будут делегированы указанным целям. На практике это также используется для применения всплывающих подсказок к динамически добавляемым элементам DOM (поддержка jQuery.on). Смотрите это и информативный пример.
template string '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'

Базовый HTML для использования при создании всплывающей подсказки.

title всплывающей подсказки будет вставлен в .tooltip-inner.

.tooltip-arrow станет стрелкой всплывающей подсказки.

Самый внешний элемент оболочки должен иметь класс .tooltip и role="tooltip".

title string | element | function ''

Значение заголовка по умолчанию, если атрибут title отсутствует.

Если задана функция, она будет вызываться со ссылкой this, установленной на элемент, к которому прикреплена всплывающая подсказка.

trigger string 'hover focus'

Как запускается всплывающая подсказка - click | hover | focus | manual. Вы можете передать несколько триггеров; разделить их пробелом.

'manual' указывает, что всплывающая подсказка будет запускаться программно через .tooltip('show'), .tooltip('hide') и методы .tooltip('toggle'); это значение нельзя комбинировать с другими триггерами.

Само по себе 'hover' приведет к появлению всплывающих подсказок, которые нельзя запускать с клавиатуры, и их следует использовать только при наличии альтернативных методов передачи той же информации пользователям клавиатуры.

fallbackPlacements array ['top', 'right', 'bottom', 'left'] Определите резервные места размещения, предоставив список мест размещения в массиве (в порядке предпочтения). Для получения дополнительной информации смотрите документацию о поведении Popper.
boundary string | element 'clippingParents' Граница ограничения переполнения всплывающей подсказки. По умолчанию это 'clippingParents' и может принимать ссылку HTMLElement (только JavaScript). Дополнительную информацию смотрите в Popper документации preventOverflow.
customClass string | function ''

Добавляйте классы во всплывающую подсказку, когда она отображается. Обратите внимание, что эти классы будут добавлены в дополнение к любым классам, указанным в шаблоне. Чтобы добавить несколько классов, разделите их пробелами: 'class-1 class-2'.

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

sanitize boolean true Включите или отключите дезинфекцию. Если активированы параметры 'template' и 'title' , будут очищены. Смотрите раздел очистки в нашей документации по JavaScript.
allowList object Значение по умолчанию Объект, содержащий разрешенные атрибуты и теги
sanitizeFn null | function null Здесь Вы можете предоставить свою собственную функцию дезинфекции. Это может быть полезно, если Вы предпочитаете использовать специальную библиотеку для выполнения очистки.
offset array | string | function [0, 0]

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

Когда функция используется для определения смещения, она вызывается с объектом, содержащим размещение popper, ссылку и popper rects в качестве первого аргумента. Узел DOM запускающего элемента передается в качестве второго аргумента. Функция должна возвращать массив с двумя числами: [skidding, distance].

Дополнительную информацию смотрите в offset документации Popper.

offset array | string | function [0, 0]

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

Когда функция используется для определения смещения, она вызывается с объектом, содержащим размещение popper, ссылку и popper rects в качестве первого аргумента. Узел DOM запускающего элемента передается в качестве второго аргумента. Функция должна возвращать массив с двумя числами: [skidding, distance].

Дополнительную информацию смотрите в offset документации Popper.

popperConfig null | object | function null

Чтобы изменить конфигурацию Popper по умолчанию для Bootstrap, смотрите конфигурацию Popper.

Когда функция используется для создания конфигурации Popper, она вызывается с объектом, который содержит конфигурацию Popper по умолчанию для Bootstrap. Это поможет вам использовать и объединить настройки по умолчанию с вашей собственной конфигурацией. Функция должна возвращать объект конфигурации для Popper.

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

Параметры для таковых могут быть заданы использованием атрибутов, как показано выше.

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

var tooltip = new bootstrap.Tooltip(element, {
  popperConfig: function (defaultBsPopperConfig) {
    // var newPopperConfig = {...}
    // use defaultBsPopperConfig if needed...
    // return newPopperConfig
  }
})

Методы

Асинхронные методы и переходы

Все методы API асинхронны и запускают переход. Они возвращаются функции, вызвавшей их, с началом перехода, но до его конца. Плюс, вызов метода к компоненту, выполняющему переход, будет проигнорирован.

Смотрите документацию.

show

Показывает всплывающую подсказку элемента. Возвращается к функции-вызову до того, как модальный элемент показан (т.е. до того, как произойдет событие shown.bs.tooltip). Расценивается как «мануальный» запуск подсказки. Подсказки с названием нулевой длины никогда не отображаются.

tooltip.show()

hide

Скрывает подсказку элемента. Возвращается к функции-вызову до того, как модальный элемент скрыт (т.е. до того, как произойдет событие hidden.bs.tooltip). Это расценивается «мануальным» запуском подсказки.

tooltip.hide()

toggle

Изменяет состояние подсказки элемента. Возвращается к функции-вызову до того, как модальный элемент показан или скрыт (т.е. до того, как события shown.bs.tooltip or hidden.bs.tooltip наступят). Расценивается как «мануальный» запуск подсказки.

tooltip.toggle()

dispose

Прячет и уничтожает подсказку элемента. Подсказки, которые используют «делегирование» (которые созданы использованием параметра «селектор»), нельзя уничтожить по отдельности на «подчиненных» элементах-триггерах.

tooltip.dispose()

enable

Дает возможность подсказке элемента быть показанной. Подсказки включены по умолчанию.

tooltip.enable()

disable

Лишает подсказку элемента возможности быть показанной. Подсказка будет доступна к показу только если она будет ре-активирована.

tooltip.disable()

toggleEnabled

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

tooltip.toggleEnabled()

update

Обновляет позицию подсказки элемента.

tooltip.update()

getInstance

Static method which allows you to get the tooltip instance associated with a DOM element

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

События

Тип события Описание
show.bs.tooltip Это событие наступает немедленно, когда экземпляр метода show вызван.
shown.bs.tooltip Это событие наступает, когда подсказка стала видимой юзеру (будет ждать завершения переходов CSS).
hide.bs.tooltip Это событие наступает немедленно, когда экземпляр метода hide вызван.
hidden.bs.tooltip Это событие наступает, когда подсказка только что прекратила быть скрытой от юзера (будет ждать завершения переходов CSS).
inserted.bs.tooltip Это событие наступает после события show.bs.tooltip, когда шаблон подсказки добавлен в DOM.
var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)

myTooltipEl.addEventListener('hidden.bs.tooltip', function () {
  // делайте что-нибудь...
})

tooltip.hide()