Cмотреть на GitHub

Подсказки

Документация и примеры добавления настраиваемых всплывающих подсказок 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="Подсказка вверху">
  Подсказка вверху
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="right" title="Подсказка справа">
  Подсказка справа
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="bottom" title="Подсказка снизу">
  Подсказка снизу
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="left" title="Подсказка слева">
  Подсказка слева
</button>

И с добавленным пользовательского HTML:

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

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

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

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

$('#example').tooltip(options)
Переполнение Overflow auto и scroll

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

$('#example').tooltip({ boundary: 'window' })

Разметка

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

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

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

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

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

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

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

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

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

Параметры

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

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

Название Тип Умолчание Описание
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 | function 0

Смещение всплывающей подсказки относительно цели.

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

Дополнительную информацию смотрите документации Popper по смещению.
fallbackPlacement string | array 'flip' Разрешить указать, какую позицию Popper будет использовать при откате. Для получения дополнительной информации смотрите документацию о поведении Popper.
customClass string | function ''

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

Вы также можете передать функцию, которая должна возвращать одну строку, содержащую дополнительные имена классов.
boundary string | element 'scrollParent' Граница ограничения переполнения всплывающей подсказки. Принимает значения 'viewport', 'window', 'scrollParent' или ссылку HTMLElement (только JavaScript). Дополнительную информацию смотрите документацию preventOverflow Popper.
sanitize boolean true Включите или отключите очистку. Если активированы параметры 'template' и 'title', будут очищены.
whiteList object Значение по умолчанию Объект, содержащий разрешенные атрибуты и теги
sanitizeFn null | function null Здесь Вы можете предоставить свою собственную функцию офистки. Это может быть полезно, если Вы предпочитаете использовать специальную библиотеку для выполнения очистки.
popperConfig null | object null Чтобы изменить конфигурацию Popper по умолчанию для Bootstrap, смотрите конфигурацию Popper.

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

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

Методы

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

Все методы 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 () {
  // сделайте что-нибудь...
})