Подсказки

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

Обзор

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

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

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

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

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

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

$(function () {
  $('[data-toggle="tooltip"]').tooltip()
})

Примеры

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

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-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)

Разметка

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

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

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

Кроме того, не полагайтесь только на 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>Кнопка отключения</button>
</span>

Параметры

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

Название Тип Умолчание Описание
animation boolean true Применяет CSS-переход к подсказке
container string | element | false false

Добавляет подсказку к выбранному элементу. Пример: container: 'body'. Эта опция полезна в том, что в потоке документа позволяет позиционировать подсказку рядом с ее триггером - что предотвратит подсказку от «сползания» при изменении размера окна.
delay number | object 0

Откладывает показ и скрытие подсказки (мс) – не применяется к ручному типу триггера

Если цифра поддерживается, задержка применяется к обоим hide/show

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

Позволяет вставлять HTML в подсказку.

Если true, тэги HTML в title подсказки будут отрисованы в подсказке. Если false – метод jQuery text будет использован для вставки содержимого в DOM.

Используйте текст, если вы беспокоитесь о XSS-атаках.
placement string | function 'top'

Как позиционируется всплывающая подсказка – авто – верх – низ – лево – право.
Когда задано auto, это автоматически переориентирует подсказку.

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

Обычный HTML для использования при создании всплывающих подсказок.

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

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

Самый внешний оборачивающий элемент должен иметь класс .tooltip и role="tooltip".
title string | element | function ''

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

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

Задает, как вызывается подсказка - click | hover | focus | manual. Вы можете назначить много триггеров, разделите их пробелом.

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

'hover' сам по себе приведет к созданию подсказок, которые нельзя запустить с клавиатуры, и должны будут использоваться лишь, если другие методы для выдачи информации из подсказки для юзеров клавиатуры невозможны.
offset number | string 0 Отступ подсказки относительно ее цели. Для большей информации иди в документацию отступов Popper.js.
fallbackPlacement string | array 'flip' Позволяет задать, какую позицию Popper.js будет использовать при откате. Для информации - сюда.
boundary string | element 'scrollParent' Граница ограничения overflow подсказки. Принимает значения 'viewport', 'window', 'scrollParent' или отсылку к элементу HTML (только в JavaScript). Для информации – документация по preventOverflow docs.
sanitize boolean true Включить или отключить санацию. Если активированы 'template' и 'title', параметры будут очищены.
whiteList object Default value Объект, который содержит допустимые атрибуты и теги
sanitizeFn null | function null Здесь вы можете предоставить свою собственную функцию очистки. Это может быть полезно, если вы предпочитаете использовать выделенную библиотеку для выполнения очистки.
popperConfig null | object null Чтобы изменить конфигурацию Popper.js по умолчанию в Bootstrap, смотрите Конфигурацию Popper.js.

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

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

Методы

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

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

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

$().tooltip(options)

Прикрепляет обработчик подсказки к коллекции элементов.

.tooltip('show')

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

$('#element').tooltip('show')

.tooltip('hide')

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

$('#element').tooltip('hide')

.tooltip('toggle')

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

$('#element').tooltip('toggle')

.tooltip('dispose')

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

$('#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 вызван.
shown.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…
})